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

sail/
lib.rs
