sail/
lib.rs

1//! `sail-rs`: the canonical, typed Sail SDK.
2//!
3//! [`Client`] is the entry point: a cheap-to-clone async handle that owns
4//! configuration and transport (HTTP for lifecycle/app, gRPC for per-sailbox
5//! exec and file streams). Bindings (the Python extension, the TypeScript
6//! napi addon, and the CLI) are thin layers over it.
7//!
8//! As a library, this crate documents its whole public API and never writes to
9//! the process streams or exits: callers decide how to surface output and
10//! errors.
11//!
12//! The transport plumbing the bindings reach into lives under the hidden
13//! [`internal`] module; it is not part of the public API and carries no
14//! stability guarantee.
15#![deny(missing_docs)]
16#![deny(clippy::print_stdout, clippy::print_stderr, clippy::exit)]
17
18pub mod app;
19pub mod client;
20pub mod config;
21pub mod error;
22pub mod exec;
23pub mod forward;
24pub mod guest;
25pub mod image;
26pub mod imagebuild;
27pub mod sailbox;
28pub mod shell;
29
30pub use worker::{
31    FileReader, FileWriter, Listener, WriteAbortHandle, WriteOptions, FILE_WRITE_CHUNK_BYTES,
32};
33// Hidden as a module: users hold its types via the re-exports above; the
34// module itself is the workerproxy client, which is not a user surface.
35#[doc(hidden)]
36pub mod worker;
37
38mod channels;
39pub(crate) mod credentials;
40pub(crate) mod http;
41pub(crate) mod imagebuilder;
42pub(crate) mod imagecache;
43pub(crate) mod retry;
44pub(crate) mod runtime;
45
46pub use client::{Client, ClientBuilder};
47pub use runtime::block_on;
48pub use sailbox::object::{Sailbox, SailboxFs};
49pub use sailbox::{DirEntry, EntryType};
50
51/// Re-export of the [`time`] crate, whose [`OffsetDateTime`](time::OffsetDateTime)
52/// appears in public types (sailbox/volume timestamps). Re-exported so callers
53/// name the same version the SDK was built against.
54pub use time;
55
56/// Generated protobuf/gRPC code for the sailbox services. The proto files are
57/// the source of truth for these types, so the generated members carry no
58/// hand-written docs and are exempt from our lint policy (the server stubs,
59/// emitted only under `test-fakes`, are pure codegen we never hand-edit).
60#[allow(missing_docs, clippy::all, clippy::pedantic)]
61pub(crate) mod pb {
62    pub mod workerproxy {
63        pub mod v1 {
64            tonic::include_proto!("workerproxy.v1");
65        }
66    }
67    pub mod imagebuilder {
68        pub mod v1 {
69            tonic::include_proto!("imagebuilder.v1");
70        }
71    }
72    pub mod image {
73        pub mod v1 {
74            tonic::include_proto!("image.v1");
75        }
76    }
77}
78
79/// Unstable, binding-only surface shared with the first-party CLI, Python, and
80/// TypeScript (napi) bindings (and this crate's own integration tests): the raw
81/// transport, the
82/// credential store, and the generated protobuf code. Not part of the public
83/// API and not covered by semantic versioning; do not depend on it from outside
84/// this workspace.
85#[doc(hidden)]
86pub mod internal {
87    pub mod credentials {
88        pub use crate::credentials::*;
89    }
90    pub mod http {
91        pub use crate::http::*;
92    }
93    pub mod pb {
94        pub use crate::pb::*;
95    }
96    pub mod retry {
97        pub use crate::retry::*;
98    }
99
100    pub use crate::runtime::runtime;
101    pub use crate::sailbox::api::SailboxApi;
102}
sail/lib.rs

sail/
lib.rs
