@panorama-industries/effect-vercel-queue 0.0.0-stage → 0.1.0

package/src/contracts/queue-api.ts

@@ -0,0 +1,199 @@
+import type { VercelApiError, VercelRegion } from "@panorama-industries/effect-vercel-core";
+import type { Array, Duration, Effect, Option } from "effect";
+
+import { Context, Data, Schema } from "effect";
+
+import type {
+  BatchSizeOutOfRange,
+  ConcurrencyKey,
+  ConsumerDiscoveryFailed,
+  ConsumerGroupName,
+  ConsumerRegistryNotConfigured,
+  CursorFallback,
+  IdempotencyKey,
+  MessageAlreadyProcessed,
+  MessageCorrupted,
+  MessageHandle,
+  MessageId,
+  MessageNotAvailable,
+  MessageNotFound,
+  ReceivedMessage,
+  TopicName,
+} from "./queue-domain.ts";
+
+/** Maximum number of messages one receive call may lease: an integer from 1 to 10. */
+export const ReceiveLimit = Schema.Int.check(Schema.isBetween({ minimum: 1, maximum: 10 })).pipe(
+  Schema.brand("ReceiveLimit"),
+);
+
+/** Maximum number of messages one receive call may lease: an integer from 1 to 10. */
+export type ReceiveLimit = typeof ReceiveLimit.Type;
+
+/** Options for publishing one message, shared by single and batch sends. */
+export interface PublishOptions {
+  /** Drops a later publish carrying the same key while the first is retained. */
+  readonly idempotencyKey?: IdempotencyKey;
+
+  /** How long the message is kept: 1 minute to 7 days, default 24 hours. */
+  readonly retention?: Duration.Input;
+
+  /** Delay before the message becomes visible: up to 7 days and never beyond its retention. */
+  readonly delay?: Duration.Input;
+
+  /** Custom headers stored with the message. */
+  readonly headers?: Readonly<Record<string, string>>;
+
+  /** **Experimental.** See {@link ConcurrencyKey}. */
+  readonly experimentalConcurrencyKey?: ConcurrencyKey;
+}
+
+/** A serialized message ready to publish. */
+export interface OutgoingMessage extends PublishOptions {
+  readonly body: Uint8Array;
+  readonly contentType: string;
+}
+
+/** Outcome of publishing one message. */
+export type SendResult = Data.TaggedEnum<{
+  /** The queue accepted the message and assigned it an identifier. */
+  Sent: { readonly messageId: MessageId };
+  /** The queue accepted the message for deferred processing; it has no identifier yet. */
+  Deferred: {};
+}>;
+
+/** Constructors and matchers for {@link SendResult}. */
+export const SendResult = Data.taggedEnum<SendResult>();
+
+/**
+ * Outcome for one entry of a batch send, in input order.
+ *
+ * A request-level failure returns no per-entry results and may happen after the queue accepted
+ * some entries; set an idempotency key on every entry from the first attempt to make retries safe.
+ */
+export type BatchSendResult = Data.TaggedEnum<{
+  Sent: { readonly messageId: MessageId };
+  Deferred: {};
+  /** The queue rejected this entry; the others may still have been accepted. */
+  Failed: {
+    readonly status: number;
+    readonly message: string;
+    /** Whether publishing this entry again may succeed. */
+    readonly retryable: boolean;
+  };
+}>;
+
+/** Constructors and matchers for {@link BatchSendResult}. */
+export const BatchSendResult = Data.taggedEnum<BatchSendResult>();
+
+/** Result of extending a lease with an experimental handoff request. */
+export const HandoffOutcome = Schema.Literals(["accepted", "not_immediate", "limit_reached"]);
+
+/** Result of extending a lease with an experimental handoff request. */
+export type HandoffOutcome = typeof HandoffOutcome.Type;
+
+/** Options for leasing messages from a consumer group. */
+export interface ReceiveOptions {
+  /** Maximum messages to lease; the queue's default is 1. */
+  readonly limit?: ReceiveLimit;
+
+  /** How long leased messages stay invisible to other consumers. */
+  readonly visibilityTimeout?: Duration.Input;
+
+  /** Where a consumer group with no stored position starts reading. */
+  readonly cursorFallback?: CursorFallback;
+
+  /** Region to receive from; defaults to `QueueConfig.region`. */
+  readonly region?: VercelRegion;
+}
+
+/** Options for leasing one message by identifier. */
+export interface ReceiveByIdOptions {
+  readonly visibilityTimeout?: Duration.Input;
+
+  /** Region that holds the message; defaults to `QueueConfig.region`. */
+  readonly region?: VercelRegion;
+}
+
+/** Failures every queue call can report. */
+export type QueueRequestError = VercelApiError | ConsumerRegistryNotConfigured;
+
+/** Failures of publishing. */
+export type QueueSendError = QueueRequestError | ConsumerDiscoveryFailed;
+
+/** Failures of publishing a batch. */
+export type QueueSendBatchError = QueueSendError | BatchSizeOutOfRange;
+
+/** Failures of leasing a specific message. */
+export type QueueReceiveByIdError =
+  | QueueRequestError
+  | MessageNotFound
+  | MessageNotAvailable
+  | MessageAlreadyProcessed
+  | MessageCorrupted;
+
+/** Failures of settling a lease: acknowledging it or changing its visibility. */
+export type QueueLeaseError = QueueRequestError | MessageNotFound | MessageNotAvailable;
+
+/**
+ * The Vercel Queues HTTP API, one operation per endpoint, with bodies as bytes.
+ *
+ * Most code uses `QueueProducer`, `QueueConsumer` or `QueuePoller`, which add typed topics, leases
+ * and tracing on top of this service.
+ */
+export class QueueApi extends Context.Service<
+  QueueApi,
+  {
+    /** Publish one message (`POST /api/v3/topic/{topic}`). */
+    readonly send: (
+      topic: TopicName,
+      message: OutgoingMessage,
+    ) => Effect.Effect<SendResult, QueueSendError>;
+
+    /** Publish 1 to 100 messages in one request (`POST /api/v3/topic/{topic}/batch`). */
+    readonly sendBatch: (
+      topic: TopicName,
+      messages: Array.NonEmptyReadonlyArray<OutgoingMessage>,
+    ) => Effect.Effect<ReadonlyArray<BatchSendResult>, QueueSendBatchError>;
+
+    /**
+     * Lease the next available messages of a consumer group. An empty array means the queue had
+     * nothing to deliver.
+     */
+    readonly receive: (
+      topic: TopicName,
+      consumerGroup: ConsumerGroupName,
+      options?: ReceiveOptions,
+    ) => Effect.Effect<ReadonlyArray<ReceivedMessage>, QueueRequestError | MessageCorrupted>;
+
+    /** Lease one message by identifier, as push delivery does for messages sent without a body. */
+    readonly receiveById: (
+      topic: TopicName,
+      consumerGroup: ConsumerGroupName,
+      messageId: MessageId,
+      options?: ReceiveByIdOptions,
+    ) => Effect.Effect<ReceivedMessage, QueueReceiveByIdError>;
+
+    /**
+     * Acknowledge a leased message so the consumer group never receives it again.
+     *
+     * `experimentalIfCoalesced` acknowledges only if no more than that many messages have been
+     * coalesced into the delivery; otherwise it fails with `ConcurrencyCoalescedPending`.
+     */
+    readonly acknowledge: (
+      handle: MessageHandle,
+      options?: { readonly experimentalIfCoalesced?: number },
+    ) => Effect.Effect<void, QueueLeaseError>;
+
+    /**
+     * Set how long a leased message stays invisible, counted from now. A zero timeout releases the
+     * lease for immediate redelivery.
+     *
+     * @returns The handoff outcome when `experimentalHandoff` was requested, otherwise none.
+     */
+    readonly changeVisibility: (
+      handle: MessageHandle,
+      visibilityTimeout: Duration.Input,
+      options?: { readonly experimentalHandoff?: boolean },
+    ) => Effect.Effect<Option.Option<HandoffOutcome>, QueueLeaseError>;
+  }
+>()("@effect-vercel/queue/QueueApi") {}

