Skip to content

api.md

Latest commit

 

History

History
322 lines (203 loc) · 11.5 KB

api.md

File metadata and controls

322 lines (203 loc) · 11.5 KB
Raw

Node V1 operation signatures

Audience: MXC consumers

Public entrypoint: @microsoft/mxc-sdk/v1. Types | Overview

Signatures describe the typed consumer API and omit implementation bodies. Callers do not supply JSON or a schema version.

Choosing a launch operation

Output Create and run a container Run in an existing container Result
Capture stdout and stderr run runInContainer Promise<ExecutionResult>
Live standard pipes spawn spawnInContainer Promise<MxcProcess>
Live standard pipes with a writable WSLC stdin spawnWithStdin spawnInContainerWithStdin Promise<MxcProcess>
Interactive terminal spawnWithPty spawnInContainerWithPty Promise<MxcPtyProcess>

Creation takes ContainerRequest and operation options. Existing-container execution takes the ContainerId returned by provision, ExecutionRequest, and operation options. PTY operations are asynchronous. Create-and-run PTY support covers IsolationSession, Bubblewrap, LXC, and Seatbelt direct execution. Existing-container PTY support remains IsolationSession-only. Seatbelt PTY rejects guiAccess. Terminal handles give the caller explicit input, output, resize, and process ownership; there is no separate attached-console launch API. Typed V1 does not accept "MXC request JSON"; the V1.Dev exact-JSON API accepts caller-authored requests separately. Captured existing-container execution returns partial text on timeout with timedOut: true, without waiting for output streams to close. Output read failures reject capture without waiting for the workload to exit. For executor-backed ProcessContainer PTY, timeoutMs reaches wxc-exec, but its exit channel does not distinguish a timeout from an ordinary exit: wait().timedOut is false when the executor exits in either case.

Read the terminal output concurrently rather than only after waiting. On macOS a workload cannot exit while its terminal output is still unread, so a caller that waits first without reading can block indefinitely.

Discovery and validation

Operation Use it to
getPlatformSupport Check whether the SDK can launch on this host and which backends it supports.
getAvailableBackends Discover native host-available backends, capabilities, tiers, and warnings. Availability is advisory; not every reported backend has a V1 creation API.
probe (Windows) Evaluate an optional ProcessContainer request, including the isolation tier and request-specific compatibility diagnostics, without creating a container.
validate* Perform native dry-run validation for a typed lifecycle operation without provisioning, starting, executing, stopping, or deprovisioning a container.

Validation returns ValidationResult with warnings, not execution output. It does not guarantee that a later operation will succeed on a changed host.

@microsoft/mxc-sdk/v1::deprovisionContainer

Releases all backend resources associated with a provisioned container.

export async function deprovisionContainer<C extends LifecycleContainmentKind>(containerId: ContainerId<C>, options: DeprovisionOptions = {}): Promise<LifecycleResult>;

@microsoft/mxc-sdk/v1::policy.filesystem.getAvailableToolsPolicy

Discover tool and SDK directories from the environment and return them as policy paths.

On Windows, finding pwsh.exe on PATH also grants read-write access to the PSReadLine history directory under the supplied USERPROFILE. It does not implicitly grant read access to a drive root.

For PowerShell startup failures, see troubleshooting.

export function getAvailableToolsPolicy(environment?: {
  [key: string]: string | undefined;
}, options?: ToolsPolicyOptions): FilesystemPolicyResult;

@microsoft/mxc-sdk/v1::getPlatformSupport

Get platform support information.

On Windows, ProcessContainer requires native PSEC support. Other supported backends are detected independently; the host is unsupported when none are available.

export function getPlatformSupport(): PlatformSupport;

@microsoft/mxc-sdk/v1::getAvailableBackends

Read every native host-available backend, including its isolation tier, capabilities, and warnings. Host availability is advisory and does not imply that V1 creation can launch every reported backend. Native failures and malformed payloads throw.

export function getAvailableBackends(): AvailableBackend[];

@microsoft/mxc-sdk/v1::policy.filesystem.getTemporaryFilesPolicy

Return the existing host temporary directory as read-write policy; no directories are created.

export function getTemporaryFilesPolicy(environment?: {
  [key: string]: string | undefined;
}): FilesystemPolicyResult;

@microsoft/mxc-sdk/v1::policy.filesystem.getUserProfilePolicy

Build read-only policy for standard user profile application data locations.

export function getUserProfilePolicy(environment?: { [key: string]: string | undefined }): FilesystemPolicyResult;

@microsoft/mxc-sdk/v1::mxcErrorFromCode

Constructs an MxcError from a native runtime error code.

export function mxcErrorFromCode(code: string, message: string, details?: Record<string, unknown>): MxcError;

@microsoft/mxc-sdk/v1::probe

Report native Windows ProcessContainer host-capability serviceability for an optional request without creating a container. Launch still validates the environment, network policy, and required PSEC version. Windows platform discovery reports probe failures and retries them rather than caching a transient failure as unsupported.

export function probe(request?: ContainerRequest): ProbeOutput;

@microsoft/mxc-sdk/v1::provisionContainer

Provision a container from the backend-specific ProvisionRequest type.

