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

sail/
lib.rs
