Skip to main content

Module workspaces

Module workspaces 

Source
Expand description

The lower-level client under the sandbox API: the parts of the Chainguard Workspaces Sessions API (chainguard.sandbox.runtime.session.v1.Sessions, the service chainctl develop uses) that the sandbox API needs, plus login and token handling. It is compatible with chainctl 0.2.398.

It is unofficial: not published or supported by Chainguard. Most programs should use the Sandbox API instead.

use chainguard_sandbox::workspaces::{Client, ExecOptions, ListOptions, Options};
let c = Client::new(Options { instance: "XXXXXX".into(), ..Default::default() }).await?;
let sessions = c.list(&ListOptions::default()).await?;
let argv = ["go", "test", "./..."].map(String::from);
let res = c.exec(&sessions[0].name, &argv, ExecOptions::default()).await?;
println!("exit {}", res.exit_code);

Modules§

pb
The generated protobuf messages and gRPC client and server for the SDK’s subset of the Sessions API.

Structs§

BrowserLoginToken
A TokenSource backed by the library’s own login: it mints tokens from the saved refresh token, and when there is none (or it has expired) runs browser_login, unless no_browser is set. Wrap it in cached. Concurrent processes share the saved login safely.
ChainctlToken
Mints tokens by running chainctl auth token --audience <audience>. It needs a prior chainctl auth login.
Claims
A token’s unverified identity claims (for display).
Client
A connection to the Sessions service. Cloning is cheap and shares the connection.
Entitlement
An organization’s Workspaces entitlement.
ExecOptions
Configures Client::exec.
ExecResult
A finished command’s status.
FileLoginStore
Stores logins in a JSON file (0600, in a 0700 directory). The Go, Python, TypeScript and Rust libraries share default_login_file, so one login serves all four.
GitHubAuthorization
The result of authorize_github. It holds no GitHub token: the service exchanges the code itself when the account is linked.
GitHubAuthorizeOptions
Configures authorize_github.
GitHubOAuthStart
What the service hands out to start a GitHub authorization: the Chainguard GitHub App’s OAuth client ID, and a state value the service signed and checks again when the account is linked.
IdentityExchange
A TokenSource that trades a token from an external OIDC issuer (GitHub Actions, GitLab, a Kubernetes service account, …) for a Chainguard token, acting as a Chainguard assumable identity that trusts that issuer and subject.
LinkedGitHub
A GitHub account linked to a Chainguard organization.
ListOptions
Filters Client::list.
LoginLock
Releases a LoginStore lock when dropped.
LoginOptions
Configures browser_login.
LoginResult
What the issuer hands back.
Options
Configures a Client.
Organization
A Chainguard organization (a root IAM group).
PlatformError
A non-2xx answer from the platform API.
StaticToken
Always returns the same token.
TermsDocument
A legal document an organization accepts.

Constants§

DEFAULT_AUDIENCE
The Chainguard token audience the plane accepts.
DEFAULT_ENVIRONMENT
The environment document chainctl 0.2.398 uses for a directory without .chainguard/develop.yaml or ci.yaml. Its check is named “develop”.
DEFAULT_GITHUB_OAUTH_PORT
The loopback port the GitHub authorization redirects to (the one chainctl uses).
DEFAULT_ISSUER
Chainguard’s security token service (STS).
DEFAULT_PLATFORM_URL
Chainguard’s account (IAM) API.
DEFAULT_URL
The sandbox plane chainctl dials (overridable with $CHAINCTL_SESSIONS_URL).
DEFAULT_USER_AGENT
The user agent sent with every call unless Options::user_agent says otherwise.
DEFAULT_WORK_DIR
Where the repository lives inside the guest.
ENABLE_TERMS
The documents an organization accepts when Workspaces is turned on the way chainctl develop init does it: the Workspaces terms, the Code Analysis Terms (the same switch turns on Chainguard Checks), and the Terms of Service and Data Privacy Agreement that linking a GitHub account requires.
ENV_AUTH_TOKEN
A static sessions token (chainctl’s override).
ENV_INSTANCE
The organization ID (chainctl’s override).
ENV_NO_DETECT_INSTANCE
Turns off organization auto-detection when set to “1”.
ENV_SESSIONS_URL
The plane’s URL (chainctl’s override).
FIRST_ATTACH_TIMEOUT
Bounds Client::complete_first_attach.
GITHUB_APP_INSTALL_URL
Where the Chainguard GitHub App is installed on a GitHub organization or user.
MAX_EXEC_STDIN
The stdin size limit chainctl documents for exec.
PLATFORM_AUDIENCE
The audience of tokens for the account API (used to list your organizations).
WORKSPACES_TERMS
The documents an organization must accept to use Workspaces: the Secured Platform Terms and the Master Service and License Agreement.

