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 connections. The Sail Python SDK, TypeScript SDK, and CLI
5//! are built on this crate.
6//!
7//! As a library, this crate documents its whole public API and never writes
8//! to the process streams or exits, with one deliberate exception:
9//! [`Sailbox::shell`] bridges the caller's terminal (raw mode, stdin/stdout,
10//! and a Ctrl-C handler) for the duration of the interactive session.
11//!
12//! The plumbing the first-party 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;
21// CR-soon aagam: the credential-injection surface is in private beta, hidden
22// from rustdoc (and docs.rs) but fully usable. When the feature publishes,
23// remove the doc(hidden) attributes here, on the Client/Sailbox impls in
24// credential/object.rs, and on ListSailboxesQuery.credential_policy_id,
25// together with the docs-side BETA_* constants.
26#[doc(hidden)]
27pub mod credential;
28pub mod error;
29pub mod exec;
30pub mod forward;
31pub mod guest;
32pub mod image;
33pub mod imagebuild;
34pub mod sailbox;
35pub mod shell;
36
37pub use worker::{
38    FileReader, FileWriter, Listener, WriteAbortHandle, WriteOptions, FILE_WRITE_CHUNK_BYTES,
39};
40// Hidden as a module: users hold its types via the re-exports above; the
41// module itself is the workerproxy client, which is not a user surface.
42#[doc(hidden)]
43pub mod worker;
44
45pub(crate) mod apierror;
46mod channels;
47pub(crate) mod credentials;
48pub(crate) mod dockerignore;
49pub(crate) mod http;
50pub(crate) mod imagebuilder;
51pub(crate) mod imagecache;
52mod notice;
53pub(crate) mod retry;
54pub(crate) mod rfc3339_micros;
55pub(crate) mod runtime;
56pub(crate) mod shell_input;
57
58pub use app::App;
59pub use client::{Client, ClientBuilder};
60#[doc(hidden)]
61pub use credential::object::{CredentialInjectionPolicy, Credentials, Secret};
62#[doc(hidden)]
63pub use credential::types::{
64    CredentialInjectionPolicyInfo, CredentialInjectionPolicyPage, CredentialInjectionPolicySummary,
65    InjectionRule, InjectionTarget, InjectionTargetKind, ListCredentialInjectionPoliciesQuery,
66    SecretInfo,
67};
68pub use error::{Result, RpcStatus, SailError, TransportKind};
69pub use exec::{
70    CancelSignal, ExecOptions, ExecProcess, ExecResult, OutputStream, RetryBudget, RunOptions,
71    EXEC_CANCEL_RETRY,
72};
73pub use image::{BaseImage, ImageArchitecture, ImageFilesystem, ImageSpec, OciImage};
74pub use notice::{clear_notice_handler, set_notice_handler};
75pub use runtime::block_on;
76pub use sailbox::object::{Sailbox, SailboxFs};
77pub use sailbox::ssh::{EnableSshOptions, SshEndpoint};
78#[doc(hidden)]
79pub use sailbox::types::CustomDomainInfo;
80pub use sailbox::types::{
81    AutoSleep, CheckpointOptions, CreateSailboxRequest, IngressPort, IngressProtocol,
82    ListSailboxesQuery, ListenerEndpoint, SailboxCheckpoint, SailboxHandle, SailboxInfo,
83    SailboxListOrder, SailboxPage, SailboxSize, SailboxStatus, SailboxStatusFilter, VolumeMount,
84    WaitForListenerOptions,
85};
86pub use sailbox::{DirEntry, EntryType, UpgradeResult};
87pub use shell::ShellOptions;
88
89/// Re-export of the [`time`] crate, whose [`OffsetDateTime`](time::OffsetDateTime)
90/// appears in public types (sailbox/volume timestamps). Re-exported so callers
91/// name the same version the SDK was built against.
92pub use time;
93
94/// Generated protobuf/gRPC code for the Sailbox services. The proto files are
95/// the source of truth for these types, so the generated members carry no
96/// hand-written docs and are exempt from our lint policy (the server stubs,
97/// emitted only under `test-fakes`, are pure codegen we never hand-edit).
98#[allow(missing_docs, clippy::all, clippy::pedantic)]
99pub(crate) mod pb {
100    pub mod workerproxy {
101        pub mod v1 {
102            tonic::include_proto!("workerproxy.v1");
103        }
104    }
105    pub mod imagebuilder {
106        pub mod v1 {
107            tonic::include_proto!("imagebuilder.v1");
108        }
109    }
110    pub mod image {
111        pub mod v1 {
112            tonic::include_proto!("image.v1");
113        }
114    }
115}
116
117/// Unstable, binding-only surface shared with the first-party CLI, Python, and
118/// TypeScript (napi) bindings (and this crate's own integration tests): the raw
119/// transport, the
120/// credential store, and the generated protobuf code. Not part of the public
121/// API and not covered by semantic versioning; do not depend on it from outside
122/// this workspace.
123#[doc(hidden)]
124pub mod internal {
125    pub mod credentials {
126        pub use crate::credentials::*;
127    }
128    pub mod http {
129        pub use crate::http::*;
130    }
131    pub mod pb {
132        pub use crate::pb::*;
133    }
134    pub mod retry {
135        pub use crate::retry::*;
136    }
137
138    pub use crate::runtime::runtime;
139    pub use crate::sailbox::api::SailboxApi;
140}
sail/lib.rs

sail/
lib.rs
