Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
167 changes: 167 additions & 0 deletions api.go
Original file line number Diff line number Diff line change
Expand Up @@ -17,6 +17,15 @@ import (
const (
workflowMaxRuns = 50
workflowMaxNotes = 200
wakeDefaultLimit = 100
wakeMaxLimit = 500
wakeErrorScanLimit = 256
wakeErrorTimeout = "TIMEOUT"
wakeErrorRateLimited = "RATE LIMITED"
wakeErrorAuth = "AUTH"
wakeErrorNotFound = "NOT FOUND"
wakeErrorTransport = "TRANSPORT"
wakeErrorDelivery = "DELIVERY ERROR"
changePollInterval = time.Second
changeHeartbeatInterval = 15 * time.Second
changeClientCap = 32
Expand Down Expand Up @@ -245,6 +254,81 @@ func workflowLimit(raw string, cap int) int {
return n
}

func wakeLimit(raw string) int {
n, err := strconv.Atoi(raw)
if err != nil || n <= 0 {
return wakeDefaultLimit
}
if n > wakeMaxLimit {
return wakeMaxLimit
}
return n
}

func validWakeState(state string) bool {
switch state {
case "pending", "attempted", "delivered", "stalled", "failed", "delivery_unknown":
return true
default:
return false
}
}

var wakeOutstandingStates = [...]string{
"pending",
"attempted",
"stalled",
"delivery_unknown",
"failed",
}

func wakeStateOutstanding(state string) bool {
for _, outstanding := range wakeOutstandingStates {
if state == outstanding {
return true
}
}
return false
}

// wakeErrorClass reduces untrusted transport text to a fixed public enum.
// Bound before case folding so classification work cannot scale with an
// arbitrarily large error string supplied by a data source.
func wakeErrorClass(value string) string {
if len(value) > wakeErrorScanLimit {
value = value[:wakeErrorScanLimit]
}
value = strings.ToLower(value)
switch {
case value == "":
return ""
case strings.Contains(value, "timeout"), strings.Contains(value, "deadline"), strings.Contains(value, "timed out"):
return wakeErrorTimeout
case strings.Contains(value, "429"), strings.Contains(value, "rate limit"), strings.Contains(value, "throttl"):
return wakeErrorRateLimited
case strings.Contains(value, "auth"), strings.Contains(value, "unauthor"), strings.Contains(value, "forbidden"), strings.Contains(value, "permission"), strings.Contains(value, "token"), strings.Contains(value, "credential"):
return wakeErrorAuth
case strings.Contains(value, "not found"), strings.Contains(value, "unknown role"), strings.Contains(value, "no such"):
return wakeErrorNotFound
case strings.Contains(value, "connect"), strings.Contains(value, "network"), strings.Contains(value, "dial"), strings.Contains(value, "reset"), strings.Contains(value, "broken pipe"), strings.Contains(value, "eof"), strings.Contains(value, "transport"), strings.Contains(value, "socket"):
return wakeErrorTransport
default:
return wakeErrorDelivery
}
}

func publicWakeRows(rows []WakeRow, outstandingOnly bool) []WakeRow {
public := make([]WakeRow, 0, len(rows))
for _, row := range rows {
if outstandingOnly && !wakeStateOutstanding(row.State) {
continue
}
row.LastError = wakeErrorClass(row.LastError)
public = append(public, row)
}
return public
}

func splitWorkflowLabel(label string) (string, string) {
namespace, campaign, ok := strings.Cut(label, "/")
if !ok {
Expand Down Expand Up @@ -376,6 +460,89 @@ func (s *server) handleOverview(w http.ResponseWriter, r *http.Request) {
writeJSON(w, http.StatusOK, o)
}

// handleWakeSummary serves the wake-outbox rollup used by the Overview badge.
func (s *server) handleWakeSummary(w http.ResponseWriter, r *http.Request) {
ds, ok := s.ds.(WakeDataSource)
if !ok {
http.Error(w, "wake ledger unsupported by data source", http.StatusNotFound)
return
}
summary, err := ds.WakeSummary(r.Context())
if err != nil {
http.Error(w, err.Error(), statusForError(err))
return
}
candidates := summary.Rows
if candidates == nil {
for _, state := range wakeOutstandingStates {
rows, rowsErr := ds.Wakes(r.Context(), WakeQuery{State: state, Limit: wakeMaxLimit})
if rowsErr != nil {
http.Error(w, rowsErr.Error(), statusForError(rowsErr))
return
}
candidates = append(candidates, rows.Rows...)
}
}
summary.Rows = publicWakeRows(candidates, true)
summary.Outstanding = len(summary.Rows)
writeJSON(w, http.StatusOK, summary)
}

// handleWakes serves metadata-only wake obligations. The data source controls
// filtering; the handler validates the public query and normalizes nil rows.
func (s *server) handleWakes(w http.ResponseWriter, r *http.Request) {
ds, ok := s.ds.(WakeDataSource)
if !ok {
http.Error(w, "wake ledger unsupported by data source", http.StatusNotFound)
return
}
state := r.URL.Query().Get("state")
if state != "" && !validWakeState(state) {
http.Error(w, "invalid wake state", http.StatusBadRequest)
return
}
rows, err := ds.Wakes(r.Context(), WakeQuery{
State: state,
Role: r.URL.Query().Get("role"),
Limit: wakeLimit(r.URL.Query().Get("limit")),
})
if err != nil {
http.Error(w, err.Error(), statusForError(err))
return
}
rows.Rows = publicWakeRows(rows.Rows, false)
writeJSON(w, http.StatusOK, rows)
}

// handleWakeReceipts serves delivered wake metadata filtered by role and time.
func (s *server) handleWakeReceipts(w http.ResponseWriter, r *http.Request) {
ds, ok := s.ds.(WakeDataSource)
if !ok {
http.Error(w, "wake ledger unsupported by data source", http.StatusNotFound)
return
}
since := r.URL.Query().Get("since")
if since != "" {
if _, err := time.Parse(time.RFC3339, since); err != nil {
http.Error(w, "invalid wake receipt since", http.StatusBadRequest)
return
}
}
rows, err := ds.WakeReceipts(r.Context(), WakeReceiptQuery{
Role: r.URL.Query().Get("role"),
Since: since,
Limit: wakeLimit(r.URL.Query().Get("limit")),
})
if err != nil {
http.Error(w, err.Error(), statusForError(err))
return
}
if rows.Rows == nil {
rows.Rows = []WakeReceipt{}
}
writeJSON(w, http.StatusOK, rows)
}

// handleTasks serves GET /api/tasks. Ordering is normalized for byte-stable
// polling: lifecycle columns first, then most-recently-updated within a column.
func (s *server) handleTasks(w http.ResponseWriter, r *http.Request) {
Expand Down
198 changes: 198 additions & 0 deletions api_test.go
Original file line number Diff line number Diff line change
Expand Up @@ -18,6 +18,21 @@ import (
type noWorkflowDataSource struct{ DataSource }
type noChangeCursorDataSource struct{ DataSource }
type noOrgDataSource struct{ DataSource }
type noWakeDataSource struct{ DataSource }

type sparseWakeDataSource struct{ DataSource }

func (d sparseWakeDataSource) WakeSummary(context.Context) (WakeSummary, error) {
return WakeSummary{}, nil
}

func (d sparseWakeDataSource) Wakes(context.Context, WakeQuery) (WakeRows, error) {
return WakeRows{}, nil
}

func (d sparseWakeDataSource) WakeReceipts(context.Context, WakeReceiptQuery) (WakeReceipts, error) {
return WakeReceipts{}, nil
}

type sparseOrgDataSource struct{ DataSource }

Expand Down Expand Up @@ -387,6 +402,189 @@ func TestFakeOverviewContractOrderingAndDeterminism(t *testing.T) {
}
}

func TestHandleWakeLedgerUnsupportedDataSource(t *testing.T) {
ds := noWakeDataSource{DataSource: NewFakeDataSource()}
srv := httptest.NewServer(Serve(ds))
defer srv.Close()

for _, path := range []string{"/api/wakes/summary", "/api/wakes", "/api/wakes/receipts"} {
resp, err := http.Get(srv.URL + path)
if err != nil {
t.Fatalf("GET %s: %v", path, err)
}
body, _ := io.ReadAll(resp.Body)
resp.Body.Close()
if resp.StatusCode != http.StatusNotFound || !strings.Contains(string(body), "wake ledger unsupported") {
t.Fatalf("GET %s status=%d body=%q, want clear 404", path, resp.StatusCode, body)
}
}
}

func TestHandleWakeLedgerNormalizesNilRows(t *testing.T) {
srv := httptest.NewServer(Serve(sparseWakeDataSource{DataSource: NewFakeDataSource()}))
defer srv.Close()

for _, path := range []string{"/api/wakes/summary", "/api/wakes", "/api/wakes/receipts"} {
raw := getRaw(t, srv.URL+path)
if !bytes.Contains(raw, []byte(`"rows": []`)) {
t.Fatalf("GET %s did not normalize rows: %s", path, raw)
}
}
}

func TestFakeWakeSummaryOutstandingRowsCannotDrift(t *testing.T) {
srv := httptest.NewServer(Serve(NewFakeDataSource()))
defer srv.Close()

var summary WakeSummary
if err := json.Unmarshal(getRaw(t, srv.URL+"/api/wakes/summary"), &summary); err != nil {
t.Fatalf("decode wake summary: %v", err)
}
if summary.Rows == nil {
t.Fatal("wake summary rows are nil")
}
if summary.Outstanding != 6 {
t.Fatalf("outstanding=%d, want 6 including failed wake", summary.Outstanding)
}
if got := len(summary.Rows); got != summary.Outstanding {
t.Fatalf("outstanding badge=%d but ledger rows=%d", summary.Outstanding, got)
}
seen := make(map[string]bool)
for _, row := range summary.Rows {
if !wakeStateOutstanding(row.State) {
t.Fatalf("terminal state %q appeared in outstanding rows: %+v", row.State, summary.Rows)
}
seen[row.State] = true
}
for _, required := range []string{"pending", "attempted", "stalled", "delivery_unknown", "failed"} {
if !seen[required] {
t.Fatalf("outstanding rows omitted required state %q: %+v", required, summary.Rows)
}
}
}

func TestWakeErrorClass(t *testing.T) {
tests := []struct {
name string
value string
want string
}{
{name: "empty", value: "", want: ""},
{name: "timeout", value: "delivery deadline exceeded", want: wakeErrorTimeout},
{name: "rate limited", value: "remote returned HTTP 429", want: wakeErrorRateLimited},
{name: "auth before transport", value: "unauthorized transport connection", want: wakeErrorAuth},
{name: "not found", value: "unknown role g9", want: wakeErrorNotFound},
{name: "transport", value: "connection reset by peer", want: wakeErrorTransport},
{name: "generic", value: "payload included here", want: wakeErrorDelivery},
{
name: "bounded scan",
value: strings.Repeat("x", wakeErrorScanLimit) + " timeout",
want: wakeErrorDelivery,
},
}
for _, tt := range tests {
t.Run(tt.name, func(t *testing.T) {
if got := wakeErrorClass(tt.value); got != tt.want {
t.Fatalf("wakeErrorClass(%q) = %q, want %q", tt.value, got, tt.want)
}
})
}
}

func TestFakeWakeLedgerContractFiltersAndDeterminism(t *testing.T) {
srv := httptest.NewServer(Serve(NewFakeDataSource()))
defer srv.Close()

summaryRaw := getRaw(t, srv.URL+"/api/wakes/summary")
if again := getRaw(t, srv.URL+"/api/wakes/summary"); !bytes.Equal(summaryRaw, again) {
t.Fatalf("wake summary changed across identical reads\nfirst=%s\nsecond=%s", summaryRaw, again)
}
var summary WakeSummary
if err := json.Unmarshal(summaryRaw, &summary); err != nil {
t.Fatalf("decode wake summary: %v", err)
}
if summary.Outstanding != 6 || summary.Pending != 2 || summary.AgedAttempted != 1 || summary.DeliveryUnknown != 1 || summary.Stalled != 1 || summary.OldestAgeSeconds != 3100 {
t.Fatalf("wake summary = %+v", summary)
}
if summary.Rows == nil || len(summary.Rows) != summary.Outstanding {
t.Fatalf("wake summary rows=%+v outstanding=%d", summary.Rows, summary.Outstanding)
}
for _, field := range []string{"\"outstanding\"", "\"pending\"", "\"aged_attempted\"", "\"delivery_unknown\"", "\"stalled\"", "\"oldest_age_seconds\"", "\"rows\""} {
if !bytes.Contains(summaryRaw, []byte(field)) {
t.Fatalf("wake summary missing %s: %s", field, summaryRaw)
}
}
for _, secret := range []string{"rotate the private signing key", "unredacted customer fixture"} {
if bytes.Contains(summaryRaw, []byte(secret)) {
t.Fatalf("wake summary leaked raw delivery error %q: %s", secret, summaryRaw)
}
}

wakesRaw := getRaw(t, srv.URL+"/api/wakes?limit=100")
if again := getRaw(t, srv.URL+"/api/wakes?limit=100"); !bytes.Equal(wakesRaw, again) {
t.Fatalf("wake rows changed across identical reads\nfirst=%s\nsecond=%s", wakesRaw, again)
}
var wakes WakeRows
if err := json.Unmarshal(wakesRaw, &wakes); err != nil {
t.Fatalf("decode wakes: %v", err)
}
if wakes.Rows == nil || len(wakes.Rows) != 6 {
t.Fatalf("wake rows = %+v, want six non-nil rows", wakes.Rows)
}
validStates := map[string]bool{"pending": true, "attempted": true, "delivered": true, "stalled": true, "failed": true, "delivery_unknown": true}
for i, row := range wakes.Rows {
if row.ID == "" || row.TargetRole == "" || row.SourceKind == "" || row.SourceID == "" || !validStates[row.State] || row.CreatedAt == "" {
t.Fatalf("incomplete wake row[%d] = %+v", i, row)
}
}
if !bytes.Contains(wakesRaw, []byte(`"attempted_at": null`)) {
t.Fatalf("pending wake must carry attempted_at:null: %s", wakesRaw)
}
for _, secret := range []string{"rotate the private signing key", "unredacted customer fixture"} {
if bytes.Contains(wakesRaw, []byte(secret)) {
t.Fatalf("wake API leaked raw delivery error %q: %s", secret, wakesRaw)
}
}
errorClasses := map[string]string{
"wake-unknown-001": wakeErrorTransport,
"wake-stalled-001": wakeErrorTimeout,
"wake-attempted-001": wakeErrorTransport,
"wake-failed-001": wakeErrorAuth,
}
for _, row := range wakes.Rows {
if want, ok := errorClasses[row.ID]; ok && row.LastError != want {
t.Fatalf("wake %s last_error=%q, want public class %q", row.ID, row.LastError, want)
}
}

var filtered WakeRows
if err := json.Unmarshal(getRaw(t, srv.URL+"/api/wakes?state=pending&role=g2&limit=1"), &filtered); err != nil {
t.Fatalf("decode filtered wakes: %v", err)
}
if len(filtered.Rows) != 1 || filtered.Rows[0].State != "pending" || filtered.Rows[0].TargetRole != "g2" {
t.Fatalf("filtered wakes = %+v", filtered.Rows)
}

var receipts WakeReceipts
if err := json.Unmarshal(getRaw(t, srv.URL+"/api/wakes/receipts?role=lead&since=2026-07-28T22:00:00Z&limit=10"), &receipts); err != nil {
t.Fatalf("decode receipts: %v", err)
}
if receipts.Rows == nil || len(receipts.Rows) != 1 || receipts.Rows[0].TargetRole != "lead" || receipts.Rows[0].State != "delivered" {
t.Fatalf("filtered receipts = %+v", receipts.Rows)
}

for _, path := range []string{"/api/wakes?state=unknown", "/api/wakes/receipts?since=not-a-time"} {
resp, err := http.Get(srv.URL + path)
if err != nil {
t.Fatalf("GET invalid query %s: %v", path, err)
}
resp.Body.Close()
if resp.StatusCode != http.StatusBadRequest {
t.Fatalf("GET %s status=%d, want 400", path, resp.StatusCode)
}
}
}

func TestFakeTasksContractOrderingAndDeterminism(t *testing.T) {
srv := httptest.NewServer(Serve(NewFakeDataSource()))
defer srv.Close()
Expand Down
Loading
Loading