Skip to content

Latest commit

 

History

History
329 lines (214 loc) · 12.3 KB

api.md

File metadata and controls

329 lines (214 loc) · 12.3 KB

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>
Interactive terminal spawnWithPty spawnInContainerWithPty Promise<MxcPtyProcess>
The caller's own standard input, output, and error spawnWithExtendedOptions with stdio: 'inherit' — Promise<MxcProcess>

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. spawnWithExtendedOptions takes extensible options; its default stdio: 'pipes' behaves like spawn. stdio: 'inherit' instead attaches the workload to whatever this Node.js process's standard streams already are, such as a console, pseudo-console, or pipes set up by the parent; it supports ProcessContainer, Bubblewrap, and Seatbelt. 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. MicroVM is reported when available, but execution requires the development JSON API; typed V1 requests cannot select it. Availability is advisory. Windows native backend availability is refreshed on each call.

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. This state and consent-management operations do not control Required collection for supported contracts. See Telemetry.

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. On WSLC, standardInput is writable. End it to give the command end-of-file. Waiting ends an untaken stdin.

export async function spawn(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. On WSLC, standardInput is writable. End it to give the workload end-of-file. Waiting ends an untaken stdin. Killing a WSLC workload that is still running, or reaching its timeout, deletes its container about a minute later, because MXC does not signal a WSLC process that has stdin.

export async function spawnInContainer<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::spawnWithExtendedOptions

Create a container request with stdio and other controls chosen in the options. With stdio: 'inherit' the returned process has no streams to take, and backends other than ProcessContainer, Bubblewrap, and Seatbelt reject with unsupported_containment.

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

@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>;