Files
archie/internal/domain/workintake/envelope.go
T
sam 9d5040fd65 refactor: add internal/eventbus as the broker-neutral messaging contract
dependencies-and-contracts.md rule 1 says domains must not import
internal/infrastructure. internal/daemon and internal/agentexec both did,
and for exactly the thing the doc carves out: "internal/eventbus is an
approved shared application contract ... it MUST remain broker-neutral."

The Publisher/Consumer/Requester interfaces existed but lived inside the
NATS package, so a caller could depend on the behaviour yet still had to
import the implementation to name it. They now live in internal/eventbus,
and nats.Client asserts against eventbus.Bus.

The larger violation was ownership of meaning. The doc says "message schemas
stay with their owning domains; the event bus transports messages, it does
not own their meaning." The bus exported TaskEnvelope and a PublishTask
method, so the transport knew what a unit of work was, and it exported the
archie.agent.* subject helpers, so it also owned the agent protocol.

  - TaskEnvelope, its routing Kind, the label vocabulary and the task
    subjects move to internal/domain/workintake, which encodes and decodes
    its own bytes. This starts internal/domain/ per organisation.md.
  - The agent request/response/system subjects move to internal/agentexec,
    which defines what those messages mean.
  - internal/workflow keeps only the kind-to-registry mapping; the label
    table stays single and lives with the domain that reads forge issues.
  - The bus now carries opaque payloads on plain-string subjects.

Consumers declare the smallest interface they need rather than taking the
whole Bus: daemon.TaskBus is publish-unique/fetch/request, agentexec.
RequestBus is publish-request/reply-inbox, and archie-agent's stageBus is
fetch/respond. None can reach what it does not use.

Two defects this surfaced:

  - archie-agent declared its own JetStream stream with a second copy of the
    name, subjects, retention, dedup window, MaxDeliver and TTLs that
    nats.Connect already sets -- two definitions of one stream, free to
    diverge. Config now takes Subjects and FilterSubject from composition,
    which is what let the agent use the shared client and delete its
    hand-rolled setup.
  - Replying to a request needs core NATS, not the JetStream publish path:
    a reply inbox is ephemeral and belongs to no stream, so a durable
    publish to it fails. The old code hid this by using the raw connection.
    The contract now distinguishes Respond from Publish. The agentexec
    round-trip test caught it after I had made the same mistake in
    archie-agent.

Also translated the SDK's ErrNoResponders into eventbus.ErrNoResponders, so
the daemon's taskrun retry no longer imports the NATS SDK to name a
transient condition. The SDK is now confined to the nats package, the *rpc
packages (themselves NATS infrastructure), and cmd/*.

The agentexec test fake previously hand-rolled a JetStream consumer; it now
drains the client's own consumer, which is both closer to production and
avoids conflicting consumers on a work-queue stream.

Verified: go build, go vet, gofmt clean; full test suite passes.
2026-07-29 11:40:24 +10:00

130 lines
4.2 KiB
Go

// Package workintake owns the promotion of a discovered external issue into
// durable, workflow-backed work.
//
// It owns the vocabulary of that promotion -- the task envelope, its routing
// kind, and the subjects it is addressed to -- because the domain that
// defines a message's meaning owns its schema. These previously lived in the
// NATS package, which made the transport responsible for knowing what a unit
// of work was; see docs/architecture/dependencies-and-contracts.md.
//
// This package names no broker. It produces and consumes bytes; carrying
// them is internal/eventbus's job.
package workintake
import (
"encoding/json"
"fmt"
"strconv"
"strings"
)
// dedupKeyPrefix namespaces idempotency keys so they cannot collide with
// another producer's on a shared broker.
const dedupKeyPrefix = "archie:"
// TaskEnvelope is the wire payload announcing a discovered issue.
//
// Publishing once took seven positional parameters, six of them strings,
// which made a transposed argument a silent bug. Callers build this struct.
type TaskEnvelope struct {
Owner string `json:"owner"`
Repo string `json:"repo"`
Number int `json:"number"`
Title string `json:"title"`
Body string `json:"body"`
// Labels are the issue's labels. On the wire this stays a
// comma-separated string for compatibility with already-queued messages,
// but in Go it is a slice.
Labels []string `json:"-"`
// LabelsRaw is the comma-separated wire form, kept in sync by the JSON
// methods. Callers should use Labels.
LabelsRaw string `json:"labels"`
// Identity is the archie identity whose forge poll discovered the issue,
// empty for single-identity deployments. Carried so the consuming daemon
// enqueues the task under the right owner.
Identity string `json:"identity,omitempty"`
// Kind is the routing category, chosen by the publisher. Empty means
// KindDefault, which is also what messages queued before this field
// existed decode to.
Kind Kind `json:"kind,omitempty"`
}
// envelopeWire avoids infinite recursion in the JSON methods below.
type envelopeWire TaskEnvelope
// MarshalJSON flattens Labels into the comma-separated wire field.
func (t TaskEnvelope) MarshalJSON() ([]byte, error) {
t.LabelsRaw = strings.Join(t.Labels, ",")
data, err := json.Marshal(envelopeWire(t))
if err != nil {
return nil, fmt.Errorf("marshal task envelope: %w", err)
}
return data, nil
}
// UnmarshalJSON expands the comma-separated wire field into Labels.
func (t *TaskEnvelope) UnmarshalJSON(data []byte) error {
var wire envelopeWire
if err := json.Unmarshal(data, &wire); err != nil {
return fmt.Errorf("unmarshal task envelope: %w", err)
}
*t = TaskEnvelope(wire)
t.Labels = SplitLabels(t.LabelsRaw)
return nil
}
// Encode renders the envelope for transport.
func (t TaskEnvelope) Encode() ([]byte, error) {
data, err := json.Marshal(t)
if err != nil {
return nil, fmt.Errorf("encode task %s: %w", t.Ref(), err)
}
return data, nil
}
// DecodeTask parses a transported envelope.
func DecodeTask(data []byte) (TaskEnvelope, error) {
var envelope TaskEnvelope
if err := json.Unmarshal(data, &envelope); err != nil {
return TaskEnvelope{}, fmt.Errorf("decode task envelope: %w", err)
}
return envelope, nil
}
// Ref identifies the issue for logs and error messages.
func (t TaskEnvelope) Ref() string {
return t.Owner + "/" + t.Repo + "#" + strconv.Itoa(t.Number)
}
// IdempotencyKey identifies this issue for delivery deduplication, so
// rediscovering it on a later poll does not enqueue the same work twice.
func (t TaskEnvelope) IdempotencyKey() string {
return dedupKeyPrefix + t.Owner + "/" + t.Repo + "/" + strconv.Itoa(t.Number)
}
// Subject returns the address this envelope routes to.
func (t TaskEnvelope) Subject() string { return SubjectForKind(t.Kind) }
// SplitLabels parses the comma-separated wire form, dropping empties so
// "bug,,feature" and a trailing comma do not produce blank labels.
func SplitLabels(raw string) []string {
if raw == "" {
return nil
}
parts := strings.Split(raw, ",")
labels := make([]string, 0, len(parts))
for _, part := range parts {
if trimmed := strings.TrimSpace(part); trimmed != "" {
labels = append(labels, trimmed)
}
}
if len(labels) == 0 {
return nil
}
return labels
}