Skip to main content

shardline_oci_adapter/
lib.rs

1#![deny(unsafe_code)]
2
3//! OCI Distribution protocol adapter for the Shardline server ecosystem.
4//!
5//! This crate provides OCI registry protocol support: upload session management,
6//! manifest and blob key construction, content-addressed storage helpers, and
7//! S3 multipart upload orchestration.
8//!
9//! # Quick start
10//!
11//! The reference and key helpers are pure and are the easiest place to start:
12//!
13//! ```
14//! use shardline_oci_adapter::{OciReference, parse_reference, validate_repository};
15//!
16//! // A reference is either a `sha256:` digest or a tag.
17//! let digest = parse_reference(
18//!     "sha256:0123456789abcdef0123456789abcdef0123456789abcdef0123456789abcdef",
19//! )?;
20//! assert!(matches!(digest, OciReference::Digest(_)));
21//!
22//! let tag = parse_reference("v1.2.3")?;
23//! assert!(matches!(tag, OciReference::Tag(_)));
24//!
25//! // Repository names follow OCI naming rules.
26//! assert!(validate_repository("acme/models").is_ok());
27//! assert!(validate_repository("Acme/Models").is_err());
28//! # Ok::<(), Box<dyn std::error::Error>>(())
29//! ```
30//!
31//! `oci_*_key` functions map those references to validated storage
32//! [`ObjectKey`](shardline_storage::ObjectKey) values:
33//!
34//! ```
35//! use shardline_oci_adapter::oci_blob_key;
36//!
37//! let key = oci_blob_key(
38//!     "acme/models",
39//!     "0123456789abcdef0123456789abcdef0123456789abcdef0123456789abcdef",
40//!     None,
41//! )?;
42//! assert!(key.as_str().starts_with("protocols/oci/"));
43//! assert!(key.as_str().ends_with(
44//!     "0123456789abcdef0123456789abcdef0123456789abcdef0123456789abcdef"
45//! ));
46//! # Ok::<(), Box<dyn std::error::Error>>(())
47//! ```
48
49mod error;
50mod protocol_support;
51mod traits;
52
53mod fs;
54mod key;
55mod multipart;
56mod session;
57mod types;
58
59#[cfg(test)]
60mod tests;
61
62pub use error::OciAdapterError;
63pub use traits::OciBackend;
64
65// ── Re-exports ───────────────────────────────────────────────────────────────
66
67pub use types::{
68    OciReference, OciS3MultipartUploadSession, OciUploadSession, OciUploadSessionLock,
69    SerializableSha256State,
70};
71
72pub use key::{
73    oci_blob_key, oci_blob_key_from_namespace, oci_blob_location, oci_manifest_key,
74    oci_manifest_key_from_namespace, oci_manifest_location, oci_manifest_media_type_key,
75    oci_manifest_media_type_key_from_namespace, oci_manifest_prefix, oci_tag_key, oci_tag_prefix,
76    oci_tag_target_key, oci_tag_target_prefix, parse_reference, upload_session_location,
77    validate_repository,
78};
79
80pub use session::{
81    append_upload_bytes, append_upload_bytes_owned, create_upload_session, delete_upload_session,
82    lock_upload_sessions, new_upload_session_id, purge_expired_upload_sessions,
83    read_upload_session, repair_upload_session_evidence, touch_upload_session,
84    upload_body_integrity, upload_body_path_for_session, upload_length, upload_session_length,
85};
86
87pub use multipart::{
88    abort_s3_multipart_upload_session, append_s3_multipart_upload_bytes,
89    append_s3_multipart_upload_bytes_owned, finalize_s3_multipart_upload_session,
90};
91
92// ── Crate-internal re-exports for test access ───────────────────────────────
93//
94// These are re-exported at the crate root so that `tests.rs` (declared as
95// `#[cfg(test)] mod tests;` inside `lib.rs`) can reach them via `crate::` or
96// `super::`.  Production sibling modules import directly from the submodule.
97
98#[cfg(test)]
99pub(crate) use fs::{
100    append_file_anchored, delete_file_anchored, open_anchored_file, persist_upload_session,
101    read_file_anchored, upload_body_path, upload_dir, upload_file_exists_async,
102    upload_file_len_async, upload_metadata_path, upload_tail_path, write_file_atomically,
103};
104#[cfg(test)]
105pub(crate) use multipart::write_upload_tail;
106#[cfg(test)]
107pub(crate) use session::{count_active_upload_sessions, upload_session_expired};
108#[cfg(test)]
109pub(crate) use types::global_scope_namespace;