S3 away: read a holder's answer of the kind away as a transport fault

A holder answers error-kind away, with part and words, when a part it
depends on is away; the kept call reads it from the answer and calls again
at the pace. Go: busretry.ErrorKindAway, AwayAnswer, AwayIn, Away;
TypeScript: ERROR_KIND_AWAY, awayAnswer, awayIn.

Builds: design 47 H2 §776, §775; H-A-349 DQ-15, H-A-350 DMC-2, H-A-354
This commit is contained in:
2026-11-21 23:10:27 +01:00
parent d40fa0b3a0
commit 423de0e8a2
6 changed files with 126 additions and 4 deletions
+44 -2
View File
@@ -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
+15
View File
@@ -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
+11 -1
View File
@@ -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.
+21
View File
@@ -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" {
+29
View File
@@ -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<string, unknown>;
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) };
}
+6 -1
View File
@@ -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<void> {
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);