package/src/contracts/queue-config.ts

@@ -0,0 +1,47 @@
+import type { DeploymentId, VercelRegion } from "@panorama-industries/effect-vercel-core";
+import type { Option, Redacted } from "effect";
+
+import { Context, Data } from "effect";
+
+/** How the client authenticates to the queue service. */
+export type QueueAuth = Data.TaggedEnum<{
+  /** Use the Vercel OIDC token of the current request (production and `vercel env pull`). */
+  Oidc: {};
+  /** Use a fixed bearer token, such as the local broker's `VERCEL_QUEUE_TOKEN`. */
+  Token: { readonly token: Redacted.Redacted<string> };
+}>;
+
+/** Constructors and matchers for {@link QueueAuth}. */
+export const QueueAuth = Data.taggedEnum<QueueAuth>();
+
+/** Where and as whom the queue client talks to Vercel Queues. */
+export class QueueConfig extends Context.Service<
+  QueueConfig,
+  {
+    /** Region for sends and receives that do not name one. */
+    readonly region: VercelRegion;
+
+    /**
+     * Base URL of the queue service in a region; the client appends `/api/v3/...`. The default is
+     * `https://{region}.vercel-queue.com`; the local broker ignores the region.
+     */
+    readonly baseUrl: (region: VercelRegion) => URL;
+
+    readonly auth: QueueAuth;
+
+    /**
+     * Deployment sent with consumer calls (receive, acknowledge, change visibility) so the queue
+     * routes them to this deployment's consumer registration. None for the local broker.
+     */
+    readonly deploymentId: Option.Option<DeploymentId>;
+
+    /**
+     * Whether sends are pinned to {@link deploymentId}, so only this deployment's consumers receive
+     * them. Pinning is the default on Vercel; turning it off lets newer deployments consume.
+     */
+    readonly pinSends: boolean;
+
+    /** Extra headers sent with every request. */
+    readonly headers: Readonly<Record<string, string>>;
+  }
+>()("@effect-vercel/queue/QueueConfig") {}

