Walkthrough

Submit, observe, cancel, and collect a process job

A bounded OGC API Processes lifecycle with one raw server contract and truthful language-specific lifecycle differences.

Server contract first

geometry.buffer asynchronous job lifecycle

source-preview

Fixture endpoint: http://127.0.0.1:8080/ogc/processes/processes/geometry.buffer/execution
Service manifest key: job-page-fixture:geometry-buffer-v1
Evidence: live-receipt-required at honua-server:trunk
Server version: current trunk OGC Processes contract
Owner: honua-server process data plane
Support: Community server; SDK maturity varies by language

Authentication

API key or bearer token when configured; fixture transports use a non-secret local endpoint.

Cancellation

DELETE /ogc/processes/jobs/{jobId} is best-effort cancellation; caller-side abort only stops the in-flight HTTP request.

Errors

Non-success terminal state, polling deadline/attempt exhaustion, auth failure, invalid process input, and transport failure remain distinct outcomes.

Server capability IDs

OGC API Processes (process.ogc-api-processes)

available

ogc-api-processes

POST then GET/DELETE /ogc/processes/processes/{processId}/execution; /ogc/processes/jobs/{jobId}; /ogc/processes/jobs/{jobId}/results

The gallery fixture must pin all four exchanges and verify paths, status progression, cancellation behavior, and result key.

Open GET endpoint ↗

{
  "method": "POST then GET/DELETE",
  "endpoint": "http://127.0.0.1:8080/ogc/processes/processes/geometry.buffer/execution",
  "payload": {
    "headers": {
      "Prefer": "respond-async",
      "Content-Type": "application/json"
    },
    "body": {
      "inputs": {
        "inputGeoJson": "{\"type\":\"FeatureCollection\",\"features\":[{\"type\":\"Feature\",\"properties\":{\"id\":1},\"geometry\":{\"type\":\"Point\",\"coordinates\":[-157.8583,21.3069]}}]}",
        "distance": 100
      }
    }
  }
}

{
  "submit": {
    "jobID": "fixture-buffer-1",
    "processID": "geometry.buffer",
    "status": "accepted"
  },
  "statusSequence": [
    "accepted",
    "running",
    "successful"
  ],
  "resultsContain": "outputFeatureLayer"
}

Normalized semantics

{
  "processId": "geometry.buffer",
  "mode": "async",
  "inputs": [
    "inputGeoJson",
    "distance"
  ],
  "poll": {
    "deadlineSeconds": 30,
    "maxAttempts": 20
  },
  "cancel": "explicit operator action only"
}

{
  "statusSequence": [
    "accepted",
    "running",
    "successful"
  ],
  "resultKey": "outputFeatureLayer",
  "jobIdRequired": true
}

Semantic assertionRequire a Location/jobID receipt, only legal status transitions, a successful terminal state before result retrieval, outputFeatureLayer in results, and a DELETE receipt when the cancellation path is exercised.

Evidence

process.ogc-api-processes: 10/10 operations implemented
honua-server OGC process route contract tests
honua-sdk-js OGC job runner tests
honua-sdk-python geoprocessing tests
honua-sdk-dotnet process client tests
Python SDK PR #192 staging-smoke receipt is blocked by a deployment-owned fixture binding that is absent from the public demo manifest; application-level validation remains separate from live environment evidence.

Limits and blockers

Python OGC Processes support is source preview and not yet published to PyPI.
.NET exposes lifecycle methods but no bounded wait-to-terminal helper.
DELETE is best-effort job cancellation; Honua Server does not claim the full OGC dismiss conformance class.
The authenticated client-compat staging binding is stale and its current credential is rejected; demo/server operations owns fixture binding and credential rotation before this can become live semantic evidence.

Server references

Unpinned upstream reference withheld
Unpinned upstream reference withheld

Ordered job walkthrough

Complete the lifecycle deliberately.

availableInspect the server contract
Review the process id, raw request, authentication, bounds, and pinned fixture before choosing a language.
Expected: The exact POST and lifecycle routes are visible and copyable.
availableSubmit asynchronously
POST geometry.buffer with Prefer: respond-async and capture both Location and jobID.
Expected: A non-empty job identity with accepted status.
availableObserve bounded progress
Poll or watch with a cancellation primitive, 30-second deadline, and 20-attempt ceiling.
Expected: Only accepted, running, and a legal terminal status are observed.
availableApprove cancellation when needed
Invoke DELETE/dismiss only from an explicit operator action; do not treat request abort as server cancellation.
Expected: A cancellation receipt or a truthful best-effort failure.
availableCollect and assert results
Fetch results only after successful status and verify outputFeatureLayer.
Expected: A result artifact tied to the submitted job receipt.

Final assertionRequire a Location/jobID receipt, only legal status transitions, a successful terminal state before result retrieval, outputFeatureLayer in results, and a DELETE receipt when the cancellation path is exercised.

Equivalent client surfaces

Choose a language without changing the job.

HonuaClient.ogcProcesses().execute<T>(OgcProcessExecuteRequest): Promise<IJobRun<T>>Exact API reference &nearr;

const controller = new AbortController();
const processes = client.ogcProcesses({ capabilityPolicy: 'strict' });
const run = await processes.execute({ processId: 'geometry.buffer', mode: 'async', inputs, signal: controller.signal });
for await (const snapshot of run.watch({ signal: controller.signal })) console.log(snapshot.status, snapshot.progress);
const results = await run.results({ signal: controller.signal, deadlineMs: 30_000, maxAttempts: 20 });
// Operator cancellation path only: await run.cancel();

