draft_proxy

Mirrors the public-API surface of src/proxy-instance.ts and the dispatcher spine of src/proxy/routes.ts.

Routes real HTTP-shaped requests through the currently ported GraphQL domains plus the meta API (/__meta/health, /__meta/config, /__meta/log, /__meta/state, /__meta/reset, /__meta/commit). Unsupported paths and unported roots keep returning Shopify-like HTTP/GraphQL error envelopes until their domains land.

The TS class is mutable; this Gleam port is not. Each dispatch returns a #(Response, DraftProxy) pair so the synthetic identity registry (and, eventually, the store) can be threaded forward.

Types

Config

pub type Config =
  proxy_state.Config

DraftProxy

Re-exports of the runtime types defined in proxy_state. The real definitions live there so domain modules (customers, products, …) can take DraftProxy / Request / Response as parameters without importing draft_proxy and creating a cycle. External callers keep using draft_proxy.DraftProxy, draft_proxy.Request, draft_proxy.Response, draft_proxy.Config, and draft_proxy.ReadMode as type names; for the value-level constructors (Request(..), Response(..), Config(..), Snapshot, LiveHybrid, Live, DraftProxy(..)) tests should import from shopify_draft_proxy/proxy/proxy_state directly.

pub type DraftProxy =
  proxy_state.DraftProxy

GraphQLRequestOptions

Options accepted by process_graphql_request. Mirrors DraftProxyGraphQLRequestOptions in TS. Use default_graphql_request_options() for the empty value.

pub type GraphQLRequestOptions {
  GraphQLRequestOptions(
    path: option.Option(String),
    api_version: option.Option(String),
    headers: dict.Dict(String, String),
  )
}

Constructors

```
GraphQLRequestOptions(
  path: option.Option(String),
  api_version: option.Option(String),
  headers: dict.Dict(String, String),
)
```
Arguments

path

Override the request path. Defaults to /admin/api/<api_version>/graphql.json.

api_version

Override the API version segment of the default path. Ignored if path is provided.

headers

Headers to attach to the synthesized request.

ReadMode

pub type ReadMode =
  proxy_state.ReadMode

Request

pub type Request =
  proxy_state.Request

Response

pub type Response =
  proxy_state.Response

StateDumpError

Reasons restore_state can refuse a dump.

pub type StateDumpError {
  MalformedDumpJson(message: String)
  UnsupportedSchema(found: String)
  UnsupportedVersion(found: Int)
  UnsupportedStoreVersion(found: Int)
  InvalidSyntheticIdentity(synthetic_identity.RestoreError)
}

Constructors

```
MalformedDumpJson(message: String)
```
The dump string failed to parse as JSON, or was missing required fields with the expected types.
```
UnsupportedSchema(found: String)
```
The schema field didn’t match state_dump_schema.
```
UnsupportedVersion(found: Int)
```
The envelope version field wasn’t state_dump_version.
```
UnsupportedStoreVersion(found: Int)
```
The inner store.version field wasn’t store_dump_version.
```
InvalidSyntheticIdentity(synthetic_identity.RestoreError)
```
The synthetic identity portion failed validation. See synthetic_identity.RestoreError for details.

Values

commit

pub fn commit(
  proxy: proxy_state.DraftProxy,
  inbound_headers: dict.Dict(String, String),
) -> promise.Promise(
  #(proxy_state.Response, proxy_state.DraftProxy),
)

Run the upstream commit replay synchronously. Erlang-only — gleam_httpc blocks until upstream answers, so this returns the response paired with the next proxy state directly. Run the upstream commit replay asynchronously. JavaScript-only — fetch is Promise-based, so callers must await the result. Returns the same #(Response, DraftProxy) pair as the Erlang version once the Promise resolves.

config_summary

pub fn config_summary(config: proxy_state.Config) -> String

Render a port number for the cli/server adapter. Currently unused but exposed so callers can confirm the proxy was constructed with the right config.

default_config

pub fn default_config() -> proxy_state.Config

Default config, mirroring the values the TS test suite uses when no explicit config is supplied.

default_graphql_path

pub fn default_graphql_path(api_version: String) -> String

Build the default /admin/api/<version>/graphql.json path. Mirrors TS defaultGraphQLPath.

default_graphql_request_options

pub fn default_graphql_request_options() -> GraphQLRequestOptions

Empty options for process_graphql_request. Equivalent to passing {} to the TS processGraphQLRequest.

dump_state

pub fn dump_state(
  proxy: proxy_state.DraftProxy,
  created_at: String,
) -> json.Json

Snapshot all instance-owned runtime state to a JSON-compatible envelope. Mirrors the TS dumpState(). created_at is taken as a parameter so callers control whether the dump is deterministic; dump_state_now is the wall-clock convenience equivalent to TS.

dump_state_now

pub fn dump_state_now(proxy: proxy_state.DraftProxy) -> json.Json

Same as dump_state but reads wall-clock time for createdAt. Equivalent to TS dumpState().

get_config_snapshot

pub fn get_config_snapshot(
  proxy: proxy_state.DraftProxy,
) -> json.Json

Sanitised runtime configuration, equivalent to the TS class’s getConfig() and the body of GET /__meta/config. Returns the JSON tree directly so callers can json.to_string it or thread it into their own envelope.

get_log_snapshot

pub fn get_log_snapshot(
  proxy: proxy_state.DraftProxy,
) -> json.Json

Mutation log snapshot, equivalent to the TS class’s getLog() and the body of GET /__meta/log. Entries are returned in original replay order.

