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 http;
49pub(crate) mod imagebuilder;
50pub(crate) mod imagecache;
51mod notice;
52pub(crate) mod retry;
53pub(crate) mod rfc3339_micros;
54pub(crate) mod runtime;
55pub(crate) mod shell_input;
56
57pub use app::App;
58pub use client::{Client, ClientBuilder};
59#[doc(hidden)]
60pub use credential::object::{CredentialInjectionPolicy, Credentials, Secret};
61#[doc(hidden)]
62pub use credential::types::{
63    CredentialInjectionPolicyInfo, CredentialInjectionPolicyPage, CredentialInjectionPolicySummary,
64    InjectionRule, InjectionTarget, InjectionTargetKind, ListCredentialInjectionPoliciesQuery,
65    SecretInfo,
66};
67pub use error::{Result, RpcStatus, SailError, TransportKind};
68pub use exec::{
69    CancelSignal, ExecOptions, ExecProcess, ExecResult, OutputStream, RetryBudget, RunOptions,
70    EXEC_CANCEL_RETRY,
71};
72pub use image::{BaseImage, ImageArchitecture, ImageFilesystem, ImageSpec};
73pub use notice::{clear_notice_handler, set_notice_handler};
74pub use runtime::block_on;
75pub use sailbox::object::{Sailbox, SailboxFs};
76pub use sailbox::ssh::{EnableSshOptions, SshEndpoint};
77pub use sailbox::types::{
78    CheckpointOptions, CreateSailboxRequest, ForkOptions, IngressPort, IngressProtocol,
79    ListSailboxesQuery, ListenerEndpoint, SailboxCheckpoint, SailboxHandle, SailboxInfo,
80    SailboxListOrder, SailboxPage, SailboxSize, SailboxStatus, SailboxStatusFilter, VolumeMount,
81    WaitForListenerOptions,
82};
83pub use sailbox::{DirEntry, EntryType, UpgradeResult};
84pub use shell::ShellOptions;
85
86/// Re-export of the [`time`] crate, whose [`OffsetDateTime`](time::OffsetDateTime)
87/// appears in public types (sailbox/volume timestamps). Re-exported so callers
88/// name the same version the SDK was built against.
89pub use time;
90
91/// Generated protobuf/gRPC code for the Sailbox services. The proto files are
92/// the source of truth for these types, so the generated members carry no
93/// hand-written docs and are exempt from our lint policy (the server stubs,
94/// emitted only under `test-fakes`, are pure codegen we never hand-edit).
95#[allow(missing_docs, clippy::all, clippy::pedantic)]
96pub(crate) mod pb {
97    pub mod workerproxy {
98        pub mod v1 {
99            tonic::include_proto!("workerproxy.v1");
100        }
101    }
102    pub mod imagebuilder {
103        pub mod v1 {
104            tonic::include_proto!("imagebuilder.v1");
105        }
106    }
107    pub mod image {
108        pub mod v1 {
109            tonic::include_proto!("image.v1");
110        }
111    }
112}
113
114/// Unstable, binding-only surface shared with the first-party CLI, Python, and
115/// TypeScript (napi) bindings (and this crate's own integration tests): the raw
116/// transport, the
117/// credential store, and the generated protobuf code. Not part of the public
118/// API and not covered by semantic versioning; do not depend on it from outside
119/// this workspace.
120#[doc(hidden)]
121pub mod internal {
122    pub mod credentials {
123        pub use crate::credentials::*;
124    }
125    pub mod http {
126        pub use crate::http::*;
127    }
128    pub mod pb {
129        pub use crate::pb::*;
130    }
131    pub mod retry {
132        pub use crate::retry::*;
133    }
134
135    pub use crate::runtime::runtime;
136    pub use crate::sailbox::api::SailboxApi;
137}
sail/lib.rs

sail/
lib.rs
