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};
77#[doc(hidden)]
78pub use sailbox::types::CustomDomainInfo;
79pub use sailbox::types::{
80    CheckpointOptions, CreateSailboxRequest, ForkOptions, IngressPort, IngressProtocol,
81    ListSailboxesQuery, ListenerEndpoint, SailboxCheckpoint, SailboxHandle, SailboxInfo,
82    SailboxListOrder, SailboxPage, SailboxSize, SailboxStatus, SailboxStatusFilter, VolumeMount,
83    WaitForListenerOptions,
84};
85pub use sailbox::{DirEntry, EntryType, UpgradeResult};
86pub use shell::ShellOptions;
87
88/// Re-export of the [`time`] crate, whose [`OffsetDateTime`](time::OffsetDateTime)
89/// appears in public types (sailbox/volume timestamps). Re-exported so callers
90/// name the same version the SDK was built against.
91pub use time;
92
93/// Generated protobuf/gRPC code for the Sailbox services. The proto files are
94/// the source of truth for these types, so the generated members carry no
95/// hand-written docs and are exempt from our lint policy (the server stubs,
96/// emitted only under `test-fakes`, are pure codegen we never hand-edit).
97#[allow(missing_docs, clippy::all, clippy::pedantic)]
98pub(crate) mod pb {
99    pub mod workerproxy {
100        pub mod v1 {
101            tonic::include_proto!("workerproxy.v1");
102        }
103    }
104    pub mod imagebuilder {
105        pub mod v1 {
106            tonic::include_proto!("imagebuilder.v1");
107        }
108    }
109    pub mod image {
110        pub mod v1 {
111            tonic::include_proto!("image.v1");
112        }
113    }
114}
115
116/// Unstable, binding-only surface shared with the first-party CLI, Python, and
117/// TypeScript (napi) bindings (and this crate's own integration tests): the raw
118/// transport, the
119/// credential store, and the generated protobuf code. Not part of the public
120/// API and not covered by semantic versioning; do not depend on it from outside
121/// this workspace.
122#[doc(hidden)]
123pub mod internal {
124    pub mod credentials {
125        pub use crate::credentials::*;
126    }
127    pub mod http {
128        pub use crate::http::*;
129    }
130    pub mod pb {
131        pub use crate::pb::*;
132    }
133    pub mod retry {
134        pub use crate::retry::*;
135    }
136
137    pub use crate::runtime::runtime;
138    pub use crate::sailbox::api::SailboxApi;
139}
sail/lib.rs

sail/
lib.rs
