Pristine logo

Pristine

pristine is the published runtime package from apps/pristine_runtime. It is the only package in this monorepo intended for Hex consumption.

Use Hex for normal runtime adoption:

{:pristine, "~> 0.4.0"}

The companion projects pristine_codegen and pristine_provider_testkit stay in this repository as GitHub-sourced build-time and test-time dependencies.

Runtime Surface

The public runtime boundary is:

Use Pristine.foundation_context/1 plus Pristine.execute_request/3 for the recommended production path and for generated provider SDKs. Use Pristine.Client plus Pristine.Operation when you want lower-level manual control over operation construction and execution.

For the covered Wave 3 unary lane, Pristine.Adapters.Transport.Finch remains the compatibility-named request adapter but now emits HttpExecutionIntent.v1 and delegates raw request/response execution to execution_plane. pristine still owns request shaping, auth, retries, telemetry, normalized responses, and the transport-versus-semantic failure boundary. Streaming and SSE remain on the explicit stream transport lane.

Standalone Example

Standalone direct use may still pass explicitly loaded local development credentials before constructing a Pristine context. Those values are direct runtime inputs only and do not satisfy governed authority.

context =

  Pristine.foundation_context(

    base_url: "https://api.example.com",

    transport: Pristine.Adapters.Transport.Finch,

    transport_opts: [finch: MyApp.Finch],

    serializer: Pristine.Adapters.Serializer.JSON,

    auth: [{Pristine.Adapters.Auth.Bearer, token: load_local_development_token()}]

  )



request = %{

  id: "widgets.list",

  method: :get,

  path_template: "/v1/widgets",

  query: %{"limit" => 10},

  auth: %{use_client_default?: true, override: nil, security_schemes: ["bearerAuth"]},

  resource: "widgets",

  retry: "widgets.read",

  circuit_breaker: "widgets_api",

  rate_limit: "widgets.integration",

  telemetry: [:my_sdk, :widgets, :list]

}



{:ok, response} = Pristine.execute_request(request, context)

Governed Operation Descriptor

Pristine.GovernedOperationDescriptor is a standalone-safe ref descriptor for OpenAPI operations that will be admitted by an owning control plane. It covers tool tasks, eval dataset loaders, generated SDKs, and AppKit management APIs without adding a Jido, Citadel, Mezzanine, or AppKit dependency to Pristine.

descriptor =

  Pristine.GovernedOperationDescriptor.new!(

    operation_ref: "pristine-operation://github/issues/list",

    connector_admission_ref: "connector-admission://tenant-1/github",

    provider_account_ref: "provider-account://tenant-1/github/app",

    credential_lease_ref: "credential-lease://tenant-1/github/app",

    operation_policy_ref: "operation-policy://tenant-1/github/issues/list",

    tenant_ref: "tenant://tenant-1",

    subject_ref: "subject://tenant-1/operator/ada",

    trace_ref: "trace://tenant-1/github/issues/list",

    redaction_ref: "redaction://tenant-1/github",

    usage_contexts: [:tool_task, :eval_dataset_loader, :generated_sdk, :appkit_management_api]

  )

Descriptors reject unmanaged auth material such as raw keys, bearer strings, token files, default clients, request auth overrides, and provider payloads.

Governed Example

Governed execution starts from an authority-materialized value. Direct base_url, headers, auth, request header overrides, request auth overrides, and OAuth saved-token sources are rejected when governed_authority is present.

authority =

  Pristine.GovernedAuthority.new!(

    base_url: "https://api.example.com",

    base_url_ref: "base-url://example/workspace-123",

    credential_handle_ref: "credential-handle://example/workspace-123",

    credential_lease_ref: "credential-lease://example/one-effect",

    target_ref: "target://example/production",

    request_scope_ref: "request-scope://example/widgets/list",

    header_policy_ref: "header-policy://example/default",

    materialization_kind: "bearer",

    bearer_token_ref: "bearer-token://example/one-effect",

    redaction_ref: "redaction://headers",

    headers: %{"x-authority-target" => "target://example/production"},

    credential_headers: %{"authorization" => "Bearer authority-materialized-token"},

    allowed_header_names: ["authorization", "x-authority-target"]

  )



context =

  Pristine.foundation_context(

    governed_authority: authority,

    transport: Pristine.Adapters.Transport.Finch,

    transport_opts: [finch: MyApp.Finch],

    serializer: Pristine.Adapters.Serializer.JSON

  )



{:ok, response} = Pristine.execute_request(request, context)

Unary Cancellation And Transport Capabilities (Pristine 0.4.0)

Cancellation support is explicit and fail-closed. A transport that only implements the historical c:Pristine.Ports.Transport.send/2 callback continues to work for ordinary calls, but a call that supplies cancellation: requires positive :unary_cancellation and :cancellation_cleanup advertisements plus send_cancelable/3. Pristine never falls back to send/2 for that call.

Inspect the configured contract without performing an HTTP request:

report = Pristine.RuntimeCapabilities.transport(context)



case report.capabilities.unary_cancellation.status do

  :supported -> :transport_declares_support

  :unsupported -> :transport_declares_no_support

  :unverified -> :fail_closed

end

A supported transport can receive an opaque cancellation token:

cancellation = Pristine.Cancellation.new()



task =

  Task.async(fn ->

    Pristine.execute_request(request, context, cancellation: cancellation)

  end)



:ok = Pristine.Cancellation.cancel(cancellation)



case Task.await(task) do

  {:error, %Pristine.Error{type: :cancelled}} -> :cancelled

  {:ok, response} -> {:completed, response}

end

Cancellation is not a transaction rollback. Once a request has been submitted, the upstream service may already have received or begun processing it even when the local HTTP operation is physically terminated. Pristine does not claim exactly-once or remote side-effect rollback semantics.

Built-in transport: Pristine.Adapters.Transport.Finch supports unary cancellation and cleanup through Execution Plane HTTP 0.2.0 sessions and OTP :httpc. The compatibility name does not imply Finch/Mint owns unary requests. Real HTTP/1.1 socket tests cover cancellation, normal completion, and caller death. This does not claim HTTP/2 unary support. Default retry waits also wake on cancellation; custom sleepers must cooperate to interrupt their own blocking work.

Why This Package Exists

pristine owns the generic runtime concerns shared by provider SDKs:

Generated SDKs describe requests. pristine executes them.

Auth ownership stays split intentionally:

Guides

Project Files

Workspace

Workspace-wide quality commands run from the repo root:

mix mr.compile

mix mr.test

mix ci

The Foundation retry adapter accepts retry_budget_ms: 30_000 to stop before a retry delay would reach the total call budget, preserving the last result. A zero base_ms or max_ms disables backoff while retaining Retry-After delays.