package/src/contracts/queue-consumer.ts

@@ -0,0 +1,40 @@
+import type { Effect } from "effect";
+import type { HttpServerRequest, HttpServerResponse } from "effect/http";
+
+import { Context } from "effect";
+
+import type { ConsumeOptions, MessageHandler } from "./message-handling.ts";
+import type { Topic } from "./topic.ts";
+
+/**
+ * Handles push deliveries: Vercel Queues calls a function route with a CloudEvent, and the route
+ * leases, processes and settles the message.
+ *
+ * ```ts
+ * export const POST = HttpEffect.toWebHandlerLayer(
+ *   QueueConsumer.use((consumer) => consumer.handler(Orders, fulfil)),
+ *   AppLayer,
+ * ).handler;
+ * ```
+ */
+export class QueueConsumer extends Context.Service<
+  QueueConsumer,
+  {
+    /**
+     * Build the HTTP handler for a push-delivered topic.
+     *
+     * Accepts structured (`com.vercel.queue.v1beta`) and binary (`com.vercel.queue.v2beta`)
+     * CloudEvents. Responds 200 when the message was processed or was already settled elsewhere,
+     * 400 for a malformed CloudEvent, and 500 to request redelivery.
+     */
+    readonly handler: <A, I, E, R, R2 = never>(
+      topic: Topic<A, I>,
+      handle: MessageHandler<A, E, R>,
+      options?: ConsumeOptions<E, R2>,
+    ) => Effect.Effect<
+      HttpServerResponse.HttpServerResponse,
+      never,
+      HttpServerRequest.HttpServerRequest | R | R2
+    >;
+  }
+>()("@effect-vercel/queue/QueueConsumer") {}

package/src/contracts/queue-domain.ts

