archie-core-7d5u.5 (idempotency and poll/webhook parity): the dedup mechanism (TaskEnvelope.IdempotencyKey + PublishUnique + JetStream Nats-Msg-Id dedup) and the shared dispatch predicate were already fully wired by 7d5u.4. What was missing: proof the dedup actually holds, and observability for a wedged receiver. - internal/infrastructure/eventbus/nats/dedup_test.go: regression test proving PublishUnique suppresses a duplicate publish on the same WorkQueuePolicy stream ARCHIE_TASKS uses in production. - internal/forge/webhook/receiver.go: Receiver.Status() tracks authenticated deliveries separately from successful publishes; a GET to the receiver's listen address (GitHub only ever POSTs) now returns it as JSON, so a wedged/non-delivering receiver is observable instead of indistinguishable from an idle repo. Poll/webhook parity (disabling webhook still polls) needed no code change: Cycle()/Run() never reference cfg.Forge.Intake anywhere in internal/daemon, only setupForgeWebhook gates the webhook HTTP server. archie-core-h019.1 (design: adversarial self-review stage): one-page decision at docs/prds/adversarial-self-review.md. Reviewer runs in a second workspace pointed at a .git-stripped snapshot of the reviewed commit, never the implementer's worktree, so isolation is a property of what's mounted rather than a prompt instruction. Findings contract is workflow.ReviewFinding, owned by internal/domain/workflow. A surviving error-level finding sets StatusParked, not WaitingHuman -- the epic's informal wording named two different states in the actual machine; this resolves which. Both changes reviewed by a fresh subagent with no memory of the implementation, per CLAUDE.md's adversarial-verification requirement; zero blocking findings, two minor coverage gaps closed.
279 lines
9.1 KiB
Go
279 lines
9.1 KiB
Go
// Package webhook implements the GitHub forge webhook receiver: an HTTP
|
|
// endpoint that verifies a GitHub webhook's HMAC signature, decodes the
|
|
// "issues" event, and publishes a matched issue as a workintake.TaskEnvelope.
|
|
//
|
|
// It is forge intake, distinct from internal/channels/webhook (the chat
|
|
// channel): that package routes inbound text through the gateway for LLM
|
|
// processing; this one decodes a GitHub payload into the same TaskEnvelope
|
|
// the poller produces and hands it to the same publish path, so a labelled or
|
|
// assigned issue becomes work the moment it happens rather than up to
|
|
// poll_interval later (see docs/prds/event-sources-and-reactions.md).
|
|
//
|
|
// GitHub's webhook must be configured with "Content type: application/json"
|
|
// (the UI default). The alternate application/x-www-form-urlencoded delivery
|
|
// is not decoded here and is rejected as a bad payload.
|
|
//
|
|
// Idempotency is not this package's job: it decodes into the same
|
|
// TaskEnvelope and calls the same publish path the poller uses, so
|
|
// PublishUnique's dedup (keyed on TaskEnvelope.IdempotencyKey) covers both
|
|
// sources for free -- see archie-core-7d5u.5. What this package does own is
|
|
// making a wedged or non-delivering receiver observable: a GET to the
|
|
// listen address (GitHub only ever POSTs) returns Status, tracking
|
|
// authenticated deliveries and successful publishes separately so an
|
|
// operator can tell "receiver is up but nothing is arriving" apart from
|
|
// "repo has no issue activity."
|
|
//
|
|
// The GET/Status route is deliberately unauthenticated, on the same
|
|
// internet-facing listener GitHub POSTs signed payloads to: it reveals
|
|
// counters and timestamps only, never repo data, issue content, or the
|
|
// webhook secret, so treating it as a public liveness probe (the same
|
|
// tradeoff an unauthenticated /healthz makes) is an acceptable exchange for
|
|
// not requiring a second credential just to check if the receiver is alive.
|
|
package webhook
|
|
|
|
import (
|
|
"context"
|
|
"encoding/json"
|
|
"io"
|
|
"log/slog"
|
|
"net/http"
|
|
"sync"
|
|
"time"
|
|
|
|
"github.com/google/go-github/v78/github"
|
|
|
|
"github.com/samcharles93/archie-core/internal/domain/workintake"
|
|
"github.com/samcharles93/archie-core/internal/webhookguard"
|
|
)
|
|
|
|
// maxBodyBytes bounds a webhook payload before it is read. GitHub webhook
|
|
// bodies are small; the cap exists so a hostile sender cannot exhaust memory.
|
|
const maxBodyBytes = 1 << 20 // 1 MiB
|
|
|
|
// PublishFunc delivers a decoded, dispatch-matched task envelope to the
|
|
// daemon's publish path. The composition root wires it to
|
|
// (*daemon.Daemon).PublishTask, the same enqueue path the poller uses.
|
|
type PublishFunc func(ctx context.Context, task workintake.TaskEnvelope) error
|
|
|
|
// Receiver is the HTTP handler for forge webhooks. It verifies the signature,
|
|
// decodes the event, applies the shared dispatch predicate, and publishes
|
|
// matched issues.
|
|
type Receiver struct {
|
|
secret string
|
|
trigger string
|
|
label string
|
|
botUser string
|
|
publish PublishFunc
|
|
log *slog.Logger
|
|
|
|
mu sync.Mutex
|
|
startedAt time.Time
|
|
lastReceivedAt time.Time
|
|
deliveries uint64
|
|
publishes uint64
|
|
}
|
|
|
|
// New returns an unstarted Receiver.
|
|
func New(secret, trigger, label, botUser string, publish PublishFunc, log *slog.Logger) *Receiver {
|
|
if log == nil {
|
|
log = slog.New(slog.DiscardHandler)
|
|
}
|
|
return &Receiver{
|
|
secret: secret,
|
|
trigger: trigger,
|
|
label: label,
|
|
botUser: botUser,
|
|
publish: publish,
|
|
log: log.With("component", "forge-webhook"),
|
|
startedAt: time.Now(),
|
|
}
|
|
}
|
|
|
|
// Status reports the receiver's delivery activity so an operator can tell a
|
|
// wedged or non-delivering receiver apart from a repo with no issue
|
|
// activity (archie-core-7d5u.5): Deliveries counts every authenticated,
|
|
// parseable webhook -- proof GitHub reached this process at all -- while
|
|
// Publishes counts only what the dispatch predicate turned into work.
|
|
// LastReceivedAt is nil until the first authenticated delivery arrives.
|
|
type Status struct {
|
|
StartedAt time.Time `json:"started_at"`
|
|
LastReceivedAt *time.Time `json:"last_received_at"`
|
|
Deliveries uint64 `json:"deliveries"`
|
|
Publishes uint64 `json:"publishes"`
|
|
}
|
|
|
|
// Status returns a snapshot of the receiver's activity counters.
|
|
func (r *Receiver) Status() Status {
|
|
r.mu.Lock()
|
|
defer r.mu.Unlock()
|
|
s := Status{
|
|
StartedAt: r.startedAt,
|
|
Deliveries: r.deliveries,
|
|
Publishes: r.publishes,
|
|
}
|
|
if !r.lastReceivedAt.IsZero() {
|
|
last := r.lastReceivedAt
|
|
s.LastReceivedAt = &last
|
|
}
|
|
return s
|
|
}
|
|
|
|
// recordDelivery marks one authenticated, parseable webhook as received.
|
|
// Called only after HMAC verification and payload parsing succeed, so an
|
|
// unauthenticated request (anyone spamming the endpoint with a bad
|
|
// signature) can never inflate the "receiver is alive" signal.
|
|
func (r *Receiver) recordDelivery() {
|
|
r.mu.Lock()
|
|
defer r.mu.Unlock()
|
|
r.deliveries++
|
|
r.lastReceivedAt = time.Now()
|
|
}
|
|
|
|
// recordPublish marks one delivery as having produced a task.
|
|
func (r *Receiver) recordPublish() {
|
|
r.mu.Lock()
|
|
defer r.mu.Unlock()
|
|
r.publishes++
|
|
}
|
|
|
|
// ServeHTTP handles one forge webhook delivery. GitHub only ever POSTs here,
|
|
// so any GET is answered with the receiver's Status instead -- an operator
|
|
// (or a monitor) can curl the same address the webhook is configured against
|
|
// to check liveness, with no separate health-check surface to wire up.
|
|
func (r *Receiver) ServeHTTP(w http.ResponseWriter, req *http.Request) {
|
|
if req.Method == http.MethodGet {
|
|
w.Header().Set("Content-Type", "application/json")
|
|
_ = json.NewEncoder(w).Encode(r.Status())
|
|
return
|
|
}
|
|
if req.Method != http.MethodPost {
|
|
http.Error(w, "method not allowed", http.StatusMethodNotAllowed)
|
|
return
|
|
}
|
|
|
|
body, err := io.ReadAll(io.LimitReader(req.Body, maxBodyBytes))
|
|
if err != nil {
|
|
r.log.Error("read body", "err", err)
|
|
http.Error(w, "read error", http.StatusBadRequest)
|
|
return
|
|
}
|
|
|
|
// HMAC verification. An invalid or missing signature is rejected and
|
|
// logged, never silently accepted.
|
|
sig := req.Header.Get("X-Hub-Signature-256")
|
|
if !webhookguard.VerifyHMAC(body, sig, r.secret) {
|
|
r.log.Warn("invalid signature", "remote", req.RemoteAddr)
|
|
http.Error(w, "invalid signature", http.StatusUnauthorized)
|
|
return
|
|
}
|
|
|
|
event, err := github.ParseWebHook(req.Header.Get("X-GitHub-Event"), body)
|
|
if err != nil {
|
|
r.log.Warn("parse webhook", "err", err)
|
|
http.Error(w, "bad payload", http.StatusBadRequest)
|
|
return
|
|
}
|
|
// Authenticated and parseable: this is a genuine GitHub delivery,
|
|
// independent of whether it turns out to be dispatch-eligible.
|
|
r.recordDelivery()
|
|
|
|
issueEvent, ok := event.(*github.IssuesEvent)
|
|
if !ok {
|
|
// Not an issue event (ping, pull_request, etc.). Acknowledge and
|
|
// ignore -- this receiver only turns issue activity into work.
|
|
w.WriteHeader(http.StatusAccepted)
|
|
return
|
|
}
|
|
|
|
task, ok := r.taskFromEvent(issueEvent)
|
|
if !ok {
|
|
// Delivered but not eligible work (PR, closed, unrelated action,
|
|
// dispatch mismatch). Acknowledge without publishing.
|
|
w.WriteHeader(http.StatusAccepted)
|
|
return
|
|
}
|
|
|
|
if err := r.publish(req.Context(), task); err != nil {
|
|
r.log.Error("publish task", "task", task.Ref(), "err", err)
|
|
http.Error(w, "publish failed", http.StatusInternalServerError)
|
|
return
|
|
}
|
|
r.recordPublish()
|
|
r.log.Info("published", "task", task.Ref())
|
|
w.WriteHeader(http.StatusAccepted)
|
|
}
|
|
|
|
// taskFromEvent decodes a GitHub issues event into a task envelope, or
|
|
// reports (zero, false) when the event is not eligible work.
|
|
func (r *Receiver) taskFromEvent(event *github.IssuesEvent) (workintake.TaskEnvelope, bool) {
|
|
issue := event.GetIssue()
|
|
if issue == nil || issue.IsPullRequest() {
|
|
return workintake.TaskEnvelope{}, false
|
|
}
|
|
// Only events that could newly make an issue eligible. unlabeled,
|
|
// unassigned, closed, and edited never queue work.
|
|
switch event.GetAction() {
|
|
case "opened", "reopened", "labeled", "assigned":
|
|
default:
|
|
return workintake.TaskEnvelope{}, false
|
|
}
|
|
if issue.GetState() != "open" {
|
|
return workintake.TaskEnvelope{}, false
|
|
}
|
|
|
|
labels := labelNames(issue.Labels)
|
|
assignees := assigneeLogins(issue.Assignees, issue.Assignee, event.GetAssignee())
|
|
if !workintake.MatchesDispatch(r.trigger, r.label, r.botUser, labels, assignees) {
|
|
return workintake.TaskEnvelope{}, false
|
|
}
|
|
|
|
repo := event.GetRepo()
|
|
if repo == nil || repo.GetOwner().GetLogin() == "" || repo.GetName() == "" {
|
|
r.log.Warn("event missing repository", "action", event.GetAction())
|
|
return workintake.TaskEnvelope{}, false
|
|
}
|
|
|
|
return workintake.TaskEnvelope{
|
|
Owner: repo.GetOwner().GetLogin(),
|
|
Repo: repo.GetName(),
|
|
Number: issue.GetNumber(),
|
|
Title: issue.GetTitle(),
|
|
Body: issue.GetBody(),
|
|
Labels: labels,
|
|
Kind: workintake.KindForLabels(labels),
|
|
}, true
|
|
}
|
|
|
|
func labelNames(labels []*github.Label) []string {
|
|
var out []string
|
|
for _, l := range labels {
|
|
if name := l.GetName(); name != "" {
|
|
out = append(out, name)
|
|
}
|
|
}
|
|
return out
|
|
}
|
|
|
|
func assigneeLogins(assignees []*github.User, extra ...*github.User) []string {
|
|
seen := map[string]bool{}
|
|
var out []string
|
|
add := func(u *github.User) {
|
|
if u == nil {
|
|
return
|
|
}
|
|
login := u.GetLogin()
|
|
if login == "" || seen[login] {
|
|
return
|
|
}
|
|
seen[login] = true
|
|
out = append(out, login)
|
|
}
|
|
for _, a := range assignees {
|
|
add(a)
|
|
}
|
|
for _, a := range extra {
|
|
add(a)
|
|
}
|
|
return out
|
|
}
|