Skip to main content

chainguard_sandbox/workspaces/
mod.rs

1//! The lower-level client under the sandbox API: the parts of the Chainguard Workspaces Sessions
2//! API (`chainguard.sandbox.runtime.session.v1.Sessions`, the service `chainctl develop` uses) that
3//! the sandbox API needs, plus login and token handling. It is compatible with chainctl 0.2.398.
4//!
5//! It is unofficial: not published or supported by Chainguard. Most programs should use the
6//! [`Sandbox`](crate::Sandbox) API instead.
7//!
8//! ```no_run
9//! # async fn f() -> chainguard_sandbox::Result<()> {
10//! use chainguard_sandbox::workspaces::{Client, ExecOptions, ListOptions, Options};
11//! let c = Client::new(Options { instance: "XXXXXX".into(), ..Default::default() }).await?;
12//! let sessions = c.list(&ListOptions::default()).await?;
13//! let argv = ["go", "test", "./..."].map(String::from);
14//! let res = c.exec(&sessions[0].name, &argv, ExecOptions::default()).await?;
15//! println!("exit {}", res.exit_code);
16//! # Ok(()) }
17//! ```
18
19mod auth;
20mod client;
21mod exchange;
22mod exec;
23mod files;
24mod firstattach;
25mod http;
26mod login;
27mod loopback;
28mod orgs;
29mod repourl;
30mod sessions;
31mod setup;
32
33/// The generated protobuf messages and gRPC client and server for the SDK's subset of the
34/// Sessions API.
35#[allow(clippy::all, missing_docs)]
36pub mod pb {
37    include!("gen/chainguard.sandbox.runtime.session.v1.rs");
38}
39
40pub use auth::{
41    BoxFuture, ChainctlToken, SharedTokenSource, StaticToken, TokenSource, cached,
42    default_token_source, token_fn,
43};
44pub use client::{Client, DEFAULT_USER_AGENT, Options};
45pub use exchange::{
46    IdTokenFn, IdentityExchange, env_id_token, file_id_token, github_actions_id_token,
47};
48pub use exec::{ExecOptions, ExecResult, OutputSink, guest_path, is_guest_held};
49pub use files::{SkipFn, tar_dir, tar_gz_dir};
50pub use firstattach::FIRST_ATTACH_TIMEOUT;
51pub use login::{
52    BrowserLoginToken, Claims, FileLoginStore, LoginLock, LoginOptions, LoginResult, LoginStore,
53    MessageSink, UrlOpener, browser_login, default_login_audiences, default_login_file,
54    login_callback_server, logout, open_browser, refresh_login, token_claims,
55};
56pub use orgs::{Organization, detect_instance, list_organizations, platform_token_source};
57pub use repourl::normalize_github_url;
58pub use sessions::{
59    DEFAULT_ENVIRONMENT, ListOptions, instance_name, is_session_name, repository_session,
60    repository_url, workspace_session,
61};
62pub use setup::{
63    DEFAULT_GITHUB_OAUTH_PORT, ENABLE_TERMS, Entitlement, GITHUB_APP_INSTALL_URL,
64    GitHubAuthorization, GitHubAuthorizeOptions, GitHubOAuthStart, LinkedGitHub, PlatformError,
65    TermsDocument, WORKSPACES_TERMS, accept_terms, accepted_terms, authorize_github,
66    begin_github_oauth, enable_sandbox, link_github_organization, linked_github_organizations,
67    missing_workspaces_terms, terms_document_info, workspaces_entitlement,
68};
69
70pub(crate) use exec::clean_path;
71pub(crate) use login::random_hex;
72
73/// The plane's session resource.
74pub type Session = pb::Session;
75
76/// The sandbox plane chainctl dials (overridable with `$CHAINCTL_SESSIONS_URL`).
77pub const DEFAULT_URL: &str = "https://sessions.chainbox.dev";
78/// The Chainguard token audience the plane accepts.
79pub const DEFAULT_AUDIENCE: &str = "https://sessions.chainbox.dev";
80/// Chainguard's security token service (STS).
81pub const DEFAULT_ISSUER: &str = "https://issuer.enforce.dev";
82/// Chainguard's account (IAM) API.
83pub const DEFAULT_PLATFORM_URL: &str = "https://console-api.enforce.dev";
84/// The audience of tokens for the account API (used to list your organizations).
85pub const PLATFORM_AUDIENCE: &str = "https://console-api.enforce.dev";
86/// Where the repository lives inside the guest.
87pub const DEFAULT_WORK_DIR: &str = "/work";
88/// The stdin size limit chainctl documents for exec.
89pub const MAX_EXEC_STDIN: usize = 16 << 20;
90/// The plane's URL (chainctl's override).
91pub const ENV_SESSIONS_URL: &str = "CHAINCTL_SESSIONS_URL";
92/// The organization ID (chainctl's override).
93pub const ENV_INSTANCE: &str = "CHAINCTL_SANDBOX_INSTANCE";
94/// A static sessions token (chainctl's override).
95pub const ENV_AUTH_TOKEN: &str = "CHAINCTL_AUTH_TOKEN";
96/// Turns off organization auto-detection when set to "1".
97pub const ENV_NO_DETECT_INSTANCE: &str = "CHAINGUARD_SANDBOX_NO_DETECT_INSTANCE";