Skip to content

How Tracked Execution Works ​

This page uses three diagrams to show how your system works together with onestep to run a long task when you apply Tracked Execution: who is responsible for what, where the data flows, and what to prepare before integrating. Deployment details for both backends are covered in MySQL Tracked Execution and PostgreSQL Tracked Execution.

Three Roles ​

There are three components in the application. Outside the dashed boxes everything is provided by onestep; you only write the API routes and the task handler.

CodeProvided by
HTTP routes (submit / query / cancel)You
Task handlerYou
ExecutionClient / ExecutionSource / OneStepApponestep
DDL for the two tables and state transitionsonestep (create tables as migration role, run with auto_create=False)

Task state is a row in the database; no message queue is involved. The API process and the worker process never talk directly — they cooperate through the same set of tables.

Lifecycle of One Task ​

Key points:

  • Submit with an idempotency key: submitting the same key again returns the same execution instead of running it twice.
  • Only four terminal states: succeeded / failed / cancelled / expired; queued / running / retrying / cancel_requested are non-terminal and the client keeps waiting.
  • Cancellation is cooperative: cancel_requested is only a request; the worker converges to cancelled at the handler's next checkpoint and does not guarantee an immediate stop.

Clients: Python and TypeScript ​

There are two official ExecutionClient implementations for the API process; the worker is always an unmodified Python onestep:

ClientPackageBackendUse case
Python ExecutionClientonestep (core)MySQL / PostgreSQLFastAPI and other Python services
TypeScript ExecutionClient@mic1on/onestep-client (npm)PostgreSQLNext.js API routes, any Node ≥ 22.6 service

The TypeScript package deliberately implements only the client half of the protocol: submit / get / list / cancel / wait / result. claim / heartbeat / complete / reclaim are worker-side lease operations; calling them from TS raises a clear error — a second writer violating the lease semantics is worse than a missing API.

ts
import { ExecutionClient, PostgresBackend } from '@mic1on/onestep-client';

const backend = await PostgresBackend.create({ connectionString: process.env.DATABASE_URL! });
const client = new ExecutionClient({ backend, namespace: 'orders' });

const execution = await client.submit(
  'orders.sync',
  { orderId: 'A-1001' },
  { idempotencyKey: 'order-A-1001' },   // safe to retry
);
const done = await client.wait(execution.id, { timeoutMs: 300_000 });

Error-to-HTTP mapping follows the table above: ExecutionNotFound → 404, ExecutionNotReady → 202/409, ExecutionFailed → 422, ExecutionCancelled → 409, ExecutionExpired → 410.

The reason this package exists is cross-language consistency: Python computes the submission_digest with json.dumps(..., sort_keys=True, separators=(",", ":"), ensure_ascii=True), and JavaScript's JSON.stringify is not equivalent (float .0, Unicode escaping, and other differences make the same payload produce a different digest and trigger ExecutionConflict). The TS client replicates Python's encoding rules byte for byte (including JSON persistence and timestamptz microsecond precision) and is tested with bidirectional replay against a real PostgreSQL worker. See the in-repo clients/ts/README.md.

What to Prepare Before Integrating ​

For the full business semantics of each state, the exception mapping table, deployment steps, the go-live checklist, and rollback, see the backend pages:

Released under the MIT License.