SandboxProviderJobCreateRequest sandbox-provider.job-create-request@1

Generated at from openvibe-contracts v0.177.0 and openvibe-sdk v0.44.0.

Version
1.0.0
Owner
run
Visibility
internal
Status
planned
Compatibility
backward
Decision
ADR-034
Schema
https://openvibe.network/contracts/sandbox-provider/job-create-request.v1.json

sandbox-provider.job-create-request@1 (PLANNED; plan T14 R4b, ADR-034): the body OpenVibe.Run POSTs to an external sandbox provider's (such as E2B or Fly Machines) job endpoint (capability sandbox_provider.job.dispatch). ID is the platform.job@1 id (job_<ULID>) and is also the idempotency key: a repeat POST with the same id answers the first job (200, created false) and never starts a second. CLASS is code or linux, the platform.runtime-class@1 classes a sandbox hosts. ARGS is the job's declared input as JSON (Run refuses more than 512 KiB serialized before it ever sends). INPUTS are files, each an OpenVibe.Media object pinned by sha256; never a URL, so the provider fetches nothing a caller chose. LIMITS are the hard caps of platform.job@1 (wall_ms required; cpu_ms and mem_bytes when the provider can enforce them). EGRESS is the network the job may reach, the values of OpenVibe.Node's worker.egress, as platform.job@1 `net` carries it. The request carries no project, subject, requester, token or other credential: the provider never learns who pays, and Run authenticates to it with a key from Run's own environment, sent in a header and never in this body. The provider's answer is sandbox-provider.job-create-result@1.

Fields

FieldTypeRequiredDescriptionConstraints
idhttps://openvibe.network/contracts/platform/job-frame.v1.json#/$defs/job_idyes
classenumyes
  • one of "code", "linux"
argsobjectyesThe job's declared input as JSON; Run enforces the 512 KiB cap before sending.
inputshttps://openvibe.network/contracts/run/job-create-request.v1.json#/$defs/inputyesFiles for the job, each an OpenVibe.Media object pinned by sha256; names are unique; empty when the job has none.
  • maxItems 32
limitsobjectyesCaps on the running job (platform.job@1 limits); the provider ends a job that hits one with exit_reason limit.
  • no other fields
limits.wall_msintegeryesRunning time from the job's start
  • minimum 1
limits.cpu_msintegerCPU time, user plus system; when the provider can enforce it
  • minimum 1
limits.mem_bytesintegerPeak resident memory; when the provider can enforce it
  • minimum 1
egresshttps://openvibe.network/contracts/run/job-create-request.v1.json#/$defs/egressyes

Examples

From the contract's own test fixtures: valid ones validate, rejected ones must fail.

Valid: full
{
  "id": "job_01JAB2C3D4E5F6G7H8J9K0MNPQ",
  "class": "code",
  "args": {
    "entry": "main.py"
  },
  "inputs": [
    {
      "name": "script.js",
      "media_id": "med_01JAB2C3D4E5F6G7H8J9K0MNPQ",
      "sha256": "9f86d081884c7d659a2feaa0c55ad015a3bf4f1b2b0b822cd15d6c15b0f00a08",
      "size_bytes": 482
    }
  ],
  "limits": {
    "wall_ms": 120000,
    "cpu_ms": 120000,
    "mem_bytes": 1073741824
  },
  "egress": "public"
}
Valid: minimal
{
  "id": "job_01JAB2C3D4E5F6G7H8J9K0MNPQ",
  "class": "code",
  "args": {},
  "inputs": [],
  "limits": {
    "wall_ms": 60000
  },
  "egress": "none"
}
Rejected: bad-id
{
  "id": "run_1",
  "class": "code",
  "args": {},
  "inputs": [],
  "limits": {
    "wall_ms": 60000
  },
  "egress": "none"
}
Rejected: class-not-sandbox
{
  "id": "job_01JAB2C3D4E5F6G7H8J9K0MNPQ",
  "class": "browser",
  "args": {},
  "inputs": [],
  "limits": {
    "wall_ms": 60000
  },
  "egress": "none"
}
Rejected: input-url
{
  "id": "job_01JAB2C3D4E5F6G7H8J9K0MNPQ",
  "class": "code",
  "args": {},
  "inputs": [
    {
      "name": "page.html",
      "url": "https://example.com/page.html"
    }
  ],
  "limits": {
    "wall_ms": 60000
  },
  "egress": "none"
}
Rejected: limits-without-wall
{
  "id": "job_01JAB2C3D4E5F6G7H8J9K0MNPQ",
  "class": "code",
  "args": {},
  "inputs": [],
  "limits": {
    "cpu_ms": 1000
  },
  "egress": "none"
}
Rejected: project-id
{
  "id": "job_01JAB2C3D4E5F6G7H8J9K0MNPQ",
  "class": "code",
  "args": {},
  "inputs": [],
  "limits": {
    "wall_ms": 60000
  },
  "egress": "none",
  "project_id": "prj_01JAB2C3D4E5F6G7H8J9K0MNPQ"
}
Rejected: subject
{
  "id": "job_01JAB2C3D4E5F6G7H8J9K0MNPQ",
  "class": "code",
  "args": {},
  "inputs": [],
  "limits": {
    "wall_ms": 60000
  },
  "egress": "none",
  "subject": "user:usr_01JAB2C3D4E5F6G7H8J9K0MNPQ"
}
Rejected: unknown-egress
{
  "id": "job_01JAB2C3D4E5F6G7H8J9K0MNPQ",
  "class": "code",
  "args": {},
  "inputs": [],
  "limits": {
    "wall_ms": 60000
  },
  "egress": "deny"
}

Validate

const contracts = require('openvibe-contracts');
contracts.validate('sandbox-provider.job-create-request@1', value);   // { valid, errors: [{ path, message }] }