@@ -0,0 +1,202 @@
+import { VercelRegion } from "@panorama-industries/effect-vercel-core";
+import { Schema } from "effect";
+
+/** Name of a queue topic: letters, digits, `_` and `-`. */
+export const TopicName = Schema.String.check(Schema.isPattern(/^[A-Za-z0-9_-]+$/)).pipe(
+  Schema.brand("TopicName"),
+);
+
+/** Name of a queue topic: letters, digits, `_` and `-`. */
+export type TopicName = typeof TopicName.Type;
+
+/** Name of a consumer group; each group receives every message of a topic once. */
+export const ConsumerGroupName = Schema.String.check(Schema.isPattern(/^[A-Za-z0-9_-]+$/)).pipe(
+  Schema.brand("ConsumerGroupName"),
+);
+
+/** Name of a consumer group; each group receives every message of a topic once. */
+export type ConsumerGroupName = typeof ConsumerGroupName.Type;
+
+/** Identifier the queue assigns to a message when it accepts it. */
+export const MessageId = Schema.NonEmptyString.pipe(Schema.brand("MessageId"));
+
+/** Identifier the queue assigns to a message when it accepts it. */
+export type MessageId = typeof MessageId.Type;
+
+/** Proof of one lease on a message; acknowledging or extending the lease requires it. */
+export const ReceiptHandle = Schema.NonEmptyString.pipe(Schema.brand("ReceiptHandle"));
+
+/** Proof of one lease on a message. */
+export type ReceiptHandle = typeof ReceiptHandle.Type;
+
+/** Key the queue uses to drop duplicate publishes of the same logical message. */
+export const IdempotencyKey = Schema.NonEmptyString.pipe(Schema.brand("IdempotencyKey"));
+
+/** Key the queue uses to drop duplicate publishes of the same logical message. */
+export type IdempotencyKey = typeof IdempotencyKey.Type;
+
+/**
+ * **Experimental.** Key that serializes processing: at most one message per key is leased at a
+ * time, and messages published while one is in flight may be coalesced into it.
+ */
+export const ConcurrencyKey = Schema.NonEmptyString.pipe(Schema.brand("ConcurrencyKey"));
+
+/** **Experimental.** Key that serializes processing of messages that share it. */
+export type ConcurrencyKey = typeof ConcurrencyKey.Type;
+
+/** Where a consumer group with no stored position starts reading a topic. */
+export const CursorFallback = Schema.Literals(["earliest", "latest"]);
+
+/** Where a consumer group with no stored position starts reading a topic. */
+export type CursorFallback = typeof CursorFallback.Type;
+
+/** Everything needed to acknowledge a leased message or change its visibility. */
+export class MessageHandle extends Schema.Class<MessageHandle>(
+  "@effect-vercel/queue/MessageHandle",
+)({
+  topic: TopicName,
+  consumerGroup: ConsumerGroupName,
+  messageId: MessageId,
+  receiptHandle: ReceiptHandle,
+  /** Region that issued the lease; follow-up calls must go to the same region. */
+  region: VercelRegion,
+}) {}
+
+/** **Experimental.** Present when a handler run is a rerun caused by coalesced messages. */
+export const ExperimentalCoalesced = Schema.Struct({
+  /** Which rerun of this delivery is executing, from 1. */
+  rerun: Schema.Int,
+  /** How many messages had been coalesced into this delivery when its acknowledgment was refused. */
+  coalescedCount: Schema.Int,
+});
+
+/** Facts about one delivery of a message, passed to message handlers. */
+export class MessageMetadata extends Schema.Class<MessageMetadata>(
+  "@effect-vercel/queue/MessageMetadata",
+)({
+  messageId: MessageId,
+  /** Number of times the message has been delivered, including this delivery (from 1). */
+  deliveryCount: Schema.Int,
+  createdAt: Schema.DateTimeUtc,
+  /** When the message expires and stops being delivered, set by its retention. */
+  expiresAt: Schema.DateTimeUtc,
+  topic: TopicName,
+  consumerGroup: ConsumerGroupName,
+  region: VercelRegion,
+  /** **Experimental.** How many handoffs preceded this delivery. */
+  experimentalHandoffCount: Schema.optionalKey(Schema.Int),
+  experimentalCoalesced: Schema.optionalKey(ExperimentalCoalesced),
+}) {}
+
+/** A leased message as returned by the queue, before its payload is decoded. */
+export class ReceivedMessage extends Schema.Class<ReceivedMessage>(
+  "@effect-vercel/queue/ReceivedMessage",
+)({
+  handle: MessageHandle,
+  metadata: MessageMetadata,
+  contentType: Schema.String,
+  body: Schema.Uint8Array,
+}) {}
+
+/** The message does not exist, or has expired (HTTP 404). */
+export class MessageNotFound extends Schema.TaggedError<MessageNotFound>()("MessageNotFound", {
+  messageId: Schema.String,
+}) {}
+
+/** Another consumer holds the lease; retry once it is released. */
+export class MessageLocked extends Schema.TaggedError<MessageLocked>()("MessageLocked", {
+  /** Delay the queue suggested before retrying, when it sent one. */
+  retryAfter: Schema.Option(Schema.Duration),
+}) {}
+
+/**
+ * **Experimental.** The acknowledgment was refused because messages with the same concurrency key
+ * were coalesced into this delivery after it started.
+ */
+export class ConcurrencyCoalescedPending extends Schema.TaggedError<ConcurrencyCoalescedPending>()(
+  "ConcurrencyCoalescedPending",
+  {
+    coalescedCount: Schema.Int,
+  },
+) {}
+
+/** The message exists but cannot be leased or settled right now, for no more specific reason. */
+export class MessageUnavailable extends Schema.TaggedError<MessageUnavailable>()(
+  "MessageUnavailable",
+  {
+    message: Schema.String,
+  },
+) {}
+
+/** The message cannot be leased or settled by this consumer (HTTP 409). */
+export class MessageNotAvailable extends Schema.TaggedError<MessageNotAvailable>()(
+  "MessageNotAvailable",
+  {
+    messageId: Schema.String,
+    reason: Schema.Union([MessageLocked, ConcurrencyCoalescedPending, MessageUnavailable]),
+  },
+) {}
+
+/** The message was already acknowledged by this consumer group (HTTP 410). */
+export class MessageAlreadyProcessed extends Schema.TaggedError<MessageAlreadyProcessed>()(
+  "MessageAlreadyProcessed",
+  {
+    messageId: Schema.String,
+  },
+) {}
+
+/** The queue returned a message whose headers or body could not be read. */
+export class MessageCorrupted extends Schema.TaggedError<MessageCorrupted>()("MessageCorrupted", {
+  messageId: Schema.String,
+  message: Schema.String,
+}) {}
+
+/**
+ * The queue could not reach the deployment that consumes this topic (HTTP 502,
+ * `consumer_discovery_failed`), usually because the pinned deployment is gone.
+ */
+export class ConsumerDiscoveryFailed extends Schema.TaggedError<ConsumerDiscoveryFailed>()(
+  "ConsumerDiscoveryFailed",
+  {
+    message: Schema.String,
+  },
+) {}
+
+/**
+ * The project has no consumer registry, so messages cannot be routed to consumers (HTTP 503,
+ * `consumer_registry_not_configured`).
+ */
+export class ConsumerRegistryNotConfigured extends Schema.TaggedError<ConsumerRegistryNotConfigured>()(
+  "ConsumerRegistryNotConfigured",
+  {
+    message: Schema.String,
+  },
+) {}
+
+/** A batch send had no entries or more than the queue's limit of 100. */
+export class BatchSizeOutOfRange extends Schema.TaggedError<BatchSizeOutOfRange>()(
+  "BatchSizeOutOfRange",
+  {
+    size: Schema.Int,
+    maximum: Schema.Int,
+  },
+) {}
+
+/** A payload did not match its topic's schema when it was published. */
+export class PayloadEncodeFailed extends Schema.TaggedError<PayloadEncodeFailed>()(
+  "PayloadEncodeFailed",
+  {
+    topic: Schema.String,
+    message: Schema.String,
+  },
+) {}
+
+/** A delivered message body did not match its topic's schema. */
+export class PayloadDecodeFailed extends Schema.TaggedError<PayloadDecodeFailed>()(
+  "PayloadDecodeFailed",
+  {
+    topic: Schema.String,
+    messageId: Schema.String,
+    message: Schema.String,
+  },
+) {}

