mechanics-core

Core runtime for executing JavaScript automation modules with Boa in a worker pool.

Stateless by design: jobs should be self-contained, and correctness must not depend on in-process caching or sticky worker affinity. This supports horizontal scaling. Each job executes in an isolated JavaScript Realm, so globalThis mutations do not carry across jobs.

What this crate provides

• Bounded worker pool (MechanicsPool) for job execution.
• Synchronous non-blocking pool state snapshots (MechanicsPool::stats, MechanicsPoolStats).
• Swappable pool-level endpoint HTTP transport via MechanicsPoolConfig.endpoint_http_client (reqwest wrapper by default), useful for deterministic/mock testing. Transport execution runs on an internal Tokio runtime.
• Per-job execution limits (MechanicsExecutionLimits).
• Synthetic JS modules: mechanics:endpoint for preconfigured HTTP calls (GET/POST/PUT/PATCH/DELETE/HEAD/OPTIONS), mechanics:form-urlencoded, mechanics:base64, mechanics:hex, mechanics:base32, mechanics:rand, and mechanics:uuid.
• Endpoint config supports JSON-deserializable resilience policy (retry_policy) for retries/backoff/rate-limit handling.
• Structured error model (MechanicsError, marked #[non_exhaustive]) with stable symbolic kind enum (MechanicsErrorKind, #[repr(u8)]).

Public API is organized by module in src/lib.rs:

• root: MechanicsPool, MechanicsPoolConfig, MechanicsPoolStats, MechanicsError, MechanicsErrorKind
• mechanics_core::job: MechanicsJob, MechanicsExecutionLimits, MechanicsConfig
• mechanics_core::endpoint: HttpEndpoint, HttpMethod, EndpointBodyType, EndpointRetryPolicy, UrlParamSpec, QuerySpec, SlottedQueryMode
• mechanics_core::endpoint::http_client: EndpointHttpClient, ReqwestEndpointHttpClient, EndpointHttpRequest, EndpointHttpRequestBody, EndpointHttpResponse, EndpointHttpHeaders

Scopes

This crate is intended to be integrated into systems as automation/orchestration layers. While using JavaScript, this crate itself is not a Web thing.

In scope

• Execute user-provided JavaScript modules safely inside isolated Boa realms.
• Provide a synchronous Rust API (MechanicsPool) for bounded worker-pool execution.
• Keep runtime behavior stateless across jobs; no cross-job mutable runtime carryover.
• Offer JSON-first runtime/job configuration (serde parseability is a first-class feature).
• Provide preconfigured outbound HTTP endpoint execution via mechanics:endpoint, with URL/query/header policy enforcement from Rust config.
• Support request/response body modes with explicit size/time limits.
• Support endpoint-level retry/backoff/rate-limit policy.
• Expose a minimal set of built-in utility modules useful for automation/orchestration scripts (form-urlencoded, base64, hex, base32, rand, uuid).
• Support pluggable pool-level HTTP transport for deterministic/mock testing.

Out of scope (for now)

• Full async-first Rust API surface (Tokio-agnostic async abstractions).
• General-purpose workflow/orchestration DSL beyond JavaScript execution itself.
• Distributed scheduling, persistence, and cross-process job coordination.
• Cross-job in-process cache guarantees or sticky-worker semantics.
• Turnkey observability backend integrations (metrics/traces exporters).
• HTTP API hosting concerns (service routing, auth middleware, request admission).

Planned integration architecture

• This crate is planned to be embedded behind a separate Rust HTTP server that exposes automation-as-a-service endpoints.
• Bearer-token authentication/authorization is planned to be enforced in that server layer, not inside this crate.
• Metrics exporters and service-level telemetry pipelines are also planned for that server layer, not in mechanics-core.

Maturity path toward crates.io

• Pre-publication: favor correctness, safety, and API clarity; breaking Rust API changes are allowed.
• Stabilization phase (before crates.io release): tighten compatibility guarantees, freeze core config/job wire contracts, and provide migration notes for any remaining breaking changes.

API design constraint

• JSON-first is a core API constraint.
• MechanicsJob, MechanicsConfig, HttpEndpoint, and related runtime-facing config types are intended to be first-class serde_json inputs.
• Unknown JSON fields are rejected for these runtime-facing payload types.
• Rust-side builder/constructor helpers should complement JSON ingestion, not replace it.
• When tightening encapsulation/visibility, preserve non-breaking JSON parseability and keep validation behavior aligned between serde and Rust-native construction paths.
• This repository is public and is intended for crates.io publication once implementation matures.
• Until publication/stabilization, compatibility-breaking Rust API changes are acceptable when they improve API safety/clarity.

Contributor quick start

Prerequisites:

• Rust toolchain with support for edition 2024 (rustup default stable is usually sufficient).

From repo root:

cargo check
cargo test --all-targets
cargo clippy --all-targets --all-features

Contract consistency gate (recommended before release):

./scripts/check-contract-consistency.sh

Keep this script updated periodically as API names, module paths, and contract checks evolve.

Optional (environment-dependent) tests:

cargo test --all-targets -- --ignored

Ignored tests in src/internal/pool/tests/endpoint_network.rs require local socket bind permission.

Quick usage

Run the example runner:

cargo run --example test-script -- <json_config_path> <js_path>

Minimal Rust imports:

use mechanics_core::{MechanicsPool, MechanicsPoolConfig};
use mechanics_core::job::{MechanicsConfig, MechanicsJob};

Minimal files:

config.json

{
  "endpoints": {}
}

main.js

export default function main(arg) {
  return { ok: true, got: arg };
}

Documentation path policy

• In project docs, record file paths as project-relative paths (for example, src/internal/http/mod.rs).
• Do not record arbitrary absolute filesystem paths.

Documentation map

Canonical project documentation is maintained in this GitHub repository.

• docs/behavior.md: runtime behavior and API semantics.
• docs/development.md: contributor workflow, checks, and change checklist.
• docs/audit-findings.md: latest audit and resolved findings.
• ts-types/README.md: TypeScript declaration maintenance policy.
• ts-types/mechanics-json-shapes.d.ts: TypeScript interfaces for serde JSON payloads (MechanicsJob, MechanicsConfig, endpoint config).
• json-schema/*.schema.json: JSON Schemas for canonical job/config payload shapes.