mustardscript 0.1.0

package/crates/mustard-node/src/lib.rs

@@ -0,0 +1,236 @@
+use base64::{Engine as _, engine::general_purpose::STANDARD};
+use hmac::{Hmac, Mac};
+use rand::random;
+use sha2::{Digest, Sha256};
+use std::collections::{HashMap, HashSet};
+use std::sync::{
+    Arc, Mutex, OnceLock,
+    atomic::{AtomicBool, Ordering},
+};
+
+use mustard::CancellationToken;
+use mustard_bridge::{
+    ResumeDto, SnapshotPolicyDto, StartOptionsDto, compile_program_bytes, decode_program,
+    encode_json, inspect_snapshot_bytes, parse_json, resume_program as bridge_resume_program,
+    start_program as bridge_start_program,
+};
+use napi::bindgen_prelude::Buffer;
+use napi::{Error, Result};
+use napi_derive::napi;
+
+type HmacSha256 = Hmac<Sha256>;
+
+fn cancellation_tokens() -> &'static Mutex<HashMap<String, Arc<AtomicBool>>> {
+    static TOKENS: OnceLock<Mutex<HashMap<String, Arc<AtomicBool>>>> = OnceLock::new();
+    TOKENS.get_or_init(|| Mutex::new(HashMap::new()))
+}
+
+fn used_progress_snapshots() -> &'static Mutex<HashSet<String>> {
+    static TOKENS: OnceLock<Mutex<HashSet<String>>> = OnceLock::new();
+    TOKENS.get_or_init(|| Mutex::new(HashSet::new()))
+}
+
+fn next_cancellation_token_id(tokens: &HashMap<String, Arc<AtomicBool>>) -> String {
+    loop {
+        let candidate = format!("cancel-{:032x}", random::<u128>());
+        if !tokens.contains_key(&candidate) {
+            return candidate;
+        }
+    }
+}
+
+fn lookup_cancellation_token(token_id: Option<String>) -> Result<Option<CancellationToken>> {
+    let Some(token_id) = token_id else {
+        return Ok(None);
+    };
+    let tokens = cancellation_tokens()
+        .lock()
+        .map_err(|_| to_napi_error("cancellation token registry is poisoned"))?;
+    let shared = tokens
+        .get(&token_id)
+        .cloned()
+        .ok_or_else(|| to_napi_error(format!("unknown cancellation token `{token_id}`")))?;
+    Ok(Some(CancellationToken::from_shared(shared)))
+}
+
+fn to_napi_error(error: impl std::fmt::Display) -> Error {
+    Error::from_reason(error.to_string())
+}
+
+fn snapshot_identity_hex(snapshot: &[u8]) -> String {
+    let digest = Sha256::digest(snapshot);
+    let mut encoded = String::with_capacity(digest.len() * 2);
+    for byte in digest {
+        use std::fmt::Write as _;
+        let _ = write!(&mut encoded, "{byte:02x}");
+    }
+    encoded
+}
+
+fn snapshot_key_digest_hex(snapshot_key: &[u8]) -> String {
+    let digest = Sha256::digest(snapshot_key);
+    let mut encoded = String::with_capacity(digest.len() * 2);
+    for byte in digest {
+        use std::fmt::Write as _;
+        let _ = write!(&mut encoded, "{byte:02x}");
+    }
+    encoded
+}
+
+fn encode_snapshot_token(snapshot_id: &str, snapshot_key: &[u8]) -> Result<String> {
+    let mut mac = HmacSha256::new_from_slice(snapshot_key)
+        .map_err(|_| to_napi_error("invalid snapshot key"))?;
+    mac.update(snapshot_id.as_bytes());
+    let digest = mac.finalize().into_bytes();
+    let mut token = String::with_capacity(digest.len() * 2);
+    for byte in digest {
+        use std::fmt::Write as _;
+        let _ = write!(&mut token, "{byte:02x}");
+    }
+    Ok(token)
+}
+
+fn assert_authenticated_snapshot(snapshot: &[u8], policy: &SnapshotPolicyDto) -> Result<()> {
+    let snapshot_id = policy
+        .snapshot_id
+        .as_deref()
+        .ok_or_else(|| to_napi_error("raw snapshot restore requires snapshot_id"))?;
+    let snapshot_key_base64 = policy
+        .snapshot_key_base64
+        .as_deref()
+        .ok_or_else(|| to_napi_error("raw snapshot restore requires snapshot_key_base64"))?;
+    let snapshot_token = policy
+        .snapshot_token
+        .as_deref()
+        .ok_or_else(|| to_napi_error("raw snapshot restore requires snapshot_token"))?;
+    let snapshot_key_digest = policy
+        .snapshot_key_digest
+        .as_deref()
+        .ok_or_else(|| to_napi_error("raw snapshot restore requires snapshot_key_digest"))?;
+    let snapshot_key = STANDARD
+        .decode(snapshot_key_base64)
+        .map_err(|_| to_napi_error("snapshot_key_base64 must be valid base64"))?;
+    let expected_snapshot_id = snapshot_identity_hex(snapshot);
+    if expected_snapshot_id != snapshot_id {
+        return Err(to_napi_error(
+            "raw snapshot restore rejected a tampered or unauthenticated snapshot",
+        ));
+    }
+    if snapshot_key_digest_hex(&snapshot_key) != snapshot_key_digest {
+        return Err(to_napi_error(
+            "raw snapshot restore rejected a mismatched snapshot key digest",
+        ));
+    }
+    let expected = encode_snapshot_token(snapshot_id, &snapshot_key)?;
+    if expected != snapshot_token {
+        return Err(to_napi_error(
+            "raw snapshot restore rejected a tampered or unauthenticated snapshot",
+        ));
+    }
+    Ok(())
+}
+
+#[napi]
+pub fn compile_program(source: String) -> Result<Buffer> {
+    let bytes = compile_program_bytes(&source).map_err(to_napi_error)?;
+    Ok(Buffer::from(bytes))
+}
+
+#[napi]
+pub fn create_cancellation_token() -> Result<String> {
+    let mut tokens = cancellation_tokens()
+        .lock()
+        .map_err(|_| to_napi_error("cancellation token registry is poisoned"))?;
+    let token_id = next_cancellation_token_id(&tokens);
+    tokens.insert(token_id.clone(), Arc::new(AtomicBool::new(false)));
+    Ok(token_id)
+}
+
+#[napi]
+pub fn cancel_cancellation_token(token_id: String) -> Result<()> {
+    let tokens = cancellation_tokens()
+        .lock()
+        .map_err(|_| to_napi_error("cancellation token registry is poisoned"))?;
+    let token = tokens
+        .get(&token_id)
+        .ok_or_else(|| to_napi_error(format!("unknown cancellation token `{token_id}`")))?;
+    token.store(true, Ordering::SeqCst);
+    Ok(())
+}
+
+#[napi]
+pub fn release_cancellation_token(token_id: String) -> Result<()> {
+    let mut tokens = cancellation_tokens()
+        .lock()
+        .map_err(|_| to_napi_error("cancellation token registry is poisoned"))?;
+    tokens.remove(&token_id);
+    Ok(())
+}
+
+#[napi]
+pub fn snapshot_identity(snapshot: Buffer) -> Result<String> {
+    Ok(snapshot_identity_hex(snapshot.as_ref()))
+}
+
+#[napi]
+pub fn is_progress_snapshot_used(snapshot_identity: String) -> Result<bool> {
+    let tokens = used_progress_snapshots()
+        .lock()
+        .map_err(|_| to_napi_error("progress snapshot registry is poisoned"))?;
+    Ok(tokens.contains(&snapshot_identity))
+}
+
+#[napi]
+pub fn claim_progress_snapshot(snapshot_identity: String) -> Result<bool> {
+    let mut tokens = used_progress_snapshots()
+        .lock()
+        .map_err(|_| to_napi_error("progress snapshot registry is poisoned"))?;
+    Ok(tokens.insert(snapshot_identity))
+}
+
+#[napi]
+pub fn release_progress_snapshot(snapshot_identity: String) -> Result<()> {
+    let mut tokens = used_progress_snapshots()
+        .lock()
+        .map_err(|_| to_napi_error("progress snapshot registry is poisoned"))?;
+    tokens.remove(&snapshot_identity);
+    Ok(())
+}
+
+#[napi]
+pub fn start_program(
+    program: Buffer,
+    options_json: String,
+    cancellation_token_id: Option<String>,
+) -> Result<String> {
+    let program = decode_program(program.as_ref()).map_err(to_napi_error)?;
+    let options: StartOptionsDto = parse_json(&options_json).map_err(to_napi_error)?;
+    let cancellation_token = lookup_cancellation_token(cancellation_token_id)?;
+    let step =
+        bridge_start_program(&program, options, cancellation_token).map_err(to_napi_error)?;
+    encode_json(&step).map_err(to_napi_error)
+}
+
+#[napi]
+pub fn inspect_snapshot(snapshot: Buffer, policy_json: String) -> Result<String> {
+    let policy: SnapshotPolicyDto = parse_json(&policy_json).map_err(to_napi_error)?;
+    assert_authenticated_snapshot(snapshot.as_ref(), &policy)?;
+    let inspection = inspect_snapshot_bytes(snapshot.as_ref(), policy).map_err(to_napi_error)?;
+    encode_json(&inspection).map_err(to_napi_error)
+}
+
+#[napi]
+pub fn resume_program(
+    snapshot: Buffer,
+    payload_json: String,
+    policy_json: String,
+    cancellation_token_id: Option<String>,
+) -> Result<String> {
+    let payload: ResumeDto = parse_json(&payload_json).map_err(to_napi_error)?;
+    let policy: SnapshotPolicyDto = parse_json(&policy_json).map_err(to_napi_error)?;
+    assert_authenticated_snapshot(snapshot.as_ref(), &policy)?;
+    let cancellation_token = lookup_cancellation_token(cancellation_token_id)?;
+    let step = bridge_resume_program(snapshot.as_ref(), payload, policy, cancellation_token)
+        .map_err(to_napi_error)?;
+    encode_json(&step).map_err(to_napi_error)
+}

