diff --git a/go/busretry/busretry.go b/go/busretry/busretry.go index dd39dd4c..5a053704 100644 --- a/go/busretry/busretry.go +++ b/go/busretry/busretry.go @@ -15,6 +15,7 @@ package busretry import ( "context" + "encoding/json" "errors" "fmt" "math/rand/v2" @@ -122,8 +123,49 @@ func (u *Unanswered) Error() string { func (u *Unanswered) Unwrap() error { return u.Last } // Fault says err is a transport fault of a kept call (§775): a request that reached no one, a call's own deadline -// passing; a callee's refusal never is. -func Fault(err error) bool { return TimedOut(err) || Undelivered(err) } +// passing, or a holder's answer of the kind away (§776); a callee's refusal never is. +func Fault(err error) bool { + var away *Away + return TimedOut(err) || Undelivered(err) || errors.As(err, &away) +} + +// ErrorKindAway is the seat error kind a holder answers when a part it depends on is away (design 47 H2 §776): its +// answer's `error-kind`, beside `part` (what did not answer) and `words`. A caller reads it as a transport fault. +const ErrorKindAway = "away" + +// Away is a holder's answer of the kind away, read as an error: the part that did not answer and the holder's words. +type Away struct { + Part, Words string +} + +func (a *Away) Error() string { + return fmt.Sprintf("away: %s does not answer: %s", a.Part, a.Words) +} + +// AwayAnswer is the seat error answer of the kind away a holder gives (§776): `error` and `error-kind` as each seat's +// error answer has them, with `part` and `words`. +func AwayAnswer(part, words string) map[string]string { + return map[string]string{"error": (&Away{Part: part, Words: words}).Error(), "error-kind": ErrorKindAway, + "part": part, "words": words} +} + +// AwayIn is the *Away a verb's answer says when its `error-kind` is away, else nil: an answer that is no object, or +// of another kind, is the caller's to read. +func AwayIn(answer json.RawMessage) *Away { + var a struct { + Error string `json:"error"` + Kind string `json:"error-kind"` + Part string `json:"part"` + Words string `json:"words"` + } + if json.Unmarshal(answer, &a) != nil || a.Kind != ErrorKindAway { + return nil + } + if a.Words == "" { + a.Words = a.Error + } + return &Away{Part: a.Part, Words: a.Words} +} // DoPaced makes a kept call through try (design 47 H2 §775): on a transport fault (Fault) it calls again at k's pace, // each wait jittered, until the caller's bound, writing one journal line per seat at the first fault and then at most diff --git a/go/busretry/busretry_test.go b/go/busretry/busretry_test.go index dd598c2e..215b5848 100644 --- a/go/busretry/busretry_test.go +++ b/go/busretry/busretry_test.go @@ -2,6 +2,7 @@ package busretry import ( "context" + "encoding/json" "errors" "fmt" "strings" @@ -170,6 +171,20 @@ func subAKeptCallIsPaced(t *testing.T) { t.Fatalf("%d tries, %v", tries, err) } }) + t.Run("away is a transport fault; its answer reads back", func(t *testing.T) { + raw, _ := json.Marshal(AwayAnswer("the forge's store", "401 and the version read failed")) + a := AwayIn(raw) + if a == nil || a.Part != "the forge's store" || a.Words != "401 and the version read failed" || !Fault(a) || + !strings.Contains(string(raw), `"error-kind":"away"`) { + t.Fatalf("%s read as %+v", raw, a) + } + if AwayIn([]byte(`{"error":"no","error-kind":"refused"}`)) != nil || AwayIn([]byte(`[1]`)) != nil || Fault(&Answered{Words: "away"}) { + t.Fatal("a refusal reads as away") + } + if a := AwayIn([]byte(`{"error":"the store is down","error-kind":"away"}`)); a == nil || a.Words != "the store is down" { + t.Fatalf("an away answer with no words reads %+v", a) + } + }) t.Run("one line per seat a minute", func(t *testing.T) { fakeClock(t) logs := 0 diff --git a/go/process/call.go b/go/process/call.go index 26a00866..5d48c856 100644 --- a/go/process/call.go +++ b/go/process/call.go @@ -123,7 +123,17 @@ func keptOf(key string, ask KeptAsk, open *busretry.Open) busretry.Kept { // callKeptWith is callWith for a kept call: busretry.DoPaced with no blackout probe. func callKeptWith(k busretry.Kept, request func(string, []byte) (json.RawMessage, error), called, fallback string, data []byte) (json.RawMessage, error) { - return busretry.DoPaced(k, askBoth(request, called, fallback, data)) + ask := askBoth(request, called, fallback, data) + return busretry.DoPaced(k, func() (json.RawMessage, error) { + result, err := ask() + if err == nil { + // A holder's answer of the kind away is a transport fault (§776): called again at the pace. + if away := busretry.AwayIn(result); away != nil { + return result, away + } + } + return result, err + }) } // askBoth asks called, then fallback when nothing answers it. diff --git a/go/process/call_test.go b/go/process/call_test.go index 7d138e21..a925187f 100644 --- a/go/process/call_test.go +++ b/go/process/call_test.go @@ -138,6 +138,27 @@ func TestACallIsAskedAgainOnlyWhenItReachedNoOne(t *testing.T) { t.Errorf("%s: asked %d times (%v), want %d", row.name, asks, err, row.asks) } } + // Design 47 H2 §776: a holder's answer of the kind away is a transport fault, called again at the pace; a refusal + // of another kind is the caller's answer at once. + for _, row := range []struct { + name string + answers []string + asks int + }{ + {"away, then answered", []string{`{"error":"x","error-kind":"away","part":"the forge's store","words":"401"}`, `{"merged":true}`}, 2}, + {"refused: answered at once", []string{`{"error":"no","error-kind":"refused"}`}, 1}, + } { + asks := 0 + request := func(string, []byte) (json.RawMessage, error) { + a := row.answers[min(asks, len(row.answers)-1)] + asks++ + return json.RawMessage(a), nil + } + got, err := callKeptWith(busretry.Kept{Seat: "git", Verb: "merge-pull"}, request, "called", "fallback", nil) + if asks != row.asks || err != nil || string(got) != row.answers[len(row.answers)-1] { + t.Errorf("%s: asked %d times, %s, %v", row.name, asks, got, err) + } + } // Design 47 H2 §775, H-A-351: a kept call carries its ask's id in the header, and a holder in a process reads it with // AskOf while its handler runs; a call carrying none reads empty. if m := askMsg("mesh.seat.mesh-builds.call.build", []byte(`{}`), "ask-9"); m.Header.Get(stdio.AskHeader) != "ask-9" { diff --git a/src/callers/index.ts b/src/callers/index.ts index 8207f8c9..b6e3e34b 100644 --- a/src/callers/index.ts +++ b/src/callers/index.ts @@ -230,3 +230,32 @@ export function readDefinitionCallers(verb: string, value: unknown, cls?: string } return value as string[]; } + +/** + * The seat error kind a holder answers when a part it depends on is away (design 47 H2 §776; H-A-349 DQ-15): its + * answer's `error-kind`, beside `part` (what did not answer) and `words`; a caller reads it as a transport fault and + * calls again at the kept-call pace. The Go side's `busretry.ErrorKindAway`. + */ +export const ERROR_KIND_AWAY = "away"; + +/** A holder's answer of the kind away: `error` and `error-kind` as each seat's error answer has them, with `part` and `words`. */ +export interface AwayAnswer { + readonly error: string; + readonly "error-kind": typeof ERROR_KIND_AWAY; + readonly part: string; + readonly words: string; +} + +/** The answer of the kind away a holder gives when `part` does not answer (the Go side's `busretry.AwayAnswer`). */ +export function awayAnswer(part: string, words: string): AwayAnswer { + return { error: `away: ${part} does not answer: ${words}`, "error-kind": ERROR_KIND_AWAY, part, words }; +} + +/** The part and words a verb's answer says when its `error-kind` is away, else undefined (the Go side's `busretry.AwayIn`). */ +export function awayIn(answer: unknown): { part: string; words: string } | undefined { + if (!answer || typeof answer !== "object" || Array.isArray(answer)) return undefined; + const a = answer as Record; + if (a["error-kind"] !== ERROR_KIND_AWAY) return undefined; + const str = (v: unknown) => (typeof v === "string" ? v : ""); + return { part: str(a.part), words: str(a.words) || str(a.error) }; +} diff --git a/test/sdk.test.ts b/test/sdk.test.ts index 0fb1f2f8..88e6f642 100644 --- a/test/sdk.test.ts +++ b/test/sdk.test.ts @@ -670,7 +670,7 @@ test("the provider loop is named for what it is, and its old name stays an alias await newTest6(); // a TypeScript bundle's value over one call's limit fails at once, namin }); -import { allows, refusal, parseCallers, parseVerbCallers, parseConfiguredVerbCallers, readDefinitionCallers, moduleOf, UNPROVEN, runAs, askIdOf, META_ASK } from "../dist/callers/index.js"; +import { allows, refusal, parseCallers, parseVerbCallers, parseConfiguredVerbCallers, readDefinitionCallers, moduleOf, UNPROVEN, runAs, askIdOf, META_ASK, awayAnswer, awayIn } from "../dist/callers/index.js"; import { Follower, statusTools, keepStatus, statusKey, viewWaitsFinding, type Answer, type Status } from "../dist/views/index.js"; // callers and verb callers judge a proved caller by the Go side's rules (ADR 0459 §2, ADR 0627 §2) @@ -704,6 +704,11 @@ async function newTest1(): Promise { assert.equal(await runAs(meta, a, async () => askIdOf(a)), want, JSON.stringify(meta)); assert.equal(askIdOf(a), "", "no ask once the call ended"); } + // design 47 H2 §776, DQ-15: the kind away is answered and read as the Go side does + assert.deepEqual(awayIn(JSON.parse(JSON.stringify(awayAnswer("the forge's store", "401")))), { part: "the forge's store", words: "401" }); + assert.equal(awayAnswer("p", "w")["error-kind"], "away"); + assert.equal(awayIn({ error: "no", "error-kind": "refused" }), undefined); + assert.deepEqual(awayIn({ error: "the store is down", "error-kind": "away" }), { part: "", words: "the store is down" }); const verbs = parseVerbCallers('{"pull":["*"],"merge-pull":["mesh-delivery-forge-bridge"],"comment":["operator"]}', ["pull", "merge-pull", "comment"], {}); assert.equal(refusal(verbs, "pull", "ace.anyone"), undefined);