The Rust implementation follows the TypeScript framework's behavior: the same database tables, HTTP routes, payloads, encryption formats and admin screens. This page lists every place where it intentionally differs.
| TypeScript | Rust |
|---|---|
openshop.config.ts loaded by the openshop CLI |
Your binary declares an App with app! and runs it with APP.main() |
defineFlow({ … }) and defineProvider({ … }) returning a definition |
An attribute on the function or the struct itself (#[flow], #[provider]), which app! lists by name |
proxy/, routes/ and admin/pages/ discovered from files |
#[proxy(GET, "/path")], #[route(GET, "/path")] and #[admin_page("/path")] on the code, listed in app! |
Hot reload of the config module in dev |
openshop dev rebuilds and restarts the process, and the admin UI reloads by itself |
process.env read on each request |
Environment captured once in RuntimeEnv at startup |
getDb() and other process globals |
An OpenShop handle (ctx.app, ctx.db) passed to every handler |
arktype schemas |
Types marked #[input], read with serde and described by a schemars JSON Schema, and field validators |
Consequences:
- Shopify apps are resolved once at startup. A missing Shopify TOML file or
missing
client_idstops the process instead of failing each request. - Invalid definitions are rejected when the configuration is built: ambiguous proxy, route or admin page paths, a route without handlers, navigation that points to an unknown page, an invalid cron expression, a block registered twice under the same key.
- The
inputof a cron is validated against the input of its flow when the configuration is built. A cron whose input the flow refuses stops the process at startup with[openshop] Invalid config: crons[0].input is not an input of flow "syncOrders": …, instead of producing a failed run at each occurrence. - Custom admin pages are served as soon as they are listed in
admin_pages: there is no separate switch to enable them. A page declares its entry in the menu withnav = "Label", and theadmin_menusetting sets the menu by hand. There is noexperimentalsetting:experimental.customPages.navigationisadmin_menu, and its errors nameadminMenu[0].path. GET /api/flowsand the MCP toolopenshop.flows.listreturninputSchemaas JSON Schema (ornull) rather than arktype's JSON format. Validation messages differ accordingly; they still start withInvalid input for flow "<name>":.- Route parameters are written
:name. The file-style[name]is accepted.
The TypeScript version infers connectors.warehouse.push(data) from the
provider definitions. Rust has no equivalent inference across a registry, so
connectors are reached by name. Two additions close most of that gap and make
larger configurations easier to split:
- A provider is a struct:
#[derive(ProviderConfig)]makes its fields the configuration form, and#[provider]makes the methods of itsimplblock the methods of the provider, called withWarehouse::on(&ctx.connectors).push(&orders). The compiler checks the method, its arguments and its result. See Providers. - Underneath,
ProviderCall<A, R>constants withProvider::handleandProvider::typed_checker, for a provider built without a struct. See Typed calls. - Blocks are declared in the module that writes them and
app!lists them by name, so a large application has no registration code to split.
- A running step is interrupted as soon as its run is canceled, and is recorded
as
canceled. The TypeScript engine only checked between steps. - Cancellation works across processes: when a worker's heartbeat finds that it no longer owns the run (canceled through the API, or the lease taken over), it cancels the flow.
- A flow that exceeds its
timeoutis stopped. In TypeScript the flow function kept running in the background after the run was marked failed. - A panic inside a flow, a webhook, a proxy or route handler, a custom admin page loader, action or access rule, a provider checker, or the error hook is caught and treated as a failure of that unit of work.
- Log lines are written in emission order with their emission time, and are fully persisted when a run finishes. Lines logged within 50 ms of each other share one statement, and the lines a flow logged are stored before the outcome of its run.
- A worker keeps polling when claiming a run fails, for example during a database outage.
- A worker with every slot taken claims again as soon as a run finishes, and
claims as many runs as it has free slots in one statement. The TypeScript
engine waits a poll interval when its slots are full and claims one run per
statement, which caps a worker at
concurrencyruns per poll interval. - Claiming reads the queue through a partial index, so its cost does not grow with the number of runs waiting.
- The logs of a run are served by page (
limit,cursor,next, andlevelCountsbesidelogsandtotal) and the export is streamed. Thelogstable has indexes on its time and its level, and workers remove the lines past thelog_retentionsetting when it is set. The columns are those of the TypeScript runtime, which keeps reading and writing the table. - Runs past their deadline are failed once per poll interval, including while every slot is taken, instead of before each claim. A claim skips them, so none starts late.
- A worker extends its lease four times per lease period (every 15 seconds at most). The TypeScript engine always waited 15 seconds, so a lease shorter than that let another worker take over a run that was still executing.
- A worker only marks a run as failed while it still owns it.
- The
workercommand usesworker.concurrencyfrom the configuration when--concurrencyis absent; the original always fell back to 5. A value that is not a positive integer is an error. - A step whose future is dropped before it finishes (flow timeout, panic) is
recorded as
failedwith the errorStep was interruptedinstead of stayingrunning. - A run that completes after a failed attempt no longer keeps the error of that attempt; the logs still show it.
- Cron schedules accept nicknames such as
@dailyin addition to five- and six-field expressions. They are read in UTC, or in the IANA time zone given with.timezone(…), and not in the time zone of the host. A process that wakes late fires the latest occurrence it missed, once. - Error messages stored on runs and steps include the context chain
(
while syncing: connection refused).
- An identifier that is not a UUID returns
404(Run not found,Token not found) instead of a database error. POST /api/crons/togglerequireskey(string) andenabled(boolean) and answers400otherwise, and404(Cron not found) for a key that is not a cron the shop sees.- A shop only sees the crons that apply to it: those that run once without a
shop, those of every shop, and those that name it.
GET /api/crons,GET /api/flowsand the MCP toolsopenshop.crons.listandopenshop.flows.listleave out the crons of other shops, and show only the shop of the caller among the shops a cron names. POST /api/runs/bulk-deleteanswers400 No IDs providedfor a missing or invalid body; identifiers that are not UUIDs count as skipped.- Retry, cancel and delete check the status of the run in the write itself, so
a run that changed meanwhile is answered
409. A retry of a flow that rejects concurrent runs answers409withexistingRunIdwhile another run of it is active for the shop. - Log export uses JSON, in a
.jsonfile, for anyformatother thancsv. - Run details list steps in creation order.
- Unknown paths under
/apireturn404after authentication. - Request bodies are limited to 2 MB (
413above that). Setmax_request_body_bytesinapp!to change the limit. The MCP endpoint keeps its own 1 MB limit. - A request whose response has not begun after 60 seconds is answered with
503, and one that comes while 1024 are being served with503andRetry-After: 1;request_timeoutandmax_concurrent_requestsinapp!change them. Verifying an MCP token runs at most a few scrypt hashes at once and remembers a right secret for five minutes; the stored hash is the same. - Responses of 1 KB or more are compressed (gzip or Brotli) when the client accepts it.
- With custom admin pages, a static page takes precedence over a dynamic
sibling:
/reviews/newis handled by its own page rather than rejected as ambiguous with/reviews/:id. - A custom admin page can be declared at
/: it is the home of the admin, in place of the built-in dashboard.AdminPagesConfig::none()disables every built-in page, and such an application must declare that home. - Turning MCP off, with
mcp: McpConfig::disabled()or.enabled(false), also disables the MCP page of the admin and/api/mcp/*, unless the application sets a mode for that page with thebuiltin_pagessetting or.builtin_page(AdminPageId::Mcp, …).
- A
#[proxy]or#[route]function can take a typed input as its second argument, read from the query string or from the JSON body. A request that does not fit it is answered with422and{ "error": "Invalid input: …" }before the function runs. A function without a typed input reads the query and the body itself, and no request is refused for its shape. - Liquid answers come from template files, embedded with
liquid!. A value of the server is passed with.assign(name, value)and written before the template as a{% assign %}tag, escaped so that it cannot close its literal or its tag. A template is not built by interpolating values into a string.
- The Admin API only accepts session tokens issued to a staff user. A token
whose
subis empty or a customer (gid://shopify/Customer/…) is rejected with401, even though it is signed with the same secret. Customer account tokens remain valid on/extand/proxy. - A blank
SHOPIFY_API_SECRET(whitespace only) counts as not configured everywhere, including session token verification. - Session tokens, launches, OAuth callbacks, app proxy requests and webhooks
are verified by
shopify_api: ten seconds of clock skew on a session token, whosedestandissare exactlyhttps://<shop>.myshopify.comand its/admin; a signed launch, callback or app proxy request of the last 90 seconds; a webhook whose body is a JSON object, with itsX-Shopify-TopicandX-Shopify-Shop-Domainheaders. POST /auth/webhooks/app-uninstalleduninstalls the shop that both the signed payload (myshopify_domain) and the unsignedX-Shopify-Shop-Domainheader name, and nothing when they differ.- App proxy signatures are compared as strict hexadecimal. A valid signature followed by other characters is rejected.
- A page of the admin is sent with
Content-Security-Policy: frame-ancestors https://<shop> https://admin.shopify.com;, the shop of its session token, andCache-Control: no-store. - MCP token hashing and verification run outside the async runtime.
- The admin is rendered by the server: each page is HTML made of Polaris web
components, with one small script,
openshop.js, that sends its forms and follows its links. There is no bundle to build or to serve. A page is authenticated with a Shopify session token, the one of the launch URL, or the one App Bridge'sfetchadds; a page loaded without one goes through/auth/session-token, the bounce page of Shopify's libraries. - Custom admin pages are
#[admin_page]blocks whose view returnsMarkup, in place ofpage.tsxfiles compiled by Vite. - In
dev, there is no Vite server and no module replacement: a page reloads when the app has been started again, whichGET /__openshop/reload, a route ofdevonly, tells it. - A visitor without a valid launch receives a page written with Polaris web
components, with the same
401and the same sentence.devanswers its403with that page instead of plain text, and the admin shows it to a visitor without a session. - The operator dashboard under
/opshas no TypeScript counterpart: pages rendered by the server, without script, that show every shop over a period (runs, log lines, flows, shops, crons), read-only, behind the password the application gives withops_password. It adds no table.opsis a reserved first segment for custom admin pages. - Sentry reporting is part of the framework: with the
sentrysetting, failed runs, failed handlers, and panics are reported with their flow and their shop. It was not ported from the TypeScript version.
- Migrations are SQL files in
./migrations, applied in file-name order and recorded in the__openshop_migrationstable. There is no Drizzle journal. - The first migration generated for a model takes over a table that Drizzle
created: it adds what is missing, converts
jsontojsonb, and renames the indexes and foreign keys of Drizzle to the names of the model. See Switch from the TypeScript version. - A model is a struct with
#[derive(Model)]instead of a Drizzle table. Its typed rows cover insertion, lookup, filters on columns, ordering, update and deletion, limited to a shop; there is no general query builder, and other queries are SQL strings run withsqlx, which can check them at compile time withsqlx::query!. Installation,FlowRun,StepResult, andLogRoware read with typed columns, across shops or for the shop of a context, and never written through them. See Read the framework tables.#[model(references(Other))]declares a foreign key, like.references()in Drizzle. There are no relational queries: the other side of a reference is read with a filter or a join.migrate generatecompares the models withmigrations/schema.snapshot.jsonand writes the difference, likedrizzle-kit generatewith its snapshots. It never asks questions: a rename is declared withrenamed_from, and a statement that can lose data or fail is written with a warning.migrate checkfails when the framework schema is not covered or when the models changed since the last generated migration.- A migration that was modified after being applied is rejected.
devand the test harness create missing tables directly and add missing columns and indexes. They do not rename, retype or drop anything.- The pool learns that PostgreSQL closed an idle connection when it uses it
again, where
pg.Pooldrops the client as soon as its socket closes. A connection that waited more than a second is pinged first, and replaced when the ping fails; one reused sooner is not checked, and fails the statement it is given if it was closed. See Idle connection check. - A
PGPOOL_*value that is not a non-negative integer falls back to its default instead of going throughNumber().0keeps the meaning it has forpg.Pool: no timeout, and the default size forPGPOOL_MAX. - While PostgreSQL refuses connections, a statement waits and the pool retries
until
PGPOOL_CONNECTION_TIMEOUT_MS, wherepg.Poolfails at once. With the timeout disabled, it waits until PostgreSQL is back.
OPENSHOP_ENV=productionenables production mode (NODE_ENV=productionis honored too): the schema push is refused.ENCRYPTION_KEYis required unlessOPENSHOP_ENVisdevelopmentortest(NODE_ENVdoes not count), or the command isdev. The application does not start without it, in production or in any environment that is not explicitly a development one.
- The ESLint preset and the Vite plugins.
- GraphQL code generation as a separate step.
graphql!checks an operation against Shopify's schema and types it when the crate compiles, so there is no.graphqlrc.ts, no generated file and no watch mode, anddevhas nothing to generate. The schema of the version of[package.metadata.shopify_api]is a committed file. Enum values are strings, and the types of an inline operation have no name. See Typed GraphQL. openshop buildandopenshop testmap tocargo build --releaseandcargo test.- The proxy test client's
.expect(schema); deserialize the response instead.