package/src/contracts/queue-poller.ts

@@ -0,0 +1,76 @@
+import type { Effect } from "effect";
+
+import { Context, Data } from "effect";
+
+import type { ConsumeOptions, MessageHandler } from "./message-handling.ts";
+import type {
+  QueueLeaseError,
+  QueueRequestError,
+  ReceiveByIdOptions,
+  ReceiveOptions,
+} from "./queue-api.ts";
+import type { ConsumerGroupName, MessageCorrupted, MessageId } from "./queue-domain.ts";
+import type { Topic } from "./topic.ts";
+
+/** What a poll did. */
+export type ReceiveOutcome = Data.TaggedEnum<{
+  /** This many messages were leased and handled. */
+  Processed: { readonly count: number };
+  /** The consumer group had nothing to deliver. */
+  Empty: {};
+  /** The requested message does not exist or has expired. */
+  NotFound: { readonly messageId: MessageId };
+  /** Another consumer holds the requested message. */
+  NotAvailable: { readonly messageId: MessageId };
+  /** The requested message was already acknowledged by this consumer group. */
+  AlreadyProcessed: { readonly messageId: MessageId };
+}>;
+
+/** Constructors and matchers for {@link ReceiveOutcome}. */
+export const ReceiveOutcome = Data.taggedEnum<ReceiveOutcome>();
+
+/** Options for one poll: lease options plus how to handle the leased messages. */
+export type PollOptions<E, R> = ConsumeOptions<E, R> &
+  Pick<ReceiveOptions, "limit" | "cursorFallback" | "region"> & {
+    /**
+     * How many leased messages are handled at once. Default: `"unbounded"`. Messages waiting their
+     * turn keep their leases renewed, so a lower value never lets a lease expire. In a function,
+     * keep `limit × handler time / concurrency` well under `maxDuration`.
+     */
+    readonly concurrency?: number | "unbounded";
+  };
+
+/** Options for polling one message by identifier. */
+export type PollByIdOptions<E, R> = ConsumeOptions<E, R> & Pick<ReceiveByIdOptions, "region">;
+
+/**
+ * Pulls messages from a consumer group and handles them, for workloads that run outside push
+ * delivery such as workers and cron jobs.
+ */
+export class QueuePoller extends Context.Service<
+  QueuePoller,
+  {
+    /**
+     * Lease up to `limit` messages and handle them, concurrently by default.
+     *
+     * @returns The outcome, or the handler's error when the error policy answered `Fail`. Also
+     *   fails with `MessageNotFound` or `MessageNotAvailable` when a lease was lost before the
+     *   message could be acknowledged.
+     */
+    readonly receive: <A, I, E, R, R2 = never>(
+      topic: Topic<A, I>,
+      consumerGroup: ConsumerGroupName,
+      handle: MessageHandler<A, E, R>,
+      options?: PollOptions<E, R2>,
+    ) => Effect.Effect<ReceiveOutcome, E | QueueLeaseError | MessageCorrupted, R | R2>;
+
+    /** Lease one message by identifier and handle it. */
+    readonly receiveById: <A, I, E, R, R2 = never>(
+      topic: Topic<A, I>,
+      consumerGroup: ConsumerGroupName,
+      messageId: MessageId,
+      handle: MessageHandler<A, E, R>,
+      options?: PollByIdOptions<E, R2>,
+    ) => Effect.Effect<ReceiveOutcome, E | QueueRequestError | MessageCorrupted, R | R2>;
+  }
+>()("@effect-vercel/queue/QueuePoller") {}

