Skip to main content

shardline_s3_adapter/
lib.rs

1#![deny(unsafe_code)]
2
3//! S3-compatible protocol adapter for the Shardline server ecosystem.
4//!
5//! This crate provides the S3 frontend's protocol primitives:
6//!
7//! - bucket (`{owner}.{name}`) encoding and decoding and the storage
8//!   object-key layout (`protocols/s3/{scope_namespace}/{key}`) — [`S3ObjectKey`];
9//! - the S3 XML wire models and error envelope — [`ListBucketResult`] and
10//!   [`S3Error`];
11//! - the SigV4 → bearer-token auth bridge and bucket-scope binding —
12//!   [`AuthScheme`] and [`CredentialScope`];
13//! - the query-param sub-resource dispatch set, ETag formatting, and byte-range
14//!   parsing — [`S3SubResource`] and [`parse_s3_range`].
15//!
16//! # Quick start
17//!
18//! ```
19//! use shardline_s3_adapter::{decode_bucket, encode_bucket, s3_object_key};
20//!
21//! // A bucket is the single dotted segment `{owner}.{name}` of the token scope.
22//! let bucket = encode_bucket("acme", "models");
23//! assert_eq!(
24//!     decode_bucket(&bucket)?,
25//!     ("acme".to_owned(), "models".to_owned())
26//! );
27//!
28//! // Object keys live under the `protocols/s3/{scope_namespace}/` prefix.
29//! let key = s3_object_key("global", "data/model.pt")?;
30//! assert_eq!(key.as_str(), "protocols/s3/global/data/model.pt");
31//!
32//! // Errors serialize to the S3 XML envelope with the correct status.
33//! use axum::response::IntoResponse;
34//! let response = shardline_s3_adapter::S3Error::no_such_key("data/model.pt")
35//!     .into_response();
36//! assert_eq!(response.status(), 404);
37//! # Ok::<(), Box<dyn std::error::Error>>(())
38//! ```
39
40mod auth;
41mod error;
42mod key;
43mod listing;
44mod multipart;
45mod protocol_support;
46mod sigv4;
47mod types;
48mod wire_conditions;
49
50pub use wire_conditions::{WireConditionalHeader, read_wire_conditional_headers};
51
52pub use auth::{
53    AuthScheme, CredentialScope, QueryCredential, extract_access_key,
54    extract_access_key_from_query, require_s3_bucket_binding,
55};
56pub use error::{S3Error, S3ErrorClass, S3ErrorClassify};
57pub use key::{
58    BucketDecodeError, S3KeyError, S3ObjectKey, decode_bucket, encode_bucket, s3_object_key,
59};
60pub use listing::{
61    Delimiter, ListObjectsV1Params, ListObjectsV2Params, ListPage, MAX_LIST_KEYS,
62    decode_continuation_token, encode_continuation_token, format_iso8601, group_page,
63    parse_list_objects_url_encoding, parse_list_objects_v1_params, parse_list_objects_v2_params,
64};
65pub use multipart::{
66    MAX_S3_PART_NUMBER, MultipartPart, MultipartUploadSession, PartQuotaLimits, S3SessionError,
67    S3SessionPartFileLock, S3UploadSessionLock, acquire_session_part_lock,
68    acquire_session_part_lock_for_root, count_active_sessions, create_session, delete_session,
69    delete_session_locked, is_expired, list_bucket_sessions, lock_session_parts,
70    lock_upload_sessions, new_upload_id, part_file_path, read_session, read_session_locked,
71    repair_session_evidence, session_dir, session_metadata_path, store_part, store_part_locked,
72    store_versioned_part_locked, store_versioned_part_with_checksum_locked, stored_part_file_path,
73    sweep_expired_sessions, upload_dir, validate_part_number,
74    validate_part_quota_for_session_locked, validate_part_quota_locked, validate_upload_id,
75    versioned_part_file_name, visit_bucket_sessions,
76};
77pub use protocol_support::{
78    ConditionalHeader, CopySource, EntityTag, EntityTagSet, InvalidS3HeaderValue, QueryMap,
79    S3SubResource, classify, etag_header, parse_content_md5, parse_copy_source, parse_s3_range,
80    parse_subresource, read_conditional_headers,
81};
82pub use sigv4::{
83    SigV4ChunkVerifier, SigV4Credential, SigV4PostPolicyAuth, VerifiedSigV4,
84    VerifiedSigV4PostPolicy, verify_sigv4, verify_sigv4_post_policy,
85};
86pub use types::{
87    CompleteMultipartUploadResult, CompleteParts, Contents, CopyObjectResult, HeadObjectHeaders,
88    InitiateMultipartUploadResult, ListBucketResult, ListBucketResultV1, ListBucketsResult,
89    ListObjectsV2ResponseContext, MAX_S3_DELETE_KEYS, PutObjectResponseHeaders, S3ErrorBody,
90    parse_complete_multipart_parts, parse_delete_object_keys, xml_escape,
91};