package/crates/mustard-sidecar/Cargo.toml

@@ -0,0 +1,21 @@
+[package]
+name = "mustard-sidecar"
+version.workspace = true
+edition.workspace = true
+license.workspace = true
+authors.workspace = true
+repository.workspace = true
+description = "Sidecar process for the MustardScript runtime"
+
+[dependencies]
+anyhow.workspace = true
+mustard-bridge = { path = "../mustard-bridge" }
+serde.workspace = true
+serde_json.workspace = true
+tokio.workspace = true
+
+[dev-dependencies]
+base64 = "0.22.1"
+hmac.workspace = true
+mustard = { path = "../mustard" }
+sha2.workspace = true

package/crates/mustard-sidecar/src/lib.rs

@@ -0,0 +1,134 @@
+use anyhow::{Context, Result};
+use mustard_bridge::{
+    ResumeDto, SnapshotPolicyDto, StartOptionsDto, StepDto, compile_program_bytes, decode_base64,
+    decode_program_base64, encode_bytes_base64, resume_program, start_program,
+};
+use serde::{Deserialize, Serialize};
+
+pub const PROTOCOL_VERSION: u32 = 1;
+pub const MAX_REQUEST_LINE_BYTES: usize = 1024 * 1024;
+
+#[derive(Debug, Serialize, Deserialize)]
+#[serde(tag = "method", rename_all = "snake_case")]
+enum Request {
+    Compile {
+        protocol_version: u32,
+        id: u64,
+        source: String,
+    },
+    Start {
+        protocol_version: u32,
+        id: u64,
+        program_base64: String,
+        options: StartOptionsDto,
+    },
+    Resume {
+        protocol_version: u32,
+        id: u64,
+        snapshot_base64: String,
+        policy: Box<SnapshotPolicyDto>,
+        payload: Box<ResumeDto>,
+    },
+}
+
+#[derive(Debug, Serialize, Deserialize)]
+struct Response {
+    protocol_version: u32,
+    id: u64,
+    ok: bool,
+    #[serde(skip_serializing_if = "Option::is_none")]
+    result: Option<ResponsePayload>,
+    #[serde(skip_serializing_if = "Option::is_none")]
+    error: Option<String>,
+}
+
+#[derive(Debug, Serialize, Deserialize)]
+#[serde(tag = "kind", rename_all = "snake_case")]
+enum ResponsePayload {
+    Program { program_base64: String },
+    Step { step: StepDto },
+}
+
+fn handle(request: Request) -> Response {
+    let id = match &request {
+        Request::Compile { id, .. } | Request::Start { id, .. } | Request::Resume { id, .. } => *id,
+    };
+    let protocol_version = match &request {
+        Request::Compile {
+            protocol_version, ..
+        }
+        | Request::Start {
+            protocol_version, ..
+        }
+        | Request::Resume {
+            protocol_version, ..
+        } => *protocol_version,
+    };
+
+    if protocol_version != PROTOCOL_VERSION {
+        return Response {
+            protocol_version: PROTOCOL_VERSION,
+            id,
+            ok: false,
+            result: None,
+            error: Some(format!(
+                "unsupported sidecar protocol version {protocol_version}; expected {PROTOCOL_VERSION}"
+            )),
+        };
+    }
+
+    let result: Result<ResponsePayload> = match request {
+        Request::Compile { source, .. } => (|| {
+            let bytes = compile_program_bytes(&source)?;
+            Ok(ResponsePayload::Program {
+                program_base64: encode_bytes_base64(&bytes),
+            })
+        })(),
+        Request::Start {
+            program_base64,
+            options,
+            ..
+        } => (|| {
+            let program = decode_program_base64(&program_base64)?;
+            let step = start_program(&program, options, None)?;
+            Ok(ResponsePayload::Step { step })
+        })(),
+        Request::Resume {
+            snapshot_base64,
+            policy,
+            payload,
+            ..
+        } => (|| {
+            let snapshot_bytes = decode_base64(&snapshot_base64)?;
+            let step = resume_program(&snapshot_bytes, *payload, *policy, None)?;
+            Ok(ResponsePayload::Step { step })
+        })(),
+    };
+
+    match result {
+        Ok(result) => Response {
+            protocol_version: PROTOCOL_VERSION,
+            id,
+            ok: true,
+            result: Some(result),
+            error: None,
+        },
+        Err(error) => Response {
+            protocol_version: PROTOCOL_VERSION,
+            id,
+            ok: false,
+            result: None,
+            error: Some(error.to_string()),
+        },
+    }
+}
+
+pub fn handle_request_line(line: &str) -> Result<Option<String>> {
+    if line.trim().is_empty() {
+        return Ok(None);
+    }
+    let request: Request = serde_json::from_str(line).context("invalid request")?;
+    let response = handle(request);
+    let encoded = serde_json::to_string(&response).context("failed to encode response")?;
+    Ok(Some(encoded))
+}

