use std::fmt;
use serde::{Deserialize, Serialize};
use serde_json::{json, Value};
use crate::codes::Code;
use crate::error::{Error, Fault};
use crate::host;
const UPLOAD_EXTERNAL: &str = "action:storage/upload-external";
#[derive(Clone, Debug, Default, Deserialize, Serialize, PartialEq, Eq)]
pub struct DocumentHandle {
pub file_hash: String,
pub filename: String,
pub mime_type: String,
pub size: u64,
pub storage_path: String,
}
#[derive(Clone, Debug, Default, Deserialize, Serialize, PartialEq, Eq)]
pub struct Target {
pub app_id: String,
pub table_name: String,
pub field_name: String,
}
impl Target {
pub fn new(
app_id: impl Into<String>,
table_name: impl Into<String>,
field_name: impl Into<String>,
) -> Target {
Target {
app_id: app_id.into(),
table_name: table_name.into(),
field_name: field_name.into(),
}
}
}
#[non_exhaustive]
#[derive(Clone, Serialize)]
#[serde(tag = "type", rename_all = "lowercase")]
pub enum Auth {
Basic {
username: String,
password: String,
},
Bearer {
bearer_token: String,
},
}
impl Auth {
pub fn bearer(bearer_token: impl Into<String>) -> Auth {
Auth::Bearer {
bearer_token: bearer_token.into(),
}
}
pub fn basic(username: impl Into<String>, password: impl Into<String>) -> Auth {
Auth::Basic {
username: username.into(),
password: password.into(),
}
}
}
impl fmt::Debug for Auth {
fn fmt(&self, formatter: &mut fmt::Formatter<'_>) -> fmt::Result {
match self {
Auth::Basic { username, .. } => formatter
.debug_struct("Basic")
.field("username", username)
.finish_non_exhaustive(),
Auth::Bearer { .. } => formatter.debug_struct("Bearer").finish_non_exhaustive(),
}
}
}
#[derive(Clone, Debug, Serialize)]
pub struct Source {
pub url: String,
#[serde(skip_serializing_if = "Option::is_none")]
pub auth: Option<Auth>,
}
impl Source {
pub fn url(url: impl Into<String>) -> Source {
Source {
url: url.into(),
auth: None,
}
}
pub fn with_auth(mut self, auth: Auth) -> Source {
self.auth = Some(auth);
self
}
}
pub fn upload_buffer(
bytes: &[u8],
filename: &str,
mime_type: &str,
target: Target,
) -> Result<DocumentHandle, Error> {
if bytes.is_empty() {
return Err(
Error::invalid("An upload needs at least one byte, and this buffer is empty.")
.hint("Pass the file's contents."),
);
}
if filename.trim().is_empty() {
return Err(Error::invalid("An upload needs a filename.")
.hint("Pass the name the file is stored under, such as report.pdf."));
}
if mime_type.trim().is_empty() {
return Err(Error::invalid("An upload needs a media type.")
.hint("Pass the type of the contents, such as application/pdf."));
}
check_target(&target)?;
let source = json!({
"bytes": encode(bytes),
"filename": filename,
"mime_type": mime_type,
});
send(source, target)
}
pub fn upload_external(source: Source, target: Target) -> Result<DocumentHandle, Error> {
if source.url.trim().is_empty() {
return Err(
Error::invalid("An external upload needs a URL to read from.")
.hint("Pass the address of the file, or use upload_buffer for bytes you hold."),
);
}
if let Some(auth) = &source.auth {
check_auth(auth)?;
}
check_target(&target)?;
send(serde_json::to_value(&source)?, target)
}
fn send(source: Value, target: Target) -> Result<DocumentHandle, Error> {
let params = json!({ "source": source, "target": serde_json::to_value(&target)? });
let stored = host::transport()?
.call(UPLOAD_EXTERNAL.to_string(), params)
.map_err(|cause| {
Error::Host(Fault::new(Code::unspecified(), cause.message())).hint(
"Nothing was attached to the record. The store is addressed by content, \
so the same bytes uploaded again answer with the same handle.",
)
})?;
serde_json::from_value(stored).map_err(|cause| {
Error::Json(Fault::new(
Code::unspecified(),
format!("The upload finished and its handle could not be read: {cause}"),
))
.hint(
"Report this. The file is stored under the hash of its contents, \
so uploading the same bytes again answers with the handle.",
)
})
}
fn check_target(target: &Target) -> Result<(), Error> {
let named = [
("app_id", &target.app_id),
("table_name", &target.table_name),
("field_name", &target.field_name),
];
for (member, value) in named {
if value.trim().is_empty() {
return Err(Error::invalid(format!("A storage target needs {member}."))
.hint("Name the app, the table, and the :document field the handle goes in."));
}
}
Ok(())
}
fn check_auth(auth: &Auth) -> Result<(), Error> {
match auth {
Auth::Basic { username, password } => {
if username.trim().is_empty() {
return Err(Error::invalid("Basic authentication needs a username.")
.hint("Pass the username, or read the URL without a credential."));
}
if password.trim().is_empty() {
return Err(Error::invalid("Basic authentication needs a password.")
.hint("Pass the password, or read the URL without a credential."));
}
}
Auth::Bearer { bearer_token } => {
if bearer_token.trim().is_empty() {
return Err(Error::invalid("Bearer authentication needs a token.")
.hint("Pass the token, or read the URL without a credential."));
}
}
}
Ok(())
}
const ALPHABET: &[u8; 64] = b"ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz0123456789+/";
const PAD: char = '=';
fn encode(bytes: &[u8]) -> String {
let mut encoded = String::with_capacity(bytes.len().div_ceil(3) * 4);
for group in bytes.chunks(3) {
let mut packed = 0_u32;
for (index, byte) in group.iter().enumerate() {
packed |= u32::from(*byte) << (16 - 8 * index);
}
encoded.push(symbol(packed >> 18));
encoded.push(symbol(packed >> 12));
encoded.push(if group.len() > 1 {
symbol(packed >> 6)
} else {
PAD
});
encoded.push(if group.len() > 2 { symbol(packed) } else { PAD });
}
encoded
}
fn symbol(packed: u32) -> char {
char::from(ALPHABET[(packed & 0b11_1111) as usize])
}
#[cfg(test)]
mod tests {
use serde_json::json;
use super::*;
use crate::testing;
fn stored() -> Value {
json!({
"file_hash": "c3ab8ff13720e8ad9047dd39466b3c89",
"filename": "report.pdf",
"mime_type": "application/pdf",
"size": 6,
"storage_path": "documents/c3/ab/c3ab8ff13720e8ad9047dd39466b3c89",
})
}
fn target() -> Target {
Target::new("dev.simple.system", "documents", "attachment")
}
#[test]
fn a_buffer_travels_base64_encoded_beside_its_name_and_type() {
let session = testing::install(|_name, _params| Ok(stored()));
upload_buffer(b"foobar", "report.pdf", "application/pdf", target()).unwrap();
let calls = session.calls();
assert_eq!(calls.len(), 1);
assert_eq!(calls[0].name, "action:storage/upload-external");
assert_eq!(
calls[0].params["source"],
json!({
"bytes": "Zm9vYmFy",
"filename": "report.pdf",
"mime_type": "application/pdf",
})
);
assert_eq!(
calls[0].params["target"],
json!({
"app_id": "dev.simple.system",
"table_name": "documents",
"field_name": "attachment",
})
);
}
#[test]
fn a_stored_file_answers_with_every_member_of_its_handle() {
let _session = testing::install(|_name, _params| Ok(stored()));
let handle = upload_buffer(b"foobar", "report.pdf", "application/pdf", target()).unwrap();
assert_eq!(
handle,
DocumentHandle {
file_hash: "c3ab8ff13720e8ad9047dd39466b3c89".to_string(),
filename: "report.pdf".to_string(),
mime_type: "application/pdf".to_string(),
size: 6,
storage_path: "documents/c3/ab/c3ab8ff13720e8ad9047dd39466b3c89".to_string(),
}
);
}
#[test]
fn an_empty_buffer_is_refused_before_anything_is_sent() {
let session = testing::install(|_name, _params| Ok(stored()));
let error = upload_buffer(&[], "report.pdf", "application/pdf", target()).unwrap_err();
assert_eq!(error.code().as_str(), "INVALID_TOOL_INPUT");
assert!(session.calls().is_empty());
}
#[test]
fn a_blank_name_or_type_is_refused_before_anything_is_sent() {
let session = testing::install(|_name, _params| Ok(stored()));
for (filename, mime_type) in [(" ", "application/pdf"), ("report.pdf", "")] {
let error = upload_buffer(b"foobar", filename, mime_type, target()).unwrap_err();
assert_eq!(error.code().as_str(), "INVALID_TOOL_INPUT");
}
assert!(session.calls().is_empty());
}
#[test]
fn a_target_missing_a_member_names_the_one_it_is_missing() {
let session = testing::install(|_name, _params| Ok(stored()));
let incomplete = [
(Target::new("", "documents", "attachment"), "app_id"),
(
Target::new("dev.simple.system", " ", "attachment"),
"table_name",
),
(
Target::new("dev.simple.system", "documents", ""),
"field_name",
),
];
for (target, member) in incomplete {
let error = upload_buffer(b"foobar", "report.pdf", "application/pdf", target)
.expect_err("an incomplete target names nothing to attach to");
assert_eq!(error.code().as_str(), "INVALID_TOOL_INPUT");
assert!(error.message().contains(member), "{}", error.message());
}
assert!(session.calls().is_empty());
}
#[test]
fn a_url_upload_carries_the_url_alone_when_it_needs_no_credential() {
let session = testing::install(|_name, _params| Ok(stored()));
upload_external(Source::url("https://example.com/report.pdf"), target()).unwrap();
assert_eq!(
session.calls()[0].params["source"],
json!({ "url": "https://example.com/report.pdf" }),
"a source with no credential carries no auth member"
);
}
#[test]
fn a_credential_travels_under_its_own_scheme() {
let session = testing::install(|_name, _params| Ok(stored()));
upload_external(
Source::url("https://example.com/report.pdf").with_auth(Auth::bearer("t-1234")),
target(),
)
.unwrap();
upload_external(
Source::url("https://example.com/report.pdf").with_auth(Auth::basic("ada", "s3cret")),
target(),
)
.unwrap();
let calls = session.calls();
assert_eq!(
calls[0].params["source"]["auth"],
json!({ "type": "bearer", "bearer_token": "t-1234" })
);
assert_eq!(
calls[1].params["source"]["auth"],
json!({ "type": "basic", "username": "ada", "password": "s3cret" })
);
}
#[test]
fn a_blank_url_is_refused_before_anything_is_sent() {
let session = testing::install(|_name, _params| Ok(stored()));
let error = upload_external(Source::url(" "), target()).unwrap_err();
assert_eq!(error.code().as_str(), "INVALID_TOOL_INPUT");
assert!(session.calls().is_empty());
}
#[test]
fn a_credential_with_nothing_in_it_is_refused_before_anything_is_sent() {
let session = testing::install(|_name, _params| Ok(stored()));
let blank = [
Auth::bearer(" "),
Auth::basic("", "s3cret"),
Auth::basic("ada", " "),
];
for auth in blank {
let error = upload_external(
Source::url("https://example.com/report.pdf").with_auth(auth),
target(),
)
.expect_err("a credential that says nothing cannot read the URL");
assert_eq!(error.code().as_str(), "INVALID_TOOL_INPUT");
}
assert!(session.calls().is_empty());
}
#[test]
fn a_refused_upload_keeps_the_hosts_own_message() {
let _session = testing::install(|_name, _params| Err(Error::failed("the store is full")));
let error =
upload_buffer(b"foobar", "report.pdf", "application/pdf", target()).unwrap_err();
assert!(matches!(error, Error::Host(_)));
assert!(error.message().contains("the store is full"));
assert!(!error.is_retryable());
}
#[test]
fn a_handle_that_cannot_be_read_is_reported_rather_than_returned() {
let _session = testing::install(|_name, _params| Ok(json!({ "filename": "report.pdf" })));
let error =
upload_buffer(b"foobar", "report.pdf", "application/pdf", target()).unwrap_err();
assert!(matches!(error, Error::Json(_)));
assert!(error.message().contains("could not be read"));
}
#[test]
fn an_upload_with_no_host_to_send_it_to_says_so() {
let error =
upload_buffer(b"foobar", "report.pdf", "application/pdf", target()).unwrap_err();
assert!(error.message().contains("No host is installed"));
}
#[test]
fn bytes_encode_to_the_standard_alphabet_with_standard_padding() {
assert_eq!(encode(b""), "");
assert_eq!(encode(b"f"), "Zg==");
assert_eq!(encode(b"fo"), "Zm8=");
assert_eq!(encode(b"foo"), "Zm9v");
assert_eq!(encode(b"foob"), "Zm9vYg==");
assert_eq!(encode(b"fooba"), "Zm9vYmE=");
assert_eq!(encode(b"foobar"), "Zm9vYmFy");
}
#[test]
fn the_last_two_symbols_of_the_alphabet_are_plus_and_slash() {
assert_eq!(encode(&[0xfb, 0xff]), "+/8=");
assert_eq!(encode(&[0xff, 0xff, 0xff]), "////");
assert_eq!(encode(&[0x00, 0x00, 0x00]), "AAAA");
}
#[test]
fn every_byte_value_survives_the_encoding() {
let every: Vec<u8> = (0..=255).collect();
let encoded = encode(&every);
assert_eq!(encoded.len(), 344, "256 bytes fill 86 groups of four");
assert!(encoded.ends_with("/w=="));
assert!(encoded
.chars()
.all(|symbol| symbol == PAD || ALPHABET.contains(&(symbol as u8))));
}
#[test]
fn a_credential_is_not_written_out_by_a_debug_rendering() {
let source =
Source::url("https://example.com/report.pdf").with_auth(Auth::bearer("t-1234"));
let rendered = format!("{source:?}");
assert!(!rendered.contains("t-1234"));
assert!(rendered.contains("Bearer"));
let basic = format!("{:?}", Auth::basic("ada", "s3cret"));
assert!(!basic.contains("s3cret"));
assert!(basic.contains("ada"));
}
}