@sjawhar/pi-envoy 14.0.1 → 14.1.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/README.md CHANGED
@@ -20,8 +20,10 @@ without one, and answers the sender with an error once four seconds pass without
20
20
  topic published straight onto NATS is forwarded once, and a miss is a `receipt_timeout` exception.
21
21
  The same route forwards a team or other ad-hoc topic's message to each session registered on the
22
22
  topic that holds its own NATS connection, as this one does, other than its sender, and the sender's
23
- error names each session that did not reply. Role messages are live only; they are not retained
24
- for a later claimant, and a session does not recover one it missed.
23
+ error names each session that did not reply. The stream stores each forward on the recipient's
24
+ agent subject, and when the listener supports consumer delivery that session takes the stored copy
25
+ once, also after a restart or a dropped connection (below). A role message is not kept for a later
26
+ claimant, and on the core path a session does not recover one it missed.
25
27
 
26
28
  This extension claims the role for the session the host has open, and every automatic claim is
27
29
  soft: it names the session it continues, which is a fork's or branch's parent, or the session
@@ -54,7 +56,20 @@ and `summary`) for recovery after an interrupt. `envoy_role_get` returns the cur
54
56
  last-seen timestamp for a role. `envoy_subscribe` reports listener warnings in both its text and
55
57
  details result, including subscriptions whose stream currently has no matching event.
56
58
 
57
- A message published while the session's NATS connection or one of its subscriptions was down is
59
+ The session's messages come from a durable consumer the listener keeps for it on Envoy's
60
+ notification stream and relays on `notifications.envoy.deliver.<session id>`, which
61
+ the session subscribes before it registers: its own agent subject, the stored copies of role
62
+ messages to a role it holds, and every followed topic the stream stores, in stream order. The
63
+ session answers each frame `received` as it decodes and `done` once Oh My Pi wrote the card or
64
+ turn to the session file, so a frame not written when the session stops, or published while it
65
+ was down or disconnected, comes again and is shown once, for up to 72 hours. Team and other
66
+ ad-hoc topics, which the stream does not store, stay live only on the session's own
67
+ subscription. "Consumer delivery" in `AGENTS.md` has the rules, and
68
+ `packages/envoy/AGENTS.md`, "Session consumers", states them once for every host.
69
+
70
+ The core path is the rollout fallback dispatch://INFRA-771 removes, for a listener that answers
71
+ `core` and for a plugin of an earlier release. There a message
72
+ published while the session's NATS connection or one of its subscriptions was down is
58
73
  recovered from Envoy's notification stream, which keeps messages for 72 hours: the session asks
59
74
  its listener (`POST /v1/replay`) for what the stream stored on its own agent subject and on each
60
75
  topic it follows, after the place it last read to, and shows each missed message once, as a card
package/dist/dispatch.js CHANGED
@@ -21615,6 +21615,15 @@ var InterestWireSchema = object({
21615
21615
  updated_at: number2().int().optional(),
21616
21616
  warnings: array(string2()).optional()
21617
21617
  });
21618
+ var DeliveryAnswerWireSchema = discriminatedUnion("mode", [
21619
+ object({
21620
+ mode: literal("consumer"),
21621
+ subject: string2().min(1),
21622
+ stream_id: string2(),
21623
+ gap: boolean2()
21624
+ }),
21625
+ object({ mode: literal("core"), reason: string2() })
21626
+ ]);
21618
21627
  var SessionWireSchema = object({
21619
21628
  session_id: string2(),
21620
21629
  machine_id: string2(),
@@ -21670,6 +21679,20 @@ var ReplayWireSchema = object({
21670
21679
  refused: string2().optional()
21671
21680
  }))
21672
21681
  });
21682
+ var DELIVERY_NOT_ANSWERED = "not_answered";
21683
+ var DELIVERY_UNREADABLE = "unreadable_answer";
21684
+ function parseSubscribeAnswer(body) {
21685
+ const interest = InterestWireSchema.parse(body);
21686
+ const raw = typeof body === "object" && body !== null && "delivery" in body ? body.delivery : undefined;
21687
+ if (raw === undefined || raw === null) {
21688
+ return { ...interest, delivery: { mode: "core", reason: DELIVERY_NOT_ANSWERED } };
21689
+ }
21690
+ const delivery = DeliveryAnswerWireSchema.safeParse(raw);
21691
+ return {
21692
+ ...interest,
21693
+ delivery: delivery.success ? delivery.data : { mode: "core", reason: DELIVERY_UNREADABLE }
21694
+ };
21695
+ }
21673
21696
  function expandSubscriptionTopics(topics) {
21674
21697
  const expanded = new Set;
21675
21698
  for (const topic of topics) {
@@ -21755,7 +21778,7 @@ function createEnvoyClient(config) {
21755
21778
  body: JSON.stringify(body)
21756
21779
  }, options);
21757
21780
  return {
21758
- subscribe: async (input) => InterestWireSchema.parse(JSON.parse(await post("/v1/interests/subscribe", {
21781
+ subscribe: async (input) => parseSubscribeAnswer(JSON.parse(await post("/v1/interests/subscribe", {
21759
21782
  session_id: input.sessionID,
21760
21783
  dir: input.directory,
21761
21784
  topics: expandSubscriptionTopics(input.topics),
@@ -21764,6 +21787,7 @@ function createEnvoyClient(config) {
21764
21787
  ...input.capabilities === undefined ? {} : { capabilities: input.capabilities },
21765
21788
  driving: input.driving,
21766
21789
  ...input.selfSubscribed === undefined ? {} : { self_subscribed: input.selfSubscribed },
21790
+ ...input.delivery === undefined ? {} : { delivery: input.delivery },
21767
21791
  ...input.clientInstanceID === undefined ? {} : { client_instance_id: input.clientInstanceID },
21768
21792
  host: machineID(),
21769
21793
  plugin: input.plugin.name,