package/src/contracts/queue-producer.ts

@@ -0,0 +1,40 @@
+import type { Array, Effect } from "effect";
+
+import { Context } from "effect";
+
+import type {
+  BatchSendResult,
+  PublishOptions,
+  QueueSendBatchError,
+  QueueSendError,
+  SendResult,
+} from "./queue-api.ts";
+import type { PayloadEncodeFailed } from "./queue-domain.ts";
+import type { Topic } from "./topic.ts";
+
+/** One payload of a batch send with its publish options. */
+export interface BatchEntry<A> extends PublishOptions {
+  readonly payload: A;
+}
+
+/** Publishes typed payloads to topics. */
+export class QueueProducer extends Context.Service<
+  QueueProducer,
+  {
+    /** Encode a payload with its topic's schema and publish it, in a `vqs.send` producer span. */
+    readonly send: <A, I>(
+      topic: Topic<A, I>,
+      payload: A,
+      options?: PublishOptions,
+    ) => Effect.Effect<SendResult, QueueSendError | PayloadEncodeFailed>;
+
+    /**
+     * Encode and publish 1 to 100 payloads in one request. Inspect every result: a batch can mix
+     * sent, deferred and failed entries.
+     */
+    readonly sendBatch: <A, I>(
+      topic: Topic<A, I>,
+      entries: Array.NonEmptyReadonlyArray<BatchEntry<A>>,
+    ) => Effect.Effect<ReadonlyArray<BatchSendResult>, QueueSendBatchError | PayloadEncodeFailed>;
+  }
+>()("@effect-vercel/queue/QueueProducer") {}

