1use std::fmt;
53
54use serde::{Deserialize, Serialize};
55use serde_json::{json, Value};
56
57use crate::codes::Code;
58use crate::error::{Error, Fault};
59use crate::host;
60
61const UPLOAD_EXTERNAL: &str = "action:storage/upload-external";
63
64#[derive(Clone, Debug, Default, Deserialize, Serialize, PartialEq, Eq)]
70pub struct DocumentHandle {
71 pub file_hash: String,
73 pub filename: String,
75 pub mime_type: String,
77 pub size: u64,
79 pub storage_path: String,
81}
82
83#[derive(Clone, Debug, Default, Deserialize, Serialize, PartialEq, Eq)]
85pub struct Target {
86 pub app_id: String,
88 pub table_name: String,
90 pub field_name: String,
92}
93
94impl Target {
95 pub fn new(
105 app_id: impl Into<String>,
106 table_name: impl Into<String>,
107 field_name: impl Into<String>,
108 ) -> Target {
109 Target {
110 app_id: app_id.into(),
111 table_name: table_name.into(),
112 field_name: field_name.into(),
113 }
114 }
115}
116
117#[non_exhaustive]
122#[derive(Clone, Serialize)]
123#[serde(tag = "type", rename_all = "lowercase")]
124pub enum Auth {
125 Basic {
127 username: String,
129 password: String,
131 },
132 Bearer {
134 bearer_token: String,
136 },
137}
138
139impl Auth {
140 pub fn bearer(bearer_token: impl Into<String>) -> Auth {
150 Auth::Bearer {
151 bearer_token: bearer_token.into(),
152 }
153 }
154
155 pub fn basic(username: impl Into<String>, password: impl Into<String>) -> Auth {
157 Auth::Basic {
158 username: username.into(),
159 password: password.into(),
160 }
161 }
162}
163
164impl fmt::Debug for Auth {
165 fn fmt(&self, formatter: &mut fmt::Formatter<'_>) -> fmt::Result {
177 match self {
178 Auth::Basic { username, .. } => formatter
179 .debug_struct("Basic")
180 .field("username", username)
181 .finish_non_exhaustive(),
182 Auth::Bearer { .. } => formatter.debug_struct("Bearer").finish_non_exhaustive(),
183 }
184 }
185}
186
187#[derive(Clone, Debug, Serialize)]
189pub struct Source {
190 pub url: String,
192 #[serde(skip_serializing_if = "Option::is_none")]
194 pub auth: Option<Auth>,
195}
196
197impl Source {
198 pub fn url(url: impl Into<String>) -> Source {
200 Source {
201 url: url.into(),
202 auth: None,
203 }
204 }
205
206 pub fn with_auth(mut self, auth: Auth) -> Source {
216 self.auth = Some(auth);
217 self
218 }
219}
220
221pub fn upload_buffer(
253 bytes: &[u8],
254 filename: &str,
255 mime_type: &str,
256 target: Target,
257) -> Result<DocumentHandle, Error> {
258 if bytes.is_empty() {
259 return Err(
260 Error::invalid("An upload needs at least one byte, and this buffer is empty.")
261 .hint("Pass the file's contents."),
262 );
263 }
264
265 if filename.trim().is_empty() {
266 return Err(Error::invalid("An upload needs a filename.")
267 .hint("Pass the name the file is stored under, such as report.pdf."));
268 }
269
270 if mime_type.trim().is_empty() {
271 return Err(Error::invalid("An upload needs a media type.")
272 .hint("Pass the type of the contents, such as application/pdf."));
273 }
274
275 check_target(&target)?;
276
277 let source = json!({
278 "bytes": encode(bytes),
279 "filename": filename,
280 "mime_type": mime_type,
281 });
282
283 send(source, target)
284}
285
286pub fn upload_external(source: Source, target: Target) -> Result<DocumentHandle, Error> {
315 if source.url.trim().is_empty() {
316 return Err(
317 Error::invalid("An external upload needs a URL to read from.")
318 .hint("Pass the address of the file, or use upload_buffer for bytes you hold."),
319 );
320 }
321
322 if let Some(auth) = &source.auth {
323 check_auth(auth)?;
324 }
325
326 check_target(&target)?;
327
328 send(serde_json::to_value(&source)?, target)
329}
330
331fn send(source: Value, target: Target) -> Result<DocumentHandle, Error> {
333 let params = json!({ "source": source, "target": serde_json::to_value(&target)? });
334
335 let stored = host::transport()?
336 .call(UPLOAD_EXTERNAL.to_string(), params)
337 .map_err(|cause| {
338 Error::Host(Fault::new(Code::unspecified(), cause.message())).hint(
339 "Nothing was attached to the record. The store is addressed by content, \
340 so the same bytes uploaded again answer with the same handle.",
341 )
342 })?;
343
344 serde_json::from_value(stored).map_err(|cause| {
345 Error::Json(Fault::new(
346 Code::unspecified(),
347 format!("The upload finished and its handle could not be read: {cause}"),
348 ))
349 .hint(
350 "Report this. The file is stored under the hash of its contents, \
351 so uploading the same bytes again answers with the handle.",
352 )
353 })
354}
355
356fn check_target(target: &Target) -> Result<(), Error> {
358 let named = [
359 ("app_id", &target.app_id),
360 ("table_name", &target.table_name),
361 ("field_name", &target.field_name),
362 ];
363
364 for (member, value) in named {
365 if value.trim().is_empty() {
366 return Err(Error::invalid(format!("A storage target needs {member}."))
367 .hint("Name the app, the table, and the :document field the handle goes in."));
368 }
369 }
370
371 Ok(())
372}
373
374fn check_auth(auth: &Auth) -> Result<(), Error> {
379 match auth {
380 Auth::Basic { username, password } => {
381 if username.trim().is_empty() {
382 return Err(Error::invalid("Basic authentication needs a username.")
383 .hint("Pass the username, or read the URL without a credential."));
384 }
385
386 if password.trim().is_empty() {
387 return Err(Error::invalid("Basic authentication needs a password.")
388 .hint("Pass the password, or read the URL without a credential."));
389 }
390 }
391 Auth::Bearer { bearer_token } => {
392 if bearer_token.trim().is_empty() {
393 return Err(Error::invalid("Bearer authentication needs a token.")
394 .hint("Pass the token, or read the URL without a credential."));
395 }
396 }
397 }
398
399 Ok(())
400}
401
402const ALPHABET: &[u8; 64] = b"ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz0123456789+/";
404
405const PAD: char = '=';
407
408fn encode(bytes: &[u8]) -> String {
411 let mut encoded = String::with_capacity(bytes.len().div_ceil(3) * 4);
412
413 for group in bytes.chunks(3) {
414 let mut packed = 0_u32;
415
416 for (index, byte) in group.iter().enumerate() {
419 packed |= u32::from(*byte) << (16 - 8 * index);
420 }
421
422 encoded.push(symbol(packed >> 18));
423 encoded.push(symbol(packed >> 12));
424 encoded.push(if group.len() > 1 {
425 symbol(packed >> 6)
426 } else {
427 PAD
428 });
429 encoded.push(if group.len() > 2 { symbol(packed) } else { PAD });
430 }
431
432 encoded
433}
434
435fn symbol(packed: u32) -> char {
437 char::from(ALPHABET[(packed & 0b11_1111) as usize])
440}
441
442#[cfg(test)]
443mod tests {
444 use serde_json::json;
445
446 use super::*;
447 use crate::testing;
448
449 fn stored() -> Value {
451 json!({
452 "file_hash": "c3ab8ff13720e8ad9047dd39466b3c89",
453 "filename": "report.pdf",
454 "mime_type": "application/pdf",
455 "size": 6,
456 "storage_path": "documents/c3/ab/c3ab8ff13720e8ad9047dd39466b3c89",
457 })
458 }
459
460 fn target() -> Target {
461 Target::new("dev.simple.system", "documents", "attachment")
462 }
463
464 #[test]
465 fn a_buffer_travels_base64_encoded_beside_its_name_and_type() {
466 let session = testing::install(|_name, _params| Ok(stored()));
467
468 upload_buffer(b"foobar", "report.pdf", "application/pdf", target()).unwrap();
469
470 let calls = session.calls();
471
472 assert_eq!(calls.len(), 1);
473 assert_eq!(calls[0].name, "action:storage/upload-external");
474 assert_eq!(
475 calls[0].params["source"],
476 json!({
477 "bytes": "Zm9vYmFy",
478 "filename": "report.pdf",
479 "mime_type": "application/pdf",
480 })
481 );
482 assert_eq!(
483 calls[0].params["target"],
484 json!({
485 "app_id": "dev.simple.system",
486 "table_name": "documents",
487 "field_name": "attachment",
488 })
489 );
490 }
491
492 #[test]
493 fn a_stored_file_answers_with_every_member_of_its_handle() {
494 let _session = testing::install(|_name, _params| Ok(stored()));
495
496 let handle = upload_buffer(b"foobar", "report.pdf", "application/pdf", target()).unwrap();
497
498 assert_eq!(
499 handle,
500 DocumentHandle {
501 file_hash: "c3ab8ff13720e8ad9047dd39466b3c89".to_string(),
502 filename: "report.pdf".to_string(),
503 mime_type: "application/pdf".to_string(),
504 size: 6,
505 storage_path: "documents/c3/ab/c3ab8ff13720e8ad9047dd39466b3c89".to_string(),
506 }
507 );
508 }
509
510 #[test]
511 fn an_empty_buffer_is_refused_before_anything_is_sent() {
512 let session = testing::install(|_name, _params| Ok(stored()));
513
514 let error = upload_buffer(&[], "report.pdf", "application/pdf", target()).unwrap_err();
515
516 assert_eq!(error.code().as_str(), "INVALID_TOOL_INPUT");
517 assert!(session.calls().is_empty());
518 }
519
520 #[test]
521 fn a_blank_name_or_type_is_refused_before_anything_is_sent() {
522 let session = testing::install(|_name, _params| Ok(stored()));
523
524 for (filename, mime_type) in [(" ", "application/pdf"), ("report.pdf", "")] {
525 let error = upload_buffer(b"foobar", filename, mime_type, target()).unwrap_err();
526
527 assert_eq!(error.code().as_str(), "INVALID_TOOL_INPUT");
528 }
529
530 assert!(session.calls().is_empty());
531 }
532
533 #[test]
534 fn a_target_missing_a_member_names_the_one_it_is_missing() {
535 let session = testing::install(|_name, _params| Ok(stored()));
536
537 let incomplete = [
538 (Target::new("", "documents", "attachment"), "app_id"),
539 (
540 Target::new("dev.simple.system", " ", "attachment"),
541 "table_name",
542 ),
543 (
544 Target::new("dev.simple.system", "documents", ""),
545 "field_name",
546 ),
547 ];
548
549 for (target, member) in incomplete {
550 let error = upload_buffer(b"foobar", "report.pdf", "application/pdf", target)
551 .expect_err("an incomplete target names nothing to attach to");
552
553 assert_eq!(error.code().as_str(), "INVALID_TOOL_INPUT");
554 assert!(error.message().contains(member), "{}", error.message());
555 }
556
557 assert!(session.calls().is_empty());
558 }
559
560 #[test]
561 fn a_url_upload_carries_the_url_alone_when_it_needs_no_credential() {
562 let session = testing::install(|_name, _params| Ok(stored()));
563
564 upload_external(Source::url("https://example.com/report.pdf"), target()).unwrap();
565
566 assert_eq!(
567 session.calls()[0].params["source"],
568 json!({ "url": "https://example.com/report.pdf" }),
569 "a source with no credential carries no auth member"
570 );
571 }
572
573 #[test]
574 fn a_credential_travels_under_its_own_scheme() {
575 let session = testing::install(|_name, _params| Ok(stored()));
576
577 upload_external(
578 Source::url("https://example.com/report.pdf").with_auth(Auth::bearer("t-1234")),
579 target(),
580 )
581 .unwrap();
582
583 upload_external(
584 Source::url("https://example.com/report.pdf").with_auth(Auth::basic("ada", "s3cret")),
585 target(),
586 )
587 .unwrap();
588
589 let calls = session.calls();
590
591 assert_eq!(
592 calls[0].params["source"]["auth"],
593 json!({ "type": "bearer", "bearer_token": "t-1234" })
594 );
595 assert_eq!(
596 calls[1].params["source"]["auth"],
597 json!({ "type": "basic", "username": "ada", "password": "s3cret" })
598 );
599 }
600
601 #[test]
602 fn a_blank_url_is_refused_before_anything_is_sent() {
603 let session = testing::install(|_name, _params| Ok(stored()));
604
605 let error = upload_external(Source::url(" "), target()).unwrap_err();
606
607 assert_eq!(error.code().as_str(), "INVALID_TOOL_INPUT");
608 assert!(session.calls().is_empty());
609 }
610
611 #[test]
612 fn a_credential_with_nothing_in_it_is_refused_before_anything_is_sent() {
613 let session = testing::install(|_name, _params| Ok(stored()));
614
615 let blank = [
616 Auth::bearer(" "),
617 Auth::basic("", "s3cret"),
618 Auth::basic("ada", " "),
619 ];
620
621 for auth in blank {
622 let error = upload_external(
623 Source::url("https://example.com/report.pdf").with_auth(auth),
624 target(),
625 )
626 .expect_err("a credential that says nothing cannot read the URL");
627
628 assert_eq!(error.code().as_str(), "INVALID_TOOL_INPUT");
629 }
630
631 assert!(session.calls().is_empty());
632 }
633
634 #[test]
635 fn a_refused_upload_keeps_the_hosts_own_message() {
636 let _session = testing::install(|_name, _params| Err(Error::failed("the store is full")));
637
638 let error =
639 upload_buffer(b"foobar", "report.pdf", "application/pdf", target()).unwrap_err();
640
641 assert!(matches!(error, Error::Host(_)));
642 assert!(error.message().contains("the store is full"));
643 assert!(!error.is_retryable());
644 }
645
646 #[test]
647 fn a_handle_that_cannot_be_read_is_reported_rather_than_returned() {
648 let _session = testing::install(|_name, _params| Ok(json!({ "filename": "report.pdf" })));
649
650 let error =
651 upload_buffer(b"foobar", "report.pdf", "application/pdf", target()).unwrap_err();
652
653 assert!(matches!(error, Error::Json(_)));
654 assert!(error.message().contains("could not be read"));
655 }
656
657 #[test]
658 fn an_upload_with_no_host_to_send_it_to_says_so() {
659 let error =
660 upload_buffer(b"foobar", "report.pdf", "application/pdf", target()).unwrap_err();
661
662 assert!(error.message().contains("No host is installed"));
663 }
664
665 #[test]
667 fn bytes_encode_to_the_standard_alphabet_with_standard_padding() {
668 assert_eq!(encode(b""), "");
669 assert_eq!(encode(b"f"), "Zg==");
670 assert_eq!(encode(b"fo"), "Zm8=");
671 assert_eq!(encode(b"foo"), "Zm9v");
672 assert_eq!(encode(b"foob"), "Zm9vYg==");
673 assert_eq!(encode(b"fooba"), "Zm9vYmE=");
674 assert_eq!(encode(b"foobar"), "Zm9vYmFy");
675 }
676
677 #[test]
678 fn the_last_two_symbols_of_the_alphabet_are_plus_and_slash() {
679 assert_eq!(encode(&[0xfb, 0xff]), "+/8=");
680 assert_eq!(encode(&[0xff, 0xff, 0xff]), "////");
681 assert_eq!(encode(&[0x00, 0x00, 0x00]), "AAAA");
682 }
683
684 #[test]
685 fn every_byte_value_survives_the_encoding() {
686 let every: Vec<u8> = (0..=255).collect();
687 let encoded = encode(&every);
688
689 assert_eq!(encoded.len(), 344, "256 bytes fill 86 groups of four");
690 assert!(encoded.ends_with("/w=="));
691 assert!(encoded
692 .chars()
693 .all(|symbol| symbol == PAD || ALPHABET.contains(&(symbol as u8))));
694 }
695
696 #[test]
697 fn a_credential_is_not_written_out_by_a_debug_rendering() {
698 let source =
699 Source::url("https://example.com/report.pdf").with_auth(Auth::bearer("t-1234"));
700
701 let rendered = format!("{source:?}");
702
703 assert!(!rendered.contains("t-1234"));
704 assert!(rendered.contains("Bearer"));
705
706 let basic = format!("{:?}", Auth::basic("ada", "s3cret"));
707
708 assert!(!basic.contains("s3cret"));
709 assert!(basic.contains("ada"));
710 }
711}