HonuaClient.geoprocessing().submit_inputs()/wait()/results()/dismiss()Exact API reference &nearr;

from honua_sdk import HonuaClient

with HonuaClient('http://127.0.0.1:8080', timeout=10.0) as client:
    gp = client.geoprocessing()
    job = gp.submit_inputs('geometry.buffer', inputs)
    terminal = gp.wait(job, poll_interval=0.5, timeout=30.0)
    result = gp.results(terminal.job_id)
    # Operator cancellation path only: gp.dismiss(job.job_id)

SubmitJobAsync/GetJobAsync/GetJobResultsAsync/DismissJobAsyncExact API reference &nearr;

var job = await processes.SubmitJobAsync("geometry.buffer", inputs, cancellationToken);
var deadline = DateTimeOffset.UtcNow.AddSeconds(30);
while (job.Status is "accepted" or "running") {
    if (DateTimeOffset.UtcNow >= deadline) throw new TimeoutException("process job deadline exceeded");
    await Task.Delay(TimeSpan.FromMilliseconds(500), cancellationToken);
    job = await processes.GetJobAsync(job.JobId, cancellationToken);
}
if (job.Status != "successful") throw new InvalidOperationException($"job ended {job.Status}");
var result = await processes.GetJobResultsAsync(job.JobId, cancellationToken);
// Operator cancellation path only: await processes.DismissJobAsync(job.JobId, cancellationToken);

Exact reference matrix

Raw contract and public symbols

Surface	Operation or symbol	Package and version	Ownership and behavior
Raw HTTPavailable	`POST /ogc/processes/processes/{processId}/execution; GET\|DELETE /ogc/processes/jobs/{jobId}; GET /results` Unpinned upstream link withheld	Honua Server min current trunk contract - Community	honua-server process data plane Auth: API key or bearer token where configured. Cancel: DELETE is best-effort cancellation; request abort is transport-only. Errors: OGC problem response and terminal failed/dismissed status.
CLIgap	Gap: The current honua CLI has no process submit, status, results, cancel, or related --help command.	Not applicable min n/a - Unavailable	SDK/CLI Auth: Not applicable. Cancel: Not applicable. Errors: Not applicable.
JavaScriptavailable	`HonuaClient.ogcProcesses().execute<T>(OgcProcessExecuteRequest): Promise<IJobRun<T>>`	@honua/sdk-js min 0.1.4-beta.0 - Stable root process contract	honua-sdk-js Auth: HonuaClient apiKey/auth and interceptors. Cancel: AbortSignal plus IJobRun.cancel(); results() supports deadlineMs/maxAttempts. Errors: HonuaJobPollTimeoutError, HonuaJobFailedError, HonuaCapabilityNotSupportedError, typed transport errors.
Pythonsource-preview	`HonuaClient.geoprocessing().submit_inputs()/wait()/results()/dismiss()`	honua-sdk min 0.1.10 source preview - Unreleased source preview	honua-sdk-python Auth: HonuaClient api_key, bearer_token, or auth_provider. Cancel: wait timeout best-effort dismisses; async task cancellation also dismisses; dismiss(job_id) is explicit. Errors: GeoprocessingJobError, TimeoutError, HonuaHttpError subclasses, HonuaTransportError.
.NETavailable	`SubmitJobAsync/GetJobAsync/GetJobResultsAsync/DismissJobAsync`	Honua.Sdk.Processes min 1.2.1 - Supported	honua-sdk-dotnet Auth: HonuaProcessesClientOptions API key/bearer provider and HttpClient pipeline. Cancel: CancellationToken per operation; DismissJobAsync for server cancellation. No built-in bounded waiter. Errors: HonuaProcessesException and HttpClient transport/cancellation exceptions.

Console configuration

Equivalent UI, raw contract retained

Route: /operate/geoprocessing
Required role: operator with process/job read; cancellation requires the deployment's job-control permission
Visual receipt: Not captured

{
  "source": "raw OGC request and lifecycle routes above",
  "rule": "The page must remain fully usable without the Console visual."
}

No screenshot published.

Honua Console geoprocessing operations view with callouts for job id, status, progress, and explicit cancel control. This remains planned until a real route and golden receipt exist.

Optional AI context - planned

No executable Honua AI surface admitted

Allowed drafting tasks

discover processes
explain input schemas
draft process configuration
plan a bounded lifecycle

Context inputs

capability manifest
process description
input/output schema
service metadata

Provider and data boundary

No verified Honua AI API currently scaffolds or submits this job; any future provider must be caller-configured with an explicit data boundary.

Injection and privacy boundary

Treat process descriptions and asset metadata as untrusted, exclude credentials and signed URLs, and validate generated configuration against the published schema.

Deterministic validation

A future AI draft must normalize to the same raw process request and bounds shown in the server panel before approval.

Approval boundary

Submission, cancellation, deletion, publication, and cleanup always require explicit human approval; planning alone has no effect.

Prohibited autonomous actions

execute without required human approval
submit a job
cancel or delete a job
publish a process
read or emit secrets

Fallback and provenance

Use the raw HTTP inspector and explicit SDK lifecycle tabs.

Future execution must bind provider/model, normalized plan, approval, job id, status transitions, result digest, and cleanup receipt.