package/src/contracts/topic.ts

@@ -0,0 +1,76 @@
+import { Schema, SchemaTransformation } from "effect";
+
+import { TopicName } from "./queue-domain.ts";
+
+/**
+ * A queue topic and the schema of its payloads, shared by the code that publishes to it and the
+ * code that consumes it.
+ *
+ * @template A - Payload type handlers receive and producers send.
+ * @template I - Encoded form of the payload before it is serialized to bytes.
+ */
+export interface Topic<A, I = A> {
+  readonly name: TopicName;
+
+  /** Schema of the payload, as given by the topic's author. */
+  readonly schema: Schema.Codec<A, I>;
+
+  /** Content type sent with every message of this topic. */
+  readonly contentType: string;
+
+  /** Converts between the payload and the bytes stored in the queue. */
+  readonly wire: Schema.Codec<A, Uint8Array>;
+}
+
+const utf8Encoder = new TextEncoder();
+const utf8Decoder = new TextDecoder();
+
+const Utf8String = Schema.Uint8Array.pipe(
+  Schema.decodeTo(
+    Schema.String,
+    SchemaTransformation.transform<string, Uint8Array>({
+      decode: (bytes) => utf8Decoder.decode(bytes),
+      encode: (text) => utf8Encoder.encode(text),
+    }),
+  ),
+);
+
+/**
+ * Define a topic whose payloads travel as JSON (`application/json`).
+ *
+ * @param name - Topic name; an invalid name is a defect raised where the topic is defined.
+ * @param schema - Payload schema; its encoded form must be JSON-serializable.
+ */
+const json = <A, I>(name: string, schema: Schema.Codec<A, I>): Topic<A, I> => ({
+  name: TopicName.make(name),
+  schema,
+  contentType: "application/json",
+  wire: Utf8String.pipe(Schema.decodeTo(Schema.fromJsonString(schema))),
+});
+
+/**
+ * Define a topic whose payloads are raw bytes (`application/octet-stream`).
+ *
+ * @param name - Topic name; an invalid name is a defect raised where the topic is defined.
+ */
+const bytes = (name: string): Topic<Uint8Array> => ({
+  name: TopicName.make(name),
+  schema: Schema.Uint8Array,
+  contentType: "application/octet-stream",
+  wire: Schema.Uint8Array,
+});
+
+/** Constructors for {@link Topic} definitions. */
+export const Topic = { json, bytes };
+
+/** Type helpers for {@link Topic}. */
+export declare namespace Topic {
+  /** Any topic, regardless of payload type. */
+  export type Any = Topic<any, any>;
+
+  /** Payload type of a topic, like `Schema.Type`. */
+  export type Type<T extends Any> = T extends Topic<infer A, any> ? A : never;
+
+  /** Encoded payload type of a topic, like `Schema.Encoded`. */
+  export type Encoded<T extends Any> = T extends Topic<any, infer I> ? I : never;
+}