package/crates/mustard-sidecar/src/main.rs

@@ -0,0 +1,36 @@
+use std::io::{self, BufRead, Write};
+
+use anyhow::{Context, Result};
+use mustard_sidecar::{MAX_REQUEST_LINE_BYTES, handle_request_line};
+
+fn main() -> Result<()> {
+    let stdin = io::stdin();
+    let mut stdin = stdin.lock();
+    let mut stdout = io::stdout().lock();
+    let mut line = Vec::new();
+    loop {
+        line.clear();
+        let read = stdin
+            .read_until(b'\n', &mut line)
+            .context("failed to read request line")?;
+        if read == 0 {
+            break;
+        }
+        if line.len() > MAX_REQUEST_LINE_BYTES + 1 {
+            anyhow::bail!("request line exceeds maximum size of {MAX_REQUEST_LINE_BYTES} bytes");
+        }
+        if line.ends_with(b"\n") {
+            line.pop();
+            if line.ends_with(b"\r") {
+                line.pop();
+            }
+        }
+        let line = String::from_utf8(line.clone()).context("request line must be valid utf-8")?;
+        let Some(response) = handle_request_line(&line)? else {
+            continue;
+        };
+        writeln!(&mut stdout, "{response}").context("failed to terminate response line")?;
+        stdout.flush().context("failed to flush response")?;
+    }
+    Ok(())
+}

