mxc_sdk_dart

A Dart port of the part of the Microsoft MXC SDK (@microsoft/mxc-sdk) that sandbox-runtime uses. It starts a command in a Windows ProcessContainer (BaseContainer), in process, through mxc_ffi.dll.

import 'package:mxc_sdk_dart/mxc_sdk_dart.dart';

final request = ContainerRequest(
  command: r'C:\Windows\System32\cmd.exe /d /s /c "echo hi"',
  filesystem: FilesystemPolicy(
    readwritePaths: [r'C:\work'],
    readonlyPaths: [r'C:\'],
  ),
  network: NetworkPolicy(
    egress: NetworkEgressConfig(defaultAction: NetworkAction.deny),
  ),
  ui: UiPolicy(disable: false),
  workingDirectory: r'C:\work',
  inheritDefaultEnvironment: true,
);
if (probe(request).tier == IsolationTier.baseContainer) {
  final process = await spawn(request);
  process.standardOutput!.listen(stdout.add);
  print(await process.wait());
}

Scope

Node SDK (@microsoft/mxc-sdk/v1) Here
probe(request) probe(request)
spawn(request), MxcProcess spawn(request), MxcProcess
ContainerRequest The same, for containments process and processcontainer
run, spawnWithPty, lifecycle APIs, telemetry, other backends Not ported

Off Windows, probe and spawn throw MxcError with MxcErrorCode.backendUnavailable, and the package bundles no library.

Differences from the Node SDK:

  • stdout and stderr are Stream<List<int>>, and stdin is a NativeStdin. A helper isolate drives each one with the blocking stream functions of mxc_ffi.
  • After a kill or a timeout, completion is polled with mxc_sandbox_try_wait, not waited on in a blocking call. The C ABI does not allow a kill during a blocking wait.

The native library

The build hook uses kiln. It downloads mxc_ffi.dll from a GitHub release when native_artifacts/prebuilt.json matches the package sources. Otherwise it builds the mxc_ffi crate of microsoft/mxc at the commit in native_artifacts/sources.json (tag v1.1.0). A source build needs Windows, rustup, and the Rust target:

rustup target add aarch64-pc-windows-msvc x86_64-pc-windows-msvc

Telemetry

The library is built without Microsoft telemetry routing. From 1.1.0, a release build of MXC sends Required diagnostic events to Microsoft, and telemetry.enabled does not turn them off (see MXC diagnostic data). The hook builds with an empty MXC_TELEMETRY_COMPONENT_PATH, which MXC documents as the build without routing. It then fails if the built library contains the routing group of the MXC checkout.

Tests

dart test runs everywhere. On Windows 11 with BaseContainer, it also runs test/windows_test.dart, which starts real containers.

Releases and CI

Unit checks formatting, analysis, tests, and the pub.dev archive on every pull request and pushes to main and ci/**. Upstream watch checks Microsoft MXC releases daily against the commit in native_artifacts/sources.json.

The Kiln release workflow builds only Windows x64 and ARM64. Start it by hand with dry_run enabled to test the builds without uploading. A real run uploads the native libraries and creates a kiln-manifest/<tag> branch. Merge that branch before publishing the Dart package. Kiln check validates its manifest and download URLs; until the first native release, it skips the check with an explanation because no manifest exists. Windows consumers build from source.

Publish the first version to pub.dev by hand. Then enable automated publishing on the package's Admin page for Telosnex/mxc_sdk_dart, tag pattern pub-mxc_sdk_dart-v{{version}}, and GitHub environment pub.dev. Later releases use a tag such as pub-mxc_sdk_dart-v0.1.1 matching pubspec.yaml. To validate the publication pipeline without uploading, start Pub publish by hand and enter the prospective tag. Manual runs are always dry runs.

Windows container tests need Windows 11 with BaseContainer support. The Linux Unit job does not run them. Integration builds the DLL and runs the other tests on Windows x64 and ARM64, on pushes and nightly. A successful native build alone does not prove that container isolation works.

License

MIT. The ported files keep the copyright of Microsoft Corporation, from microsoft/mxc sdk/node (MIT).

Libraries

mxc_sdk_dart
Dart port of the Microsoft MXC SDK subset that sandbox-runtime uses.