get_state_snapshot

pub fn get_state_snapshot(
  proxy: proxy_state.DraftProxy,
) -> json.Json

Base + staged in-memory state snapshot, equivalent to the TS class’s getState() and the body of GET /__meta/state.

new

pub fn new() -> proxy_state.DraftProxy

Fresh proxy with default config. Equivalent to new DraftProxy(...).

process_graphql_request

pub fn process_graphql_request(
  proxy: proxy_state.DraftProxy,
  body: String,
  options: GraphQLRequestOptions,
) -> #(proxy_state.Response, proxy_state.DraftProxy)

Convenience wrapper that synthesizes a POST to the Admin GraphQL path and dispatches it through process_request. Mirrors the TS class’s processGraphQLRequest(body, options).

process_graphql_request_async

pub fn process_graphql_request_async(
  proxy: proxy_state.DraftProxy,
  body: String,
  options: GraphQLRequestOptions,
) -> promise.Promise(
  #(proxy_state.Response, proxy_state.DraftProxy),
)

Async JavaScript-target variant of process_graphql_request. Keeps the default GraphQL route construction in Gleam while still allowing live-hybrid passthrough requests to await upstream fetch.

process_passthrough_async

pub fn process_passthrough_async(
  proxy: proxy_state.DraftProxy,
  request: proxy_state.Request,
  send: fn(request.Request(String)) -> promise.Promise(
    Result(commit.HttpOutcome, commit.CommitTransportError),
  ),
) -> promise.Promise(
  #(proxy_state.Response, proxy_state.DraftProxy),
)

Erlang-only test seam: dispatch a passthrough request with an injected send. Mirrors commit.run_commit_sync accepting a fake transport so tests don’t need a real HTTP server. Production callers should use process_request/2 or dispatch_graphql directly. JS-only test seam: same shape as process_passthrough_sync but the injected send returns a Promise.

process_request

pub fn process_request(
  proxy: proxy_state.DraftProxy,
  request: proxy_state.Request,
) -> #(proxy_state.Response, proxy_state.DraftProxy)

Process a request and return the response paired with the updated proxy state. The TS class returns just a response (mutating itself in place); the Gleam port returns both halves so callers can thread the registry forward.

process_request_async

pub fn process_request_async(
  proxy: proxy_state.DraftProxy,
  request: proxy_state.Request,
) -> promise.Promise(
  #(proxy_state.Response, proxy_state.DraftProxy),
)

Async dispatcher exposed only on JavaScript. Routes every request just like process_request/2, but the MetaCommit arm awaits the upstream fetch instead of returning a 501. Live-hybrid passthrough requests also await an upstream fetch. Other routes are wrapped in promise.resolve so callers can use a single async entry point.

registry_entry_has_local_dispatch

pub fn registry_entry_has_local_dispatch(
  entry: operation_registry.RegistryEntry,
) -> Bool

True when a registry entry names a root that this Gleam port can dispatch locally today. This intentionally gates on the explicit local dispatch table so registry metadata cannot claim unported roots as local support.

reset

pub fn reset(
  proxy: proxy_state.DraftProxy,
) -> proxy_state.DraftProxy

Clear staged state, mutation log, and synthetic identity counters. Mirrors the TS class’s reset() method and the body-effect of POST /__meta/reset.

restore_snapshot

pub fn restore_snapshot(
  proxy: proxy_state.DraftProxy,
  snapshot_json: String,
) -> Result(proxy_state.DraftProxy, StateDumpError)

Install a normalized snapshot JSON file into the proxy’s base state. Unknown state buckets are ignored so existing TypeScript snapshot files can be consumed incrementally as the Gleam port learns new domains.

restore_state

pub fn restore_state(
  proxy: proxy_state.DraftProxy,
  dump_json: String,
) -> Result(proxy_state.DraftProxy, StateDumpError)

Rebuild a proxy from a dump produced by dump_state. The supplied proxy provides the substrate (config, registry) the restored state is grafted onto. Mirrors the TS restoreState(dump) but returns a Result instead of throwing.

state_dump_schema

pub const state_dump_schema: String

The schema string used in the dump envelope. Mirrors DRAFT_PROXY_STATE_DUMP_SCHEMA in the TS proxy so dumps written by either implementation are accepted by both.

state_dump_version

pub const state_dump_version: Int

The version integer used in the dump envelope. Bump only when breaking the on-disk shape.

with_config

pub fn with_config(
  config: proxy_state.Config,
) -> proxy_state.DraftProxy

Fresh proxy with the supplied config.

with_default_registry

pub fn with_default_registry(
  proxy: proxy_state.DraftProxy,
) -> proxy_state.DraftProxy

Attach the vendored default registry built from config/operation-registry.json (mirrored as Gleam source in operation_registry_data.gleam).

with_registry

pub fn with_registry(
  proxy: proxy_state.DraftProxy,
  registry: List(operation_registry.RegistryEntry),
) -> proxy_state.DraftProxy

Attach a parsed operation registry to the proxy. Once attached, query/mutation dispatch routes by capability instead of the hardcoded predicates.

with_upstream_transport

pub fn with_upstream_transport(
  proxy: proxy_state.DraftProxy,
  transport: upstream_client.SyncTransport,
) -> proxy_state.DraftProxy

Install an injected upstream transport. Used by the parity runner to wire a recorded cassette into the proxy; production callers leave this unset.

Constructors

Arguments

Constructors