package/dist/index.js

@@ -0,0 +1,20 @@
+'use strict';
+
+const { loadNative } = require('./native-loader.js');
+const { createExecutorApi } = require('./lib/executor.js');
+const { MustardError } = require('./lib/errors.js');
+const { createProgressApi } = require('./lib/progress.js');
+const { createMustardClass } = require('./lib/runtime.js');
+
+const native = loadNative();
+const { Progress, materializeStep, parseStep } = createProgressApi(native);
+const Mustard = createMustardClass({ native, materializeStep, parseStep });
+const { InMemoryMustardExecutorStore, MustardExecutor } = createExecutorApi({ Mustard, Progress });
+
+module.exports = {
+  InMemoryMustardExecutorStore,
+  MustardError,
+  Mustard,
+  MustardExecutor,
+  Progress,
+};

package/dist/install.js

@@ -0,0 +1,117 @@
+'use strict';
+
+const { execFileSync } = require('node:child_process');
+const fs = require('node:fs');
+const path = require('node:path');
+const {
+  resolvePrebuiltPackage,
+  getCurrentPrebuiltTarget,
+  getLocalBuildOutputFile,
+} = require('./native-loader.js');
+
+const packageRoot = path.basename(__dirname) === 'dist' ? path.dirname(__dirname) : __dirname;
+
+let prebuilt = null;
+let prebuiltError = null;
+try {
+  prebuilt = resolvePrebuiltPackage();
+} catch (error) {
+  prebuiltError = error;
+}
+
+if (prebuilt) {
+  process.stdout.write(
+    `MustardScript: using optional prebuilt addon from ${prebuilt.packageName}\n`,
+  );
+  process.exit(0);
+}
+
+const target = getCurrentPrebuiltTarget();
+if (prebuiltError) {
+  process.stdout.write(
+    `MustardScript: ignoring invalid optional prebuilt for ${target?.platformArchABI ?? `${process.platform}-${process.arch}`}: ${prebuiltError.message}\n`,
+  );
+}
+if (target) {
+  process.stdout.write(
+    `MustardScript: no installed prebuilt for ${target.platformArchABI}; building from source\n`,
+  );
+} else {
+  process.stdout.write(
+    `MustardScript: no configured prebuilt for ${process.platform}-${process.arch}; building from source\n`,
+  );
+}
+
+function nativeLibraryExtension(platform) {
+  switch (platform) {
+    case 'win32':
+      return '.dll';
+    case 'darwin':
+      return '.dylib';
+    default:
+      return '.so';
+  }
+}
+
+function parseCargoArtifactPath(output) {
+  const expectedExtension = nativeLibraryExtension(process.platform);
+  let artifactPath = null;
+  for (const line of output.split(/\r?\n/u)) {
+    if (line.trim() === '') {
+      continue;
+    }
+    let event;
+    try {
+      event = JSON.parse(line);
+    } catch {
+      continue;
+    }
+    if (event.reason !== 'compiler-artifact') {
+      continue;
+    }
+    if (event.target?.name !== 'mustard_node') {
+      continue;
+    }
+    if (
+      !Array.isArray(event.target?.crate_types) ||
+      !event.target.crate_types.includes('cdylib')
+    ) {
+      continue;
+    }
+    if (!Array.isArray(event.filenames)) {
+      continue;
+    }
+    const filename = event.filenames.find((entry) => entry.endsWith(expectedExtension));
+    if (filename) {
+      artifactPath = filename;
+    }
+  }
+  if (!artifactPath) {
+    throw new Error('MustardScript: cargo did not report a native cdylib artifact');
+  }
+  return artifactPath;
+}
+
+const cargo = process.env.CARGO || 'cargo';
+const cargoOutput = execFileSync(
+  cargo,
+  [
+    'build',
+    '--release',
+    '--manifest-path',
+    'crates/mustard-node/Cargo.toml',
+    '--message-format',
+    'json-render-diagnostics',
+  ],
+  {
+    cwd: packageRoot,
+    encoding: 'utf8',
+    stdio: ['ignore', 'pipe', 'inherit'],
+    env: process.env,
+  },
+);
+
+const artifactPath = parseCargoArtifactPath(cargoOutput);
+const outputPath = path.join(packageRoot, getLocalBuildOutputFile());
+fs.copyFileSync(artifactPath, outputPath);
+process.stdout.write(`MustardScript: built local addon at ${path.basename(outputPath)}\n`);

