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.
130 lines
4.2 KiB
Go
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
|
|
}
|