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 aNativeStdin. A helper isolate drives each one with the blocking stream functions ofmxc_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.