package/dist/lib/cancellation.js

@@ -0,0 +1,124 @@
+'use strict';
+
+const { types } = require('node:util');
+
+const { MustardError, callNative } = require('./errors.js');
+
+function throwIfAborted(signal) {
+  if (signal?.aborted) {
+    throw new MustardError('Limit', 'execution cancelled');
+  }
+}
+
+function getAbortSignal(options, label) {
+  if (options === undefined) {
+    return undefined;
+  }
+  if (options === null || typeof options !== 'object') {
+    throw new TypeError(`${label} must be an object`);
+  }
+  const { signal } = options;
+  if (signal === undefined) {
+    return undefined;
+  }
+  if (
+    typeof signal !== 'object' ||
+    signal === null ||
+    typeof signal.aborted !== 'boolean' ||
+    typeof signal.addEventListener !== 'function' ||
+    typeof signal.removeEventListener !== 'function'
+  ) {
+    throw new TypeError(`${label}.signal must be an AbortSignal`);
+  }
+  return signal;
+}
+
+function withCancellationSignal(native, fn, args, signal) {
+  if (signal === undefined) {
+    return callNative(fn, ...args);
+  }
+  const tokenId = callNative(native.createCancellationToken);
+  const cancel = () => {
+    try {
+      callNative(native.cancelCancellationToken, tokenId);
+    } catch {
+      // Ignore late cancellation after cleanup wins the race.
+    }
+  };
+
+  if (signal.aborted) {
+    cancel();
+  } else {
+    signal.addEventListener('abort', cancel, { once: true });
+  }
+
+  try {
+    return callNative(fn, ...args, tokenId);
+  } finally {
+    if (!signal.aborted) {
+      signal.removeEventListener('abort', cancel);
+    }
+    callNative(native.releaseCancellationToken, tokenId);
+  }
+}
+
+async function settleCapabilityInvocation(capability, args, signal) {
+  if (signal?.aborted) {
+    return { type: 'cancelled' };
+  }
+
+  let pending;
+  try {
+    pending = capability(...args);
+  } catch (error) {
+    return { type: 'error', error };
+  }
+
+  if (!types.isPromise(pending)) {
+    return { type: 'value', value: pending };
+  }
+
+  if (signal === undefined) {
+    try {
+      return {
+        type: 'value',
+        value: await pending,
+      };
+    } catch (error) {
+      return { type: 'error', error };
+    }
+  }
+
+  if (signal.aborted) {
+    pending.catch(() => {});
+    return { type: 'cancelled' };
+  }
+
+  const ABORTED = Symbol('aborted');
+  let onAbort = null;
+  const raced = await Promise.race([
+    pending.then(
+      (value) => ({ type: 'value', value }),
+      (error) => ({ type: 'error', error }),
+    ),
+    new Promise((resolve) => {
+      onAbort = () => resolve(ABORTED);
+      signal.addEventListener('abort', onAbort, { once: true });
+    }),
+  ]);
+  signal.removeEventListener('abort', onAbort);
+
+  if (raced === ABORTED) {
+    pending.catch(() => {});
+    return { type: 'cancelled' };
+  }
+
+  return raced;
+}
+
+module.exports = {
+  getAbortSignal,
+  settleCapabilityInvocation,
+  throwIfAborted,
+  withCancellationSignal,
+};