export async function provisionContainer<C extends LifecycleContainmentKind>(request: ProvisionRequest<C> & {
  containment: C;
}, options: ProvisionOptions = {}): Promise<ProvisionResult<C>>;

@microsoft/mxc-sdk/v1::getTelemetryConsentStatus

Read persisted/effective consent and policy without blocking the event loop.

export async function getTelemetryConsentStatus(): Promise<TelemetryConsentStatus>;

@microsoft/mxc-sdk/v1::requestTelemetryConsent

Request consent with the versioned canonical consent resource.

export async function requestTelemetryConsent(presenter: TelemetryConsentPresenter, locale?: string): Promise<TelemetryConsentOutcome>;

@microsoft/mxc-sdk/v1::run

Run a container request asynchronously and capture its output.

export async function run(request: ContainerRequest, options: RunOptions = {}): Promise<ExecutionResult>;

@microsoft/mxc-sdk/v1::runInContainer

Execute in an existing IsolationSession or WSLC container and capture output. Dispatch failures reject with MxcError; workload exit codes and timeouts are returned in ExecutionResult.

export async function runInContainer<C extends PipedExecuteBackend>(containerId: ContainerId<C>, request: ExecutionRequest<C>, options?: RunInContainerOptions): Promise<ExecutionResult>;

@microsoft/mxc-sdk/v1::spawn

Create a container request and asynchronously return its live process. A WSLC command reads end-of-file on stdin.

export async function spawn(request: ContainerRequest, options: SpawnOptions = {}): Promise<MxcProcess>;

@microsoft/mxc-sdk/v1::spawnWithStdin

spawn with a writable standardInput whose end gives the command end-of-file.

export async function spawnWithStdin(request: ContainerRequest, options: SpawnOptions = {}): Promise<MxcProcess>;

@microsoft/mxc-sdk/v1::spawnInContainer

Spawn a workload asynchronously inside a started IsolationSession or WSLC container with live standard pipes. A WSLC workload reads end-of-file on stdin.

export async function spawnInContainer<C extends PipedExecuteBackend>(containerId: ContainerId<C>, request: ExecutionRequest<C>, options: SpawnInContainerOptions = {}): Promise<MxcProcess>;

@microsoft/mxc-sdk/v1::spawnInContainerWithStdin

spawnInContainer with a writable standardInput. Ending it gives the workload end-of-file.

export async function spawnInContainerWithStdin<C extends PipedExecuteBackend>(containerId: ContainerId<C>, request: ExecutionRequest<C>, options: SpawnInContainerOptions = {}): Promise<MxcProcess>;

@microsoft/mxc-sdk/v1::spawnInContainerWithPty

Execute a request in an existing container with an MXC-owned PTY.

export async function spawnInContainerWithPty<C extends LifecycleContainmentKind>(containerId: ContainerId<C>, request: ExecutionRequest<C>, options: SpawnInContainerWithPtyOptions = {}): Promise<MxcPtyProcess>;

@microsoft/mxc-sdk/v1::spawnWithPty

Create a container request attached to an MXC-owned pseudo-terminal.

export async function spawnWithPty(request: ContainerRequest, options: SpawnWithPtyOptions = {}): Promise<MxcPtyProcess>;

@microsoft/mxc-sdk/v1::startContainer

Starts a previously provisioned container.

export async function startContainer<C extends LifecycleContainmentKind>(containerId: ContainerId<C>, options: StartOptions = {}): Promise<LifecycleResult>;

@microsoft/mxc-sdk/v1::stopContainer

Stops a started container without releasing its provision-side resources.

export async function stopContainer<C extends LifecycleContainmentKind>(containerId: ContainerId<C>, options: StopOptions = {}): Promise<LifecycleResult>;

@microsoft/mxc-sdk/v1::validateDeprovision

Validate deprovision without releasing the container.

export async function validateDeprovision<C extends LifecycleContainmentKind>(containerId: ContainerId<C>, options: DeprovisionOptions = {}): Promise<ValidationResult>;

@microsoft/mxc-sdk/v1::validateProcess

Validate a process request without starting a workload.

export async function validateProcess<C extends LifecycleContainmentKind>(containerId: ContainerId<C>, request: ExecutionRequest<C>, options: SpawnInContainerOptions = {}): Promise<ValidationResult>;

@microsoft/mxc-sdk/v1::validateProvision

Validate provision without allocating a container or returning an identity.

export async function validateProvision<C extends LifecycleContainmentKind>(request: ProvisionRequest<C> & {
  containment: C;
}, options: ProvisionOptions = {}): Promise<ValidationResult>;

@microsoft/mxc-sdk/v1::validateStart

Validate a start request without starting the container.

export async function validateStart<C extends LifecycleContainmentKind>(containerId: ContainerId<C>, options: StartOptions = {}): Promise<ValidationResult>;

@microsoft/mxc-sdk/v1::validateStop

Validate a stop request without stopping the container.

export async function validateStop<C extends LifecycleContainmentKind>(containerId: ContainerId<C>, options: StopOptions = {}): Promise<ValidationResult>;

@microsoft/mxc-sdk/v1::withdrawTelemetryConsent

Idempotently withdraw telemetry consent without blocking the event loop.

export async function withdrawTelemetryConsent(): Promise<TelemetryConsentOutcome>;