hardbyte / hardbyte/awa

Stabilize the SQL enqueue contract as a public producer API

Open
#342 0 comments 0 reactions 0 assignees View on GitHub
docs feature
Dominant language
Rust
Stars
32
Forks
5
Avg merge
15h 21m
Merged PRs (30d)
21

Description

## Problem

Awa's positioning is "Postgres job queue for Rust and Python", but a very common fleet shape is a third language on the *producer* side only — a Node/Go/JVM service enqueueing work for Rust/Python workers. Awa is close to supporting this:

- `awa.insert_job_compat(...)` is complete cross-storage enqueue plumbing (kind, queue, args, priority, run_at, metadata, tags, unique_key, unique_states).
- #314 documented and tested the SQL-only install/upgrade path for external migration tooling, so non-Rust deployments already have a schema story.

What's missing is the **public decision and contract**, not the mechanism. `_compat` records an internal storage-transition responsibility and should not become the permanent user-facing name.

## Proposal

Introduce `awa.insert_job(...)` as the stable public SQL producer capability. Keep `insert_job_compat` internal so its signature and implementation can evolve with the supported binary/schema window.

1. **Clean, single-signature name**: `awa.insert_job` has one exact input signature and documented result. Do not overload the public definer name or add competing default-parameter variants; exact function identity is part of the ACL and conformance contract.
2. **Document the contract**: parameter semantics, returned row shape, stable SQLSTATE errors (including unique conflict), and the transactional NOTIFY behaviour producers get for free.
3. **Evolve it deliberately**: compatible changes retain the clean name and signature. Breaking improvements follow ADR-036 deprecation and ADR-041 expand/migrate/contract. A temporary `awa.insert_job_v2` may coexist under a separate exact grant, but a declared breaking release may restore the clean canonical name after old callers retire; suffixes are migration tools, not permanent public history.
4. **Cross-language uniqueness**: document the exact BLAKE3 `unique_key` derivation, including input canonicalization and what `by_args`/`by_queue` fold in.
5. **Concurrency keys and shard routing**: freeze the domain-separated `concurrency_key` digest and ADR-033 precedence rule: explicit `ordering_key` selects the shard; otherwise `concurrency_key` selects a stable shard from its digest; only jobs with neither key use the rotor. Cross-language vectors cover both keyed routes and precedence when both keys are present.
6. **Contract tests**: provide a conformance script any producer implementation can run against a live schema, plus a docs example in one unsupported language (`node-postgres` or `pgx`) to prove the path.

Explicitly out of scope: official client libraries for other languages. The contract makes external producers *possible and safe*; maintaining idiomatic clients stays out of core scope.

Refs: ADR-002, ADR-016, ADR-025, ADR-033, ADR-036, ADR-043, #314, `docs/positioning.md`.

Contributor guide

No contributing guide indexed for this repository

Assessment

This issue has not been assessed yet.

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.