Traits§

LoginStore
Keeps refresh tokens between runs, per issuer.
TokenSource
Returns a Chainguard bearer token whose audience includes DEFAULT_AUDIENCE (or, for the platform API, PLATFORM_AUDIENCE).

Functions§

accept_terms
Records that the organization accepts the documents with these IDs. This is a legal act on the organization’s behalf: call it only when the person running your program has agreed to the documents. It needs the owner role; accepting a document again changes nothing.
accepted_terms
The IDs of the legal documents the organization has accepted. ts must mint platform tokens (None: platform_token_source).
authorize_github
Sends the person to GitHub to authorize the Chainguard GitHub App and waits for GitHub’s redirect to a loopback port. It is the flow chainctl uses: PKCE with S256, the account picker forced, and the state checked on return. Bound it with tokio::time::timeout.
begin_github_oauth
Starts a GitHub authorization.
browser_login
Runs the interactive login: opens the issuer’s login page in a browser and waits for the redirect back to a localhost callback. Bound it with tokio::time::timeout.
cached
Reuses a token until a minute before the exp claim of the JWT. Tokens whose expiry can’t be read are cached for five minutes. Concurrent callers share one fetch, which runs on its own task, so one caller giving up (dropping its future) doesn’t fail the others. The client drops the cached token when the plane answers Unauthenticated (see TokenSource::invalidate).
default_login_audiences
What a browser login asks for: the sessions service and the account API. $CHAINGUARD_SANDBOX_LOGIN_AUDIENCES (comma-separated) overrides it.
default_login_file
<user config dir>/chainguard-sandbox/login.json: on macOS ~/Library/Application Support/chainguard-sandbox/login.json, on Linux $XDG_CONFIG_HOME (or ~/.config)/chainguard-sandbox/login.json, on Windows %AppData%. Overridden by $CHAINGUARD_SANDBOX_LOGIN_FILE.
default_token_source
$CHAINCTL_AUTH_TOKEN when set, otherwise the library’s own login (a cached BrowserLoginToken): tokens are minted from the saved login, and a browser login runs when there is none. chainctl isn’t used; set $CHAINGUARD_SANDBOX_AUTH=chainctl to mint tokens with it instead. $CHAINGUARD_SANDBOX_SOCIAL_LOGIN preselects the login’s social provider (github, google-oauth2, gitlab), and $CHAINGUARD_SANDBOX_NO_BROWSER=1 makes a missing login an error (Error::LoginRequired) instead of opening a browser.
detect_instance
The ID of the only organization the identity belongs to (Error::NoOrganization or Error::AmbiguousOrganization otherwise).
enable_sandbox
Turns on Checks and Workspaces for the organization, with its plan’s monthly allowance. An allowance Chainguard already granted is kept. It needs the owner role, and the organization must have accepted the terms first: otherwise the error’s PlatformError::missing_terms lists the documents.
env_id_token
Reads the OIDC token from an environment variable (e.g. a GitLab CI id_tokens: variable).
file_id_token
Reads the OIDC token from a file on every call (e.g. a Kubernetes projected service-account token, which is rotated in place).
github_actions_id_token
Fetches a GitHub Actions OIDC token whose audience is the Chainguard issuer ("" = DEFAULT_ISSUER). The workflow needs permissions: id-token: write.
guest_path
Resolves p against /work, cleaning it like Go’s path.Clean.
instance_name
“instances/{id}”; an already-qualified name is returned unchanged.
is_guest_held
Whether e is the plane refusing a call because another controller holds the guest (an attached shell that is still heartbeating), including the FailedPrecondition “… held by another controller … Channel already in use” it returns for a few seconds after another client’s attach or exec ends.
is_session_name
Whether s is a full resource name “instances/{instance}/sessions/{session}”.
link_github_organization
Links a GitHub account to the Chainguard organization, using an authorization from authorize_github. github_login is the account to link, an organization or a user; empty means the GitHub user who authorized. The Chainguard GitHub App must be installed on the account (otherwise PlatformError::github_app_not_installed), and you must own it. An account can be linked to one Chainguard organization at a time.
linked_github_organizations
The GitHub accounts linked to the organization.
list_organizations
Returns the organizations visible to the token source’s identity, sorted by name. ts must mint tokens for PLATFORM_AUDIENCE; None uses platform_token_source. It calls the IAM Groups API: GET /iam/v1/groups?uidp.in_root=true.
logout
Forgets the saved login for issuer (“” = DEFAULT_ISSUER). None uses the default file.
missing_workspaces_terms
The documents Workspaces needs that the organization has not accepted yet.
normalize_github_url
Turns any GitHub remote form — git@github.com:o/r.git, ssh://git@github.com[:22]/o/r, git://github.com/o/r, https://token@GitHub.com/o/r.git, github.com/o/r — into https://github.com/o/r. Credentials are never kept. Other URLs with a scheme lose their credentials and trailing “.git”; scp-style remotes on other hosts are returned unchanged.
open_browser
Opens u in the default browser (open on macOS, xdg-open on Linux and BSDs, the URL handler on Windows). No shell is involved. Returns whether it worked.
platform_token_source
Mints tokens for the account API (PLATFORM_AUDIENCE) the same way default_token_source does for sessions: from the saved browser login, or with chainctl when $CHAINGUARD_SANDBOX_AUTH=chainctl.
refresh_login
Trades a refresh token for a token for aud (DEFAULT_AUDIENCE if empty). With rotation the issuer returns a new refresh token, which replaces the old one (empty if it didn’t rotate). Returns (token, new_refresh_token). A refused refresh token is Error::LoginExpired.
repository_session
Describes a session opened from a repository URL, like chainctl develop github.com/org/repo: the repository as https://github.com/owner/repo, idle AUTO_HOLD, and DEFAULT_ENVIRONMENT as the fallback for repositories without .chainguard/ files. revision pins a commit (empty = unpinned).
repository_url
Normalizes “github.com/o/r”, “git@github.com:o/r.git”, “ssh://git@github.com:22/o/r” and similar to https://github.com/o/r. Other URLs keep their scheme (credentials stripped); scp-style remotes on other hosts are returned unchanged; a bare “host/path” gets https://.
tar_dir
Writes dir as an uncompressed tar stream, with the rules chainctl documents for its workspace upload: symlinks travel as links; sockets, devices and FIFOs are skipped; entries are owned by root. A symlinked dir is resolved first. A file that changes size while it is being written is truncated or zero-padded to the size in its header, rather than aborting the tar.
tar_gz_dir
tar_dir, gzip’d, in memory (the sandbox API’s upload_dir sends it).
terms_document_info
The label and URL of a known document ID, or a document with only the ID set.
token_claims
Decodes a JWT’s claims without verifying it.
token_fn
Adapts an async function to a TokenSource.
workspace_session
Describes a session whose /work tree is uploaded on the first attach (see Client::complete_first_attach): label identifies the workspace (the sandbox API uses /chainguard-sandbox/<name>); repository and revision are optional metadata; document is the environment document (YAML), None using DEFAULT_ENVIRONMENT with provenance SYNTHESIZED. The idle policy is AUTO_HOLD, chainctl’s default.
workspaces_entitlement
Whether Workspaces is turned on for the organization, its plan, and its session limits.

Type Aliases§

BoxFuture
A boxed, sendable future, as returned by TokenSource::token.
IdTokenFn
Returns the external OIDC token presented to the STS.
MessageSink
Receives progress messages (“open this URL …”). The default writes to stderr.
OutputSink
Receives a stream’s output as it arrives.
Session
The plane’s session resource.
SharedTokenSource
A shared token source.
SkipFn
Decides whether to leave out a path (relative, slash-separated) and, for a directory, everything under it. The second argument is whether it is a directory.
UrlOpener
Opens a URL in a browser; returns false if it couldn’t (the URL is then printed instead).