@ghostlytools/sdk 0.0.0-stage → 1.2.4
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 +13 -2
- package/dist/app.js +72 -0
- package/dist/app.js.map +1 -0
- package/dist/core.js +207 -0
- package/dist/core.js.map +1 -0
- package/dist/fakes-JOzOFxn3.js +536 -0
- package/dist/fakes-JOzOFxn3.js.map +1 -0
- package/dist/fakes.js +2 -0
- package/dist/index.js +179 -0
- package/dist/index.js.map +1 -0
- package/dist/keet-identity-key-BLli1rE4.js +76483 -0
- package/dist/keet-identity-key-BLli1rE4.js.map +1 -0
- package/dist/src-BqHTnRWH.js +31296 -0
- package/dist/src-BqHTnRWH.js.map +1 -0
- package/dist/testing.js +330 -0
- package/dist/testing.js.map +1 -0
- package/dist/types/browser/src/engine/paymentAdapters/providers/contractSuite.d.ts +41 -0
- package/dist/types/browser/src/engine/paymentAdapters/providers/lightning.d.ts +103 -0
- package/dist/types/browser/src/engine/paymentAdapters/providers/onchain.d.ts +88 -0
- package/dist/types/browser/src/engine/paymentAdapters/providers/testing.d.ts +89 -0
- package/dist/types/browser/src/engine/paymentAdapters/providers/types.d.ts +151 -0
- package/dist/types/browser/src/plugins/bundled.d.ts +8 -0
- package/dist/types/browser/src/plugins/registry.d.ts +57 -0
- package/dist/types/browser/src/proofs/contract.d.ts +262 -0
- package/dist/types/browser/src/proofs/contractSuite.d.ts +27 -0
- package/dist/types/browser/src/proofs/testing.d.ts +36 -0
- package/dist/types/browser/src/proofs/verify.d.ts +23 -0
- package/dist/types/browser/src/shared/mints.d.ts +50 -0
- package/dist/types/core/src/appBundle.d.ts +173 -0
- package/dist/types/core/src/appStatements.d.ts +142 -0
- package/dist/types/core/src/appStore.d.ts +133 -0
- package/dist/types/core/src/appUpdates.d.ts +88 -0
- package/dist/types/core/src/atprotoIdentity.d.ts +49 -0
- package/dist/types/core/src/atprotoRepo.d.ts +101 -0
- package/dist/types/core/src/avatar.d.ts +19 -0
- package/dist/types/core/src/bip322.d.ts +57 -0
- package/dist/types/core/src/bitcoinAddress.d.ts +5 -0
- package/dist/types/core/src/bitcoinMessage.d.ts +15 -0
- package/dist/types/core/src/bitcoinScript.d.ts +69 -0
- package/dist/types/core/src/bolt11.d.ts +30 -0
- package/dist/types/core/src/bytes.d.ts +11 -0
- package/dist/types/core/src/callSignal.d.ts +232 -0
- package/dist/types/core/src/canonicalJson.d.ts +22 -0
- package/dist/types/core/src/capsRecord.d.ts +234 -0
- package/dist/types/core/src/catchUp.d.ts +45 -0
- package/dist/types/core/src/chatFiles.d.ts +271 -0
- package/dist/types/core/src/clockWatch.d.ts +72 -0
- package/dist/types/core/src/communityRendezvous.d.ts +113 -0
- package/dist/types/core/src/crypto.d.ts +10 -0
- package/dist/types/core/src/datalink.d.ts +187 -0
- package/dist/types/core/src/deviceInvite.d.ts +51 -0
- package/dist/types/core/src/deviceLink.d.ts +70 -0
- package/dist/types/core/src/dhtDelivery.d.ts +407 -0
- package/dist/types/core/src/dhtFiles.d.ts +46 -0
- package/dist/types/core/src/did.d.ts +134 -0
- package/dist/types/core/src/didDht.d.ts +155 -0
- package/dist/types/core/src/directPath.d.ts +63 -0
- package/dist/types/core/src/dns.d.ts +41 -0
- package/dist/types/core/src/domainProofs.d.ts +88 -0
- package/dist/types/core/src/engineErrors.d.ts +91 -0
- package/dist/types/core/src/enroll.d.ts +98 -0
- package/dist/types/core/src/files.d.ts +73 -0
- package/dist/types/core/src/forwards.d.ts +12 -0
- package/dist/types/core/src/frames.d.ts +211 -0
- package/dist/types/core/src/ghostlink.d.ts +1532 -0
- package/dist/types/core/src/groupCommits.d.ts +103 -0
- package/dist/types/core/src/groupCommunity.d.ts +720 -0
- package/dist/types/core/src/groupCrypto.d.ts +60 -0
- package/dist/types/core/src/groupEdits.d.ts +67 -0
- package/dist/types/core/src/groupEntry.d.ts +61 -0
- package/dist/types/core/src/groupFiles.d.ts +106 -0
- package/dist/types/core/src/groupHubs.d.ts +61 -0
- package/dist/types/core/src/groupMentions.d.ts +27 -0
- package/dist/types/core/src/groupMeta.d.ts +162 -0
- package/dist/types/core/src/groupSession.d.ts +728 -0
- package/dist/types/core/src/groupSignals.d.ts +167 -0
- package/dist/types/core/src/groupTyping.d.ts +56 -0
- package/dist/types/core/src/groupWake.d.ts +68 -0
- package/dist/types/core/src/handoff.d.ts +255 -0
- package/dist/types/core/src/http.d.ts +125 -0
- package/dist/types/core/src/identity.d.ts +17 -0
- package/dist/types/core/src/identityProofs.d.ts +243 -0
- package/dist/types/core/src/identityTimeline.d.ts +72 -0
- package/dist/types/core/src/image.d.ts +33 -0
- package/dist/types/core/src/index.d.ts +100 -0
- package/dist/types/core/src/invite.d.ts +128 -0
- package/dist/types/core/src/link.d.ts +353 -0
- package/dist/types/core/src/linkPreview.d.ts +60 -0
- package/dist/types/core/src/linkTrace.d.ts +12 -0
- package/dist/types/core/src/lnurl.d.ts +99 -0
- package/dist/types/core/src/messageTime.d.ts +28 -0
- package/dist/types/core/src/miniApp.d.ts +146 -0
- package/dist/types/core/src/pairedApps.d.ts +151 -0
- package/dist/types/core/src/pairedCalls.d.ts +59 -0
- package/dist/types/core/src/pairedCapabilities.d.ts +101 -0
- package/dist/types/core/src/pairedEdits.d.ts +83 -0
- package/dist/types/core/src/pairedFiles.d.ts +30 -0
- package/dist/types/core/src/pairedHttp.d.ts +15 -0
- package/dist/types/core/src/pairedSession.d.ts +163 -0
- package/dist/types/core/src/pairedSignal.d.ts +17 -0
- package/dist/types/core/src/pairedTransports.d.ts +76 -0
- package/dist/types/core/src/pairedTyping.d.ts +130 -0
- package/dist/types/core/src/pairedWake.d.ts +109 -0
- package/dist/types/core/src/pairingProgress.d.ts +107 -0
- package/dist/types/core/src/paymentIntent.d.ts +111 -0
- package/dist/types/core/src/paymentUri.d.ts +34 -0
- package/dist/types/core/src/payments.d.ts +97 -0
- package/dist/types/core/src/peerProofs.d.ts +98 -0
- package/dist/types/core/src/pins.d.ts +73 -0
- package/dist/types/core/src/pkarr.d.ts +48 -0
- package/dist/types/core/src/pkdns.d.ts +35 -0
- package/dist/types/core/src/pubkyProofs.d.ts +25 -0
- package/dist/types/core/src/pubkyRing.d.ts +21 -0
- package/dist/types/core/src/reactions.d.ts +108 -0
- package/dist/types/core/src/records.d.ts +89 -0
- package/dist/types/core/src/relay.d.ts +459 -0
- package/dist/types/core/src/relayBreaker.d.ts +99 -0
- package/dist/types/core/src/replies.d.ts +41 -0
- package/dist/types/core/src/services.d.ts +35 -0
- package/dist/types/core/src/setUpdate.d.ts +53 -0
- package/dist/types/core/src/signal.d.ts +53 -0
- package/dist/types/core/src/signer.d.ts +13 -0
- package/dist/types/core/src/sparkAddress.d.ts +37 -0
- package/dist/types/core/src/sshsig.d.ts +74 -0
- package/dist/types/core/src/statusCards.d.ts +253 -0
- package/dist/types/core/src/storeForward.d.ts +144 -0
- package/dist/types/core/src/text.d.ts +20 -0
- package/dist/types/core/src/transport.d.ts +158 -0
- package/dist/types/core/src/transportSwitch.d.ts +160 -0
- package/dist/types/core/src/turnRead.d.ts +145 -0
- package/dist/types/core/src/turnRecord.d.ts +165 -0
- package/dist/types/core/src/version.d.ts +9 -0
- package/dist/types/core/src/video.d.ts +44 -0
- package/dist/types/core/src/voice.d.ts +88 -0
- package/dist/types/core/src/webPush.d.ts +58 -0
- package/dist/types/sdk/src/app.d.ts +23 -0
- package/dist/types/sdk/src/core.d.ts +7 -0
- package/dist/types/sdk/src/fakes.d.ts +6 -0
- package/dist/types/sdk/src/index.d.ts +26 -0
- package/dist/types/sdk/src/testing.d.ts +7 -0
- package/dist/types-DvtCy3WB.js +99 -0
- package/dist/types-DvtCy3WB.js.map +1 -0
- package/dist/verify-RjMx7eW6.js +106 -0
- package/dist/verify-RjMx7eW6.js.map +1 -0
- package/package.json +70 -4
|
@@ -0,0 +1,89 @@
|
|
|
1
|
+
import { type GhostRecord, type SignedPacket } from "./pkarr.js";
|
|
2
|
+
import { type ServiceAd } from "./services.js";
|
|
3
|
+
/**
|
|
4
|
+
* TXT labels a peer publishes under its own key. Every value except `_ts` and
|
|
5
|
+
* `_ack` is secretbox-encrypted with the link key.
|
|
6
|
+
*
|
|
7
|
+
* `_msgs`, `_ts`, `_ack`, `_nick` and `_call` are the original Ghost protocol.
|
|
8
|
+
* `_svc` and `_rtc` are additive: clients that predate them ignore unknown
|
|
9
|
+
* labels, so old and new peers keep chatting and calling each other.
|
|
10
|
+
*/
|
|
11
|
+
export declare const LABEL: {
|
|
12
|
+
readonly msgs: "_msgs";
|
|
13
|
+
readonly ts: "_ts";
|
|
14
|
+
readonly ack: "_ack";
|
|
15
|
+
readonly nick: "_nick";
|
|
16
|
+
readonly call: "_call";
|
|
17
|
+
/** Service advertisement, see `services.ts`. */
|
|
18
|
+
readonly svc: "_svc";
|
|
19
|
+
/** Signaling for the WebRTC data link, see `signal.ts`. */
|
|
20
|
+
readonly rtc: "_rtc";
|
|
21
|
+
/**
|
|
22
|
+
* A group link's layer-1 transports and how to dial its native ones (`encodePacketTransports` in `capsRecord.ts`):
|
|
23
|
+
* published only by an app with no WebRTC and by a member answering one, so two apps that have WebRTC never send it.
|
|
24
|
+
*/
|
|
25
|
+
readonly tr: "_tr";
|
|
26
|
+
};
|
|
27
|
+
export declare const RECORD_TTL = 300;
|
|
28
|
+
/** Same ceiling the Rust implementation applies to the encrypted message batch. */
|
|
29
|
+
export declare const MAX_MSGS_PAYLOAD_B64 = 800;
|
|
30
|
+
export interface CompactMessage {
|
|
31
|
+
t: number;
|
|
32
|
+
m: string;
|
|
33
|
+
}
|
|
34
|
+
export interface OutgoingLinkState {
|
|
35
|
+
messages: CompactMessage[];
|
|
36
|
+
ackTimestamp: number;
|
|
37
|
+
nick?: string;
|
|
38
|
+
callSignal?: string | null;
|
|
39
|
+
rtcSignal?: string | null;
|
|
40
|
+
/** `undefined` publishes no `_svc` at all, which is what a legacy peer looks like. */
|
|
41
|
+
services?: ServiceAd[];
|
|
42
|
+
/** A group link's `_tr` value, already encoded; absent publishes none. */
|
|
43
|
+
transports?: string | null;
|
|
44
|
+
}
|
|
45
|
+
export interface BuiltLinkRecords {
|
|
46
|
+
records: GhostRecord[];
|
|
47
|
+
/** How many of the newest messages made it into the packet. */
|
|
48
|
+
keptMessages: number;
|
|
49
|
+
/** False when the advertisement had to be left out to fit the packet. */
|
|
50
|
+
servicesIncluded: boolean;
|
|
51
|
+
}
|
|
52
|
+
/**
|
|
53
|
+
* The packet an inviter puts under the contact's key before they join, so that their first packet lands
|
|
54
|
+
* as a newer one under a key the network already knows (seconds faster than a first packet under a
|
|
55
|
+
* fresh key). It carries no message record, which every link session's own packet does, even empty:
|
|
56
|
+
* that is how a reader tells it from a contact who is here (or was, and left without a word).
|
|
57
|
+
*/
|
|
58
|
+
export declare function emptyLinkRecords(): GhostRecord[];
|
|
59
|
+
/** A packet nobody's link session published (see `emptyLinkRecords`): read as no packet at all. */
|
|
60
|
+
export declare function isEmptyLinkPacket(batch: ResolvedLink): boolean;
|
|
61
|
+
/**
|
|
62
|
+
* Builds the records for one publish. A Pkarr packet is at most 1000 bytes, so
|
|
63
|
+
* space is handed out by priority: signaling first (it is what gets peers onto
|
|
64
|
+
* WebRTC, where there is no such limit), then the service advertisement, then
|
|
65
|
+
* as many of the newest messages as still fit.
|
|
66
|
+
*/
|
|
67
|
+
export declare function buildLinkRecords(pubKeyZ32: string, state: OutgoingLinkState, encKey: Uint8Array): BuiltLinkRecords;
|
|
68
|
+
export interface ResolvedMessage {
|
|
69
|
+
text: string;
|
|
70
|
+
timestamp: number;
|
|
71
|
+
nick?: string;
|
|
72
|
+
}
|
|
73
|
+
export interface ResolvedLink {
|
|
74
|
+
messages: ResolvedMessage[];
|
|
75
|
+
latestTimestamp: number;
|
|
76
|
+
peerAck: number;
|
|
77
|
+
nick?: string;
|
|
78
|
+
callSignal: string | null;
|
|
79
|
+
rtcSignal: string | null;
|
|
80
|
+
/** `null` when the peer published no advertisement (legacy client or offline). */
|
|
81
|
+
services: ServiceAd[] | null;
|
|
82
|
+
/** A group link's `_tr` value as published (`parsePacketTransports`); `null` when there is none. */
|
|
83
|
+
transports: string | null;
|
|
84
|
+
rawRecordNames: string[];
|
|
85
|
+
encryptedPayloadLength: number;
|
|
86
|
+
/** Milliseconds since the UNIX epoch. */
|
|
87
|
+
packetTimestamp: number;
|
|
88
|
+
}
|
|
89
|
+
export declare function parseLinkRecords(packet: SignedPacket, encKey: Uint8Array): ResolvedLink;
|
|
@@ -0,0 +1,459 @@
|
|
|
1
|
+
import type { Identity } from "./identity.js";
|
|
2
|
+
import { type GhostRecord, type SignedPacket } from "./pkarr.js";
|
|
3
|
+
import { type DiscoveryStatus, type RelayBreakerOptions } from "./relayBreaker.js";
|
|
4
|
+
import { type DiscoveryChange, type PkarrRequestOptions, type PkarrTransport, type ServerTime } from "./transport.js";
|
|
5
|
+
import type { TurnConditions, TurnSourceAnswer, TurnSourcePut } from "./turnRead.js";
|
|
6
|
+
/**
|
|
7
|
+
* Public Pkarr relays. They are generic Pkarr infrastructure (an HTTP bridge to
|
|
8
|
+
* the Mainline DHT), not a Ghostly backend: they only ever see signed,
|
|
9
|
+
* encrypted packets. Every client uses this list: the browser clients read and
|
|
10
|
+
* write through it, Ghostly Desktop writes to it (so browser contacts see its
|
|
11
|
+
* packets) and reads from it only when "Also use Pkarr relays" is on. Adding a
|
|
12
|
+
* relay is one line here; see docs/RELAYS.md for how one is chosen.
|
|
13
|
+
*/
|
|
14
|
+
export declare const DEFAULT_RELAYS: string[];
|
|
15
|
+
/**
|
|
16
|
+
* Relay lists that were the defaults once: a profile that still has one gets today's defaults. When a relay
|
|
17
|
+
* joins `DEFAULT_RELAYS`, the list as it was goes here, so profiles on the old defaults move with it.
|
|
18
|
+
*/
|
|
19
|
+
export declare const PREVIOUS_DEFAULT_RELAYS: string[][];
|
|
20
|
+
/** The defaults for `relays` when it is one of the old default lists, `relays` itself otherwise. */
|
|
21
|
+
export declare function currentRelays(relays: string[]): string[];
|
|
22
|
+
/**
|
|
23
|
+
* Requests this client allows itself per relay and minute. Relays limit by IP
|
|
24
|
+
* (120 a minute when this was written) and one address is often shared by
|
|
25
|
+
* several peers: two browser profiles, a tab and an extension, a household.
|
|
26
|
+
*/
|
|
27
|
+
export declare const REQUESTS_PER_MINUTE = 30;
|
|
28
|
+
/**
|
|
29
|
+
* Of those, what background requests (`{ background: true }`: periodic looks at shared records, as a
|
|
30
|
+
* community group's hub makes) may spend, counted on their own: the rest is kept for links, whose
|
|
31
|
+
* signaling cannot wait, and a burst of signaling does not hold the background ones back afterwards.
|
|
32
|
+
*/
|
|
33
|
+
export declare const BACKGROUND_REQUESTS_PER_MINUTE = 20;
|
|
34
|
+
/**
|
|
35
|
+
* A link's write the budget refused (its presence, its offer, its answer) goes first when the minute
|
|
36
|
+
* frees a request: reads on that relay wait this long after the refusal. A link that polls fast for a
|
|
37
|
+
* peer while its offer waits would otherwise take every request the minute frees, and the offer (the
|
|
38
|
+
* only thing that peer is waiting for) would go out only once the polling slowed down, half a minute later.
|
|
39
|
+
*/
|
|
40
|
+
export declare const WRITE_FIRST_MS = 5000;
|
|
41
|
+
/**
|
|
42
|
+
* Once a 1:1 chat needs the relays (the budget refused one of its requests there, or it read urgently anywhere: it polls
|
|
43
|
+
* fast for a signal due any moment), group requests leave it the last this many of each minute, for a minute. Groups
|
|
44
|
+
* that spend the whole budget spend it over the minute, so the chat then takes the next request that frees, within
|
|
45
|
+
* seconds, and has room for what follows (the receipt). Waiting for a refusal was too late when a contact went away
|
|
46
|
+
* from a chat and from groups at once: the chat and the groups' edges all watched fast for it, the edges spent both
|
|
47
|
+
* relays' minute in 40 s, and the chat read the contact's offer half a minute late (2026-09-27). A chat with nothing
|
|
48
|
+
* to wait for leaves groups the whole budget: a community door alone costs about 22 requests a minute, and a reserve
|
|
49
|
+
* kept for any chat starved a new group's edges. The reserve is per chat: a chat that reads its contact at a slow pace
|
|
50
|
+
* again (it is live) gives its part back at once. Kept for the minute, a daemon back after a restart with its chats
|
|
51
|
+
* live in 18 s held a group's edge that had just missed its read for 48 s more (bug hunt r6a, 2026-09-29).
|
|
52
|
+
*/
|
|
53
|
+
export declare const CHAT_RESERVE = 10;
|
|
54
|
+
/**
|
|
55
|
+
* A 1:1 chat's signaling (a new offer or answer, and its reads for the answer to its offer, `signal`) may go over a
|
|
56
|
+
* relay's minute by this fraction of it: 6 on a relay of 30, 12 on one of 60, 1 on relay.pkarr.org's 5 (it allows 10),
|
|
57
|
+
* and never more than that in any minute; its reads leave the last of those to a write. Everything else still stops at
|
|
58
|
+
* the limit. The minute before a chat leaves DHT only can be spent by then (the pairing, the texts over the DHT), and
|
|
59
|
+
* its offer or answer, the one thing the contact waits for, then waited 40 s for requests to age out while the
|
|
60
|
+
* contact's attempt gave up: the matrix's extension chat stayed "On DHT · retrying live" 46 times in 120 (2026-09-30).
|
|
61
|
+
*/
|
|
62
|
+
export declare const SIGNALING_ALLOWANCE_SHARE: number;
|
|
63
|
+
/**
|
|
64
|
+
* A 1:1 chat's reads of a contact that went away from a live session, in their first seconds (`departed`,
|
|
65
|
+
* `DEPARTED_READ_MS` in link.ts), may go over a relay's minute within the chat's allowance (`SIGNALING_ALLOWANCE_SHARE`):
|
|
66
|
+
* at most this many of each contact's in a minute, every relay together, leaving the last of the allowance to an offer or
|
|
67
|
+
* answer. Their fast poll reads every 2 s, on the relays in turn: 6 cover 12 s from the goodbye, by when an app that
|
|
68
|
+
* restarts has its offer out (2.5 to 10 s in the lab of #1441), and add at most 3 to a relay's minute. They wait for no
|
|
69
|
+
* write the minute refused: that write cannot go before the minute frees anyway. A daemon restarted 20 s after its last
|
|
70
|
+
* restart found its contact's minute spent on both relays: every read of it was held back, the offer it published as it
|
|
71
|
+
* came up was never read, and the chat came back only through the race's DHT dial, 8 s on (2026-10-07).
|
|
72
|
+
*/
|
|
73
|
+
export declare const DEPARTED_READS = 6;
|
|
74
|
+
/**
|
|
75
|
+
* A group edge's requests for a member that may be back may go over a relay's minute by this fraction of it (4 on a
|
|
76
|
+
* relay of 30, 8 on one of 60, none on relay.pkarr.org's 5): its reads of a member that went away and its packet
|
|
77
|
+
* written meanwhile, which that member reads first when it is back (`watch`), its offer or answer, and its reads for
|
|
78
|
+
* the answer to its offer (`signal`). Its reads leave the last of those to a write and go
|
|
79
|
+
* one at a time (`GROUP_OVER_PACE_MS`), so the allowance lasts until the member is back, and the read that finds its
|
|
80
|
+
* offer still has the answer behind it. Less than a chat's (`SIGNALING_ALLOWANCE_SHARE`), which keeps room past the
|
|
81
|
+
* groups'. A private group's admin that had just let members in and seen them restart had spent its minute in 30 s;
|
|
82
|
+
* a member back then, with no other member online to carry its offer, had it read only when the minute freed: 18 to
|
|
83
|
+
* 42 s later, one round in four of the member-back runs (2026-10-03).
|
|
84
|
+
*/
|
|
85
|
+
export declare const GROUP_SIGNALING_ALLOWANCE_SHARE: number;
|
|
86
|
+
/** Past the limit, a group's reads within its allowance go no more often than this on a relay. */
|
|
87
|
+
export declare const GROUP_OVER_PACE_MS = 5000;
|
|
88
|
+
/**
|
|
89
|
+
* Groups' urgent reads (their edges looking fast for a signal) take at most a quarter of a relay's minute in any this
|
|
90
|
+
* long, so that they never spend it in a burst. An app back after a restart has every edge offering and looking fast at
|
|
91
|
+
* once; the members at the other end answer only once they notice its old sessions went (about 20 s with
|
|
92
|
+
* node-datachannel). On the default relays the edges spent the groups' share of the minute in those seconds, and read
|
|
93
|
+
* nothing for 40 s more: a private group's edges were live again 75 to 110 s after a restart (bug hunt r5a, 2026-09-29).
|
|
94
|
+
*/
|
|
95
|
+
export declare const GROUP_BURST_MS = 15000;
|
|
96
|
+
/** …and never fewer than one link polling fast (every 2 s) reads in that time: one edge alone is never held back. */
|
|
97
|
+
export declare const GROUP_BURST_ONE_LINK = 8;
|
|
98
|
+
/**
|
|
99
|
+
* A group's edges' reads of members that went away from a live session and have not shown themselves back (`watch`: a
|
|
100
|
+
* link looks for them closely for two minutes, `WATCH_PEER_MS`) take at most this share of a relay's requests, whatever
|
|
101
|
+
* their number, spread over the minute (`GROUP_RATION_WINDOW_MS`): 2 in any 10 s on a relay of 30. Under it, the key
|
|
102
|
+
* read longest ago goes first. A member alone in a private group whose three other members left at once watched each of
|
|
103
|
+
* them every 2 s: those reads and the admin's knock poll spent both relays' minute, the member back first had its offer
|
|
104
|
+
* read only when the minute freed, 25 to 44 s on, and its edge came up then (bug hunt r12, measured again 2026-10-03).
|
|
105
|
+
*/
|
|
106
|
+
export declare const WATCH_SHARE: number;
|
|
107
|
+
/**
|
|
108
|
+
* Once a group's read found a relay's minute full, the groups' reads there are spread over the minute for a minute
|
|
109
|
+
* (`GROUP_RATION_MS`): at most a sixth of it in any 10 s (5 on a relay of 30), the key read longest ago first. A sliding
|
|
110
|
+
* minute that demand keeps full hands out its requests in bursts: the minute is spent in 25 to 35 s as requests age
|
|
111
|
+
* out, then nothing frees for the rest of it. A private group's admin (its knock poll every 2 s while its link is new)
|
|
112
|
+
* whose members left and came back read nothing for 18 to 42 s at a time, and the member back first waited that long
|
|
113
|
+
* for its edge (bug hunt r12, measured again on 2026-10-03). Writes are not counted: they go first anyway.
|
|
114
|
+
*/
|
|
115
|
+
export declare const GROUP_RATION_WINDOW_MS = 10000;
|
|
116
|
+
/**
|
|
117
|
+
* While a link polls fast (an `urgent` read: its peer, or the peer's offer or answer, is due any moment) within this
|
|
118
|
+
* long, background requests (a community's periodic looks) are held to `BACKGROUND_WHILE_SIGNALING` a minute on each
|
|
119
|
+
* relay rather than their usual share. A fast poll reads every 2 s, one relay after the other.
|
|
120
|
+
*/
|
|
121
|
+
export declare const SIGNALING_WINDOW_MS = 10000;
|
|
122
|
+
/**
|
|
123
|
+
* Background requests a minute on each relay while a link signals: one look every 12 s. Next to a community's
|
|
124
|
+
* lookups (20 a minute), a new group edge on one relay got 10 and read every 6 s, and its offer and answer missed each
|
|
125
|
+
* other's fast windows (2026-09-27). Not none: fast windows can follow one another, and a hub still reads its knocks.
|
|
126
|
+
*/
|
|
127
|
+
export declare const BACKGROUND_WHILE_SIGNALING = 5;
|
|
128
|
+
/**
|
|
129
|
+
* A read of a key the relays answered this recently is answered from that answer, with no request. Several parts of
|
|
130
|
+
* a chat read the contact's keys (the link's poll, its capabilities, DHT delivery), and each tends to read again
|
|
131
|
+
* within a few dozen milliseconds of its last read, when a pace changes or a signal goes out: nothing new can be there
|
|
132
|
+
* yet, and a pairing spent a sixth of its requests on those reads (2026-09-27). A publish under the key forgets it.
|
|
133
|
+
*/
|
|
134
|
+
export declare const FRESH_READ_MS = 500;
|
|
135
|
+
/**
|
|
136
|
+
* Relays whose limit per address is far from the others': this client's share of theirs, a minute, in place of
|
|
137
|
+
* `REQUESTS_PER_MINUTE`. relay.pkarr.org (not a default, see docs/RELAYS.md) allows 10 (`x-ratelimit-limit`), which a
|
|
138
|
+
* browser cannot read without CORS exposing it. pkarr.pubky.app allows 1000 (pkarr.pubky.org, on the same address,
|
|
139
|
+
* 50): 60 of ours leaves room for many peers behind one address, and a page that pairs three contacts in a minute,
|
|
140
|
+
* about ten requests a relay each, still has requests to spare there (2026-09-28). Writes go to every relay and
|
|
141
|
+
* count once one took them; reads go to a relay with requests left.
|
|
142
|
+
*/
|
|
143
|
+
export declare const RELAY_REQUESTS_PER_MINUTE: Record<string, number>;
|
|
144
|
+
/**
|
|
145
|
+
* A read asks the next relay too when the one it asked has not answered within this long, and takes the first good
|
|
146
|
+
* answer. Measured on 2026-10-03 from a home connection: a relay hands over a packet it holds in 0.25 s (0.7 s on a new
|
|
147
|
+
* connection), and one that has to fetch the packet from the DHT first takes 2.7 s. Reads used to wait for a relay's
|
|
148
|
+
* answer before asking the next one, up to the 10 s timeout: a relay that answered slowly or not at all (pkarr.pubky.org
|
|
149
|
+
* on 2026-10-03) made every read of a pairing that slow, and the pairing never finished.
|
|
150
|
+
*/
|
|
151
|
+
export declare const HEDGE_MS = 1500;
|
|
152
|
+
/**
|
|
153
|
+
* The hedge delay for a key whose last read found nothing (404): a relay takes 3 to 5 s to say so (it asks the DHT
|
|
154
|
+
* every time), and a hedge at `HEDGE_MS` would double every poll of a key nobody has published yet.
|
|
155
|
+
*/
|
|
156
|
+
export declare const HEDGE_MISSING_MS = 6000;
|
|
157
|
+
/**
|
|
158
|
+
* A packet that took longer than this to arrive, or a hedge lost to a relay that answered with the packet, is slow: it
|
|
159
|
+
* counts against the relay's breaker like a failure (three in a row trip it, logged as "slow"), while another relay is
|
|
160
|
+
* there to ask. A 404 says nothing either way: every relay is slow to give one.
|
|
161
|
+
*/
|
|
162
|
+
export declare const SLOW_MS = 3000;
|
|
163
|
+
/** A relay found slow goes after the others in every read for this long, unless it answers fast meanwhile. */
|
|
164
|
+
export declare const SLOW_DEMOTE_MS = 60000;
|
|
165
|
+
/** How long each source has to answer a read or a put of the turn record (WISP 06 § Publishing and reading). */
|
|
166
|
+
export declare const TURN_SOURCE_TIMEOUT_MS = 8000;
|
|
167
|
+
export interface RelayTransportOptions {
|
|
168
|
+
relays?: string[];
|
|
169
|
+
timeoutMs?: number;
|
|
170
|
+
fetch?: typeof fetch;
|
|
171
|
+
/**
|
|
172
|
+
* Requests allowed per relay and minute (`REQUESTS_PER_MINUTE`); background ones get a share of it.
|
|
173
|
+
* `Infinity` for relays of one's own, with no limit to stay under (a test's relay in the same process).
|
|
174
|
+
*/
|
|
175
|
+
requestsPerMinute?: number;
|
|
176
|
+
/** How long a read answers the next ones of the same key (`FRESH_READ_MS`); 0 makes every read a request. */
|
|
177
|
+
freshReadMs?: number;
|
|
178
|
+
/** `HEDGE_MS`; `Infinity` asks the next relay only once the one asked failed. */
|
|
179
|
+
hedgeMs?: number;
|
|
180
|
+
/** The circuit breaker's settings (tests shorten its waits); trips are logged with `log`. */
|
|
181
|
+
breaker?: RelayBreakerOptions;
|
|
182
|
+
/** Where a relay that trips or recovers is reported; never with a key. `console.info` by default. */
|
|
183
|
+
log?: (line: string) => void;
|
|
184
|
+
}
|
|
185
|
+
export declare function normalizeRelayUrl(input: string): string | null;
|
|
186
|
+
export declare class RelayTransport implements PkarrTransport {
|
|
187
|
+
private relays;
|
|
188
|
+
private readonly timeoutMs;
|
|
189
|
+
private readonly fetchFn;
|
|
190
|
+
private readonly timeListeners;
|
|
191
|
+
private readonly lastTimestamp;
|
|
192
|
+
private readonly newest;
|
|
193
|
+
/**
|
|
194
|
+
* The latest time of any packet read under a key, whoever dated it: the next packet this client puts there is dated
|
|
195
|
+
* past it (`nextTimestamp`). A key is not always one writer's with one clock: a group's lobby, beacon and knock
|
|
196
|
+
* records are written by every member, an inviter warms its contact's key with an empty packet, and this device's
|
|
197
|
+
* own clock may have been set back since it last wrote. A relay and the DHT keep only the packet dated latest, so
|
|
198
|
+
* one dated by this clock alone, when it is behind, was refused (409) or silently never read, until this clock
|
|
199
|
+
* caught up with the other one: minutes, or an hour.
|
|
200
|
+
*/
|
|
201
|
+
private readonly seenTimestamp;
|
|
202
|
+
/**
|
|
203
|
+
* The last packet this client put under a key that a relay took. A read the budget holds back answers the newer of
|
|
204
|
+
* it and the last one read: a hub that wrote its own beacon entry since it last read the beacon must not see that
|
|
205
|
+
* entry as old as the one it replaced (it would stop counting itself at its community's door until its next write).
|
|
206
|
+
*/
|
|
207
|
+
private readonly written;
|
|
208
|
+
private readonly coolingDown;
|
|
209
|
+
private readonly networkCooldown;
|
|
210
|
+
private cursor;
|
|
211
|
+
/** Per key, the relay that answered its last read: the next read of the key starts at the one after it (`resolve`). */
|
|
212
|
+
private readonly lastReadFrom;
|
|
213
|
+
private readonly spent;
|
|
214
|
+
private readonly spentBackground;
|
|
215
|
+
/** Groups' urgent reads on each relay in the last `GROUP_BURST_MS`. */
|
|
216
|
+
private readonly spentGroupUrgent;
|
|
217
|
+
/** Watch reads on each relay in the last `GROUP_RATION_WINDOW_MS` (`WATCH_SHARE`). */
|
|
218
|
+
private readonly spentWatch;
|
|
219
|
+
/** Groups' reads past the limit on each relay in the last `GROUP_OVER_PACE_MS` (`GROUP_SIGNALING_ALLOWANCE_SHARE`). */
|
|
220
|
+
private readonly spentGroupOver;
|
|
221
|
+
/** Per contact, its departed reads past the limit in the last minute, every relay together (`DEPARTED_READS`). */
|
|
222
|
+
private readonly departedOver;
|
|
223
|
+
/**
|
|
224
|
+
* Per key a group reads (not in the background), when a read of it last went out and when it last asked: whose turn
|
|
225
|
+
* it is under the watch share (`WATCH_SHARE`) and while the groups' reads are rationed (`GROUP_RATION_WINDOW_MS`).
|
|
226
|
+
*/
|
|
227
|
+
private readonly readTurns;
|
|
228
|
+
/** Per key read in turn (`isTurnRead`), when a read of it last went out and when it last asked (`READ_TURN_MS`). */
|
|
229
|
+
private readonly keyTurns;
|
|
230
|
+
/** Groups' reads (not background ones) on each relay in the last `GROUP_RATION_WINDOW_MS`. */
|
|
231
|
+
private readonly spentGroupReads;
|
|
232
|
+
/** When a group's read last found each relay's minute full: its reads there are rationed for `GROUP_RATION_MS`. */
|
|
233
|
+
private readonly groupsFullAt;
|
|
234
|
+
/** When a link's write was last refused on each relay (`chat <relay>`, `group <relay>`), while it waits for the budget. */
|
|
235
|
+
private readonly writeWaiting;
|
|
236
|
+
/**
|
|
237
|
+
* Per key a 1:1 chat asks for: when it last read urgently (for the next minute, groups leave it `CHAT_RESERVE` on
|
|
238
|
+
* every relay) and when the budget last refused it on each relay (the same, on that relay). A read of the key at a
|
|
239
|
+
* slow pace (the chat is live, or back in the background) drops it: `CHAT_RESERVE`.
|
|
240
|
+
*/
|
|
241
|
+
private readonly chatNeeds;
|
|
242
|
+
/** When a link (a chat's or a group's) last asked urgently: background requests yield for `SIGNALING_WINDOW_MS`. */
|
|
243
|
+
private urgentAt;
|
|
244
|
+
/** Timestamp of the last packet sent to each relay, per key: the compare-and-swap value for the next one. */
|
|
245
|
+
private readonly lastPut;
|
|
246
|
+
/** Per relay and key, the newest packet that relay held back for its budget while another relay took it (`catchUpLater`). */
|
|
247
|
+
private readonly catchUp;
|
|
248
|
+
private catchUpTimer;
|
|
249
|
+
/**
|
|
250
|
+
* Per key whose reads the budget held back since its last read went out: when a request frees for it
|
|
251
|
+
* (`readHeldBackFor`), how many times in a row, and since when (`READ_STARVED_MS`).
|
|
252
|
+
*/
|
|
253
|
+
private readonly heldBack;
|
|
254
|
+
/** When the relays last answered a read of each key, for `FRESH_READ_MS`. */
|
|
255
|
+
private readonly readAt;
|
|
256
|
+
private readonly freshReadMs;
|
|
257
|
+
private readonly perMinute;
|
|
258
|
+
/** `requestsPerMinute` was given: it bounds every relay, one with its own share (`RELAY_REQUESTS_PER_MINUTE`) too. */
|
|
259
|
+
private readonly perMinuteGiven;
|
|
260
|
+
private readonly backgroundPerMinute;
|
|
261
|
+
private readonly backgroundWhileSignaling;
|
|
262
|
+
private readonly breaker;
|
|
263
|
+
/** The relay the last read was answered by. */
|
|
264
|
+
private lastRelay;
|
|
265
|
+
private readonly hedgeMs;
|
|
266
|
+
/** Until when each relay found slow (`SLOW_MS`) goes after the others in a read (`readOrder`). */
|
|
267
|
+
private readonly slowUntil;
|
|
268
|
+
/** Keys whose last read was answered 404: their next read hedges later (`HEDGE_MISSING_MS`). */
|
|
269
|
+
private readonly missing;
|
|
270
|
+
private readonly listeners;
|
|
271
|
+
constructor(options?: RelayTransportOptions);
|
|
272
|
+
/** How reads go and how each relay is doing, for the connection panel. */
|
|
273
|
+
discovery(): DiscoveryStatus;
|
|
274
|
+
/** Back online on some network: relays that failed (or rate limited this address) on the old one are asked again. */
|
|
275
|
+
networkChanged(): void;
|
|
276
|
+
/** Called when a relay trips or recovers. */
|
|
277
|
+
subscribe(listener: (change?: DiscoveryChange) => void): () => void;
|
|
278
|
+
private changed;
|
|
279
|
+
/** What the relay did, for its breaker. */
|
|
280
|
+
private answered;
|
|
281
|
+
setRelays(relays: string[]): void;
|
|
282
|
+
describe(): {
|
|
283
|
+
protocol: string;
|
|
284
|
+
relays: string[];
|
|
285
|
+
};
|
|
286
|
+
/**
|
|
287
|
+
* Publishes to every relay. Peers may be configured with different relay
|
|
288
|
+
* sets; writing everywhere keeps the overlap warm, the DHT covers the rest.
|
|
289
|
+
* Returns once one relay took the packet: the others finish in the background.
|
|
290
|
+
*/
|
|
291
|
+
publish(identity: Identity, records: GhostRecord[], options?: PkarrRequestOptions): Promise<void>;
|
|
292
|
+
/**
|
|
293
|
+
* The time the next packet under a key is dated: this clock's, and past every packet this client put or read there.
|
|
294
|
+
* BEP44 sequence numbers must strictly increase, and the clock that dated the last one may not be this one's.
|
|
295
|
+
*/
|
|
296
|
+
nextTimestamp(pubKeyZ32: string): bigint;
|
|
297
|
+
/**
|
|
298
|
+
* Signs the records, dated by `nextTimestamp`, and hands the payload to `put` (the relays; the CLI adds the DHT).
|
|
299
|
+
* `put` calls `conflict` for a relay that answered 409: it holds a packet under this key dated at or after this one,
|
|
300
|
+
* which this client has not read (an inviter's warm packet under the key it gave its contact, from a clock ahead of
|
|
301
|
+
* this one). That packet is read from that relay, and the records go again dated just past it, once. Without this
|
|
302
|
+
* the packet was refused until this device's clock passed the other one's, however long that took, and on a relay
|
|
303
|
+
* that did take it, readers still preferred the later-dated empty packet of another relay.
|
|
304
|
+
*/
|
|
305
|
+
publishDated(identity: Identity, records: GhostRecord[], put: (pubKeyZ32: string, payload: Uint8Array, timestamp: bigint, conflict: (relay: string) => void) => Promise<void>, options?: PkarrRequestOptions, again?: boolean): Promise<void>;
|
|
306
|
+
/** One relay's packet for a key, read now: its time, kept for `nextTimestamp`. Null when it has none or does not answer. */
|
|
307
|
+
private heldAt;
|
|
308
|
+
/** A packet under this key was read (on a relay, or by the CLI on the DHT): its time, for `nextTimestamp`. */
|
|
309
|
+
sawTimestamp(pubKeyZ32: string, timestamp: bigint): void;
|
|
310
|
+
/** Puts a payload signed elsewhere (a did:dht document), byte for byte, on every relay. `conflict`: as `publishDated` gives it. */
|
|
311
|
+
publishPayload(pubKeyZ32: string, payload: Uint8Array, options?: PkarrRequestOptions, conflict?: (relay: string) => void): Promise<void>;
|
|
312
|
+
/**
|
|
313
|
+
* Puts the packet on every relay and settles as soon as one of them took it. A relay that is slow to
|
|
314
|
+
* answer (one that stores the packet and answers the PUT only at the timeout) must not hold a link's
|
|
315
|
+
* presence, offer or answer back: the rest finish in the background, their outcomes still counted.
|
|
316
|
+
* When no relay takes it, this waits for all of them to say why.
|
|
317
|
+
*/
|
|
318
|
+
private putEverywhere;
|
|
319
|
+
/**
|
|
320
|
+
* Public relays rate limit by IP (120 requests a minute at the time of
|
|
321
|
+
* writing) and several peers may share one address, so a poll costs one
|
|
322
|
+
* request: one relay is asked, the next one when this one fails, or when it
|
|
323
|
+
* has not answered within `HEDGE_MS` (a hedge: the first good answer wins and
|
|
324
|
+
* the other request is dropped). The newest validly signed packet seen so far
|
|
325
|
+
* wins, which also covers a relay that is still serving an older cached copy.
|
|
326
|
+
*
|
|
327
|
+
* In turn per key: a key's next read starts at the relay after the one that answered its last read. A relay that
|
|
328
|
+
* does not have a packet yet (a publish that reached only the other relay, one rate limited there) answers a key's
|
|
329
|
+
* reads at most once in a row. With one turn for all keys, a link that read its peer between two other reads landed
|
|
330
|
+
* on the same relay every time: a restarted member's offer, only on `pkarr.pubky.app`, went unread for 12 to 60 s
|
|
331
|
+
* while the member at the other end read `pkarr.pubky.org` (bug hunt r5a, 2026-09-29). A relay found slow lately
|
|
332
|
+
* (`SLOW_DEMOTE_MS`) goes after the others, whatever the turn.
|
|
333
|
+
*
|
|
334
|
+
* A hedge spends a second request, so it goes only where the budget has requests to spare (`hedgeRoom`), never for a
|
|
335
|
+
* background read (nobody waits on it), and later for a key whose last read found nothing (`HEDGE_MISSING_MS`).
|
|
336
|
+
*/
|
|
337
|
+
resolve(pubKeyZ32: string, options?: PkarrRequestOptions): Promise<SignedPacket | null>;
|
|
338
|
+
/** The order a key's read asks the relays in: in turn per key (see `resolve`), relays found slow lately last. */
|
|
339
|
+
private readOrder;
|
|
340
|
+
/** One GET of a key at one relay, which `controller` drops. Never rejects: what happened is the outcome. */
|
|
341
|
+
private readFromRelay;
|
|
342
|
+
/**
|
|
343
|
+
* The relay was slow (`SLOW_MS`): it goes after the others for a while, and counts it against its breaker while
|
|
344
|
+
* another relay is there to ask. With none, a slow answer beats no answer: it counts as one.
|
|
345
|
+
*/
|
|
346
|
+
private slow;
|
|
347
|
+
/**
|
|
348
|
+
* A hedge may go to this relay: its minute has more requests left than what groups leave a chat (`reserveOf`), so
|
|
349
|
+
* a second request for a read that already went out never takes one a pairing needs.
|
|
350
|
+
*/
|
|
351
|
+
private hedgeRoom;
|
|
352
|
+
readAnsweredAt(pubKeyZ32: string): number | undefined;
|
|
353
|
+
readHeldBackFor(pubKeyZ32: string): number | undefined;
|
|
354
|
+
private heldBackUntil;
|
|
355
|
+
/** The relays answered a read of this key now; answers older than `FRESH_READ_MS` are dropped as the list grows. */
|
|
356
|
+
private answeredRead;
|
|
357
|
+
/** The relay that answered a key's read, for its next one; the keys read longest ago go past `READ_TURNS_KEPT`. */
|
|
358
|
+
private readFrom;
|
|
359
|
+
/**
|
|
360
|
+
* A relay whose budget (this client's, or its own rate limit) held a packet back that another relay took: it gets
|
|
361
|
+
* that packet when it frees a request, as a background write. Only the newest per key and relay; a newer packet put
|
|
362
|
+
* everywhere drops it. Without this, that relay kept the key's older packet for good, and an app that restarted and
|
|
363
|
+
* read it first found a contact's offer long answered, answered it again, and waited on it (bug hunt r7a).
|
|
364
|
+
*/
|
|
365
|
+
private catchUpLater;
|
|
366
|
+
private scheduleCatchUp;
|
|
367
|
+
private runCatchUp;
|
|
368
|
+
private put;
|
|
369
|
+
/**
|
|
370
|
+
* Discovery reads and writes share a bounded per-relay request budget; background requests only part of it, and
|
|
371
|
+
* groups leave a chat the budget refused its reserve. A link's write the budget refused goes before any read
|
|
372
|
+
* once a request is free again.
|
|
373
|
+
*/
|
|
374
|
+
private take;
|
|
375
|
+
/**
|
|
376
|
+
* How long until this relay's budget takes this request, 0 when it would now: the oldest request of the minute over
|
|
377
|
+
* a limit ages out, a chat's reserve lapses, or a waiting write has had its turn. Keeps the lists to the minute, oldest first.
|
|
378
|
+
*
|
|
379
|
+
* Who goes first: a chat's refused write holds back everything but chat writes; a group's refused write holds back
|
|
380
|
+
* group reads and background requests, never a chat's. Background requests yield to a link that signals. A chat's
|
|
381
|
+
* signaling goes over the limit by its allowance (`SIGNALING_ALLOWANCE_SHARE`), and so do a few of its reads of a
|
|
382
|
+
* contact that just went away (`DEPARTED_READS`).
|
|
383
|
+
*/
|
|
384
|
+
private heldFor;
|
|
385
|
+
/** A group's read of `key` asks: it waits for its turn from now on, unless it is taken (`readsAhead`). */
|
|
386
|
+
private readAsked;
|
|
387
|
+
/**
|
|
388
|
+
* Keys a group reads, still asking (within `WATCH_TURN_MS`), that were read longer ago than `key`: a share keeps a
|
|
389
|
+
* request for each. With `watchLane`, only watched keys the same other limits hold: one the groups' burst holds back
|
|
390
|
+
* would keep a turn it cannot take.
|
|
391
|
+
*/
|
|
392
|
+
private readsAhead;
|
|
393
|
+
/** A read of `key` that takes turns asks: it waits for its turn from now on, unless it is taken (`turnAhead`). */
|
|
394
|
+
private turnAsked;
|
|
395
|
+
/**
|
|
396
|
+
* Whether a key read in turn longer ago than `key`, still asking, would take this relay's next request: one read in the
|
|
397
|
+
* background for a background read, and a chat's that is starved (`READ_STARVED_MS`) for any. One asks again after
|
|
398
|
+
* the budget held it back (a link's poll does, a one-off look does not), and keeps asking within `READ_TURN_MS` of its
|
|
399
|
+
* last ask, or of when it was told the budget frees a request for it (`readHeldBackFor`).
|
|
400
|
+
* One the budget holds back on its own account (a group's read, for the chats' reserve) keeps no turn: a group key
|
|
401
|
+
* waiting for the chats held every chat's read back (CLI lab, 2026-10-13).
|
|
402
|
+
*/
|
|
403
|
+
private turnAhead;
|
|
404
|
+
/** A 1:1 chat's read of `key` the budget has held back for `READ_STARVED_MS` without a break. */
|
|
405
|
+
private starved;
|
|
406
|
+
/** This contact's departed reads past the limit in the last minute (`DEPARTED_READS`). */
|
|
407
|
+
private departedReads;
|
|
408
|
+
/** One more, the contacts with none in the last minute dropped. */
|
|
409
|
+
private departedOverAdd;
|
|
410
|
+
private chatNeed;
|
|
411
|
+
/** How long groups still leave a chat its reserve on this relay (`CHAT_RESERVE`); a chat's need a minute old goes. */
|
|
412
|
+
private chatReservedFor;
|
|
413
|
+
/** Requests allowed to this relay a minute: this client's budget, or the relay's own share (`RELAY_REQUESTS_PER_MINUTE`). */
|
|
414
|
+
private limitOf;
|
|
415
|
+
/** What groups leave a chat on this relay: `CHAT_RESERVE`, or a third of a smaller budget. */
|
|
416
|
+
private reserveOf;
|
|
417
|
+
private isCoolingDown;
|
|
418
|
+
/** Left alone after failing at the network level. */
|
|
419
|
+
private networkCoolingDown;
|
|
420
|
+
/** How much longer the relay asked (429) to be left alone; 0 when it did not. */
|
|
421
|
+
private rateLimitedFor;
|
|
422
|
+
/** Leaves the relay alone for as long as its 429 asks; returns that, in ms. */
|
|
423
|
+
private coolDown;
|
|
424
|
+
/**
|
|
425
|
+
* One request under one time limit. `read` runs before the timer is cleared, so a body read there is bounded in
|
|
426
|
+
* time as well: a relay that sends its headers and then trickles, or never ends, is given up on like one that
|
|
427
|
+
* never answered.
|
|
428
|
+
*/
|
|
429
|
+
/**
|
|
430
|
+
* The relay's own time, when its answer says it and this runtime may read it: Node and the Desktop can, a browser
|
|
431
|
+
* only when the relay exposes the header to other origins. Held against this device's clock (`ClockWatch`).
|
|
432
|
+
*/
|
|
433
|
+
private serverTime;
|
|
434
|
+
onServerTime(listener: (time: ServerTime) => void): () => void;
|
|
435
|
+
/**
|
|
436
|
+
* The turn record's read (WISP 06 § Publishing and reading): every relay, in parallel, `TURN_SOURCE_TIMEOUT_MS`
|
|
437
|
+
* each. Unlike `resolve`, it does not stop at the first relay that answers, keeps nothing, and answers nothing from
|
|
438
|
+
* memory. Each request counts in the relay's minute, so chats see it, but is never held back by it: a device may
|
|
439
|
+
* not act before it has read its turn.
|
|
440
|
+
*/
|
|
441
|
+
turnRead(pubKeyZ32: string, options?: {
|
|
442
|
+
timeoutMs?: number;
|
|
443
|
+
}): Promise<TurnSourceAnswer[]>;
|
|
444
|
+
/**
|
|
445
|
+
* The turn record's put: the bytes as given, to each relay `conditions` names, with `If-Match` on the sequence that
|
|
446
|
+
* relay is known to hold (none where it held no record). Unlike `putEverywhere`, a relay that refuses (409, 412,
|
|
447
|
+
* 428) is not asked again without the condition: its refusal is the answer, and every relay's answer is reported.
|
|
448
|
+
*/
|
|
449
|
+
turnPut(pubKeyZ32: string, payload: Uint8Array, conditions: TurnConditions): Promise<TurnSourcePut[]>;
|
|
450
|
+
private turnRequest;
|
|
451
|
+
/** `cancel`: this client drops the request (a hedged read another relay answered first). */
|
|
452
|
+
private request;
|
|
453
|
+
}
|
|
454
|
+
/**
|
|
455
|
+
* A relay's answer body, at most RELAY_PAYLOAD_MAX_BYTES: refused on a larger `content-length` before anything is
|
|
456
|
+
* read, and otherwise streamed with a running count, so a relay (a default one or one the person added, working or
|
|
457
|
+
* compromised) cannot fill memory with a huge or endless body. Stops when `signal` aborts.
|
|
458
|
+
*/
|
|
459
|
+
export declare function readRelayBody(response: Response, signal: AbortSignal, max?: number): Promise<Uint8Array>;
|
|
@@ -0,0 +1,99 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* A circuit breaker per Pkarr relay. A relay that failed `threshold` times in a row (no answer, a server error,
|
|
3
|
+
* its own rate limit, 429, or an answer too slow to use, `SLOW_MS` in relay.ts) is left alone for a while: a minute the first time, twice as long each time it
|
|
4
|
+
* trips again, five minutes at most. When the wait is over, one request goes to it (the probe); an answer
|
|
5
|
+
* closes the breaker, a failure opens it again for longer. The relays still closed take its turns meanwhile.
|
|
6
|
+
*
|
|
7
|
+
* Only what the relay did counts: a request this client held back for its own budget is not a failure, and an
|
|
8
|
+
* answer the protocol expects (404, 409, 412, 428) is a relay working as it should.
|
|
9
|
+
*/
|
|
10
|
+
/** Failures in a row that trip a relay's breaker. */
|
|
11
|
+
export declare const BREAKER_THRESHOLD = 3;
|
|
12
|
+
/** How long a relay is left alone the first time its breaker trips; doubled on each trip in a row. */
|
|
13
|
+
export declare const BREAKER_BASE_MS = 60000;
|
|
14
|
+
/** The longest a relay is left alone. */
|
|
15
|
+
export declare const BREAKER_MAX_MS: number;
|
|
16
|
+
/**
|
|
17
|
+
* While every relay is left alone for failing, one of them is asked this often anyway: with nothing else to try, a
|
|
18
|
+
* long wait only delays noticing that they answer again (a link stayed down minutes after the relays came back).
|
|
19
|
+
*/
|
|
20
|
+
export declare const BREAKER_ALL_DOWN_PROBE_MS = 15000;
|
|
21
|
+
/** Why a request to a relay failed: its rate limit (`throttled`), or anything else (`error`). */
|
|
22
|
+
export type RelayFailure = "throttled" | "error";
|
|
23
|
+
/** A relay as the connection panel shows it: `ok`, `throttled` (its rate limit) or `failing`, until when. */
|
|
24
|
+
export interface RelayHealth {
|
|
25
|
+
relay: string;
|
|
26
|
+
state: "ok" | "throttled" | "failing";
|
|
27
|
+
/** When the relay is asked again (ms since the epoch), while it is left alone. */
|
|
28
|
+
until?: number;
|
|
29
|
+
/** What went wrong last, in a few words; never a key. */
|
|
30
|
+
reason?: string;
|
|
31
|
+
}
|
|
32
|
+
/**
|
|
33
|
+
* How this client reaches Pkarr right now, for the connection panel: the path its last read took ("dht", or
|
|
34
|
+
* the relay that answered), and the health of each relay it uses (none where it reads the DHT alone).
|
|
35
|
+
*/
|
|
36
|
+
export interface DiscoveryStatus {
|
|
37
|
+
path: {
|
|
38
|
+
via: "dht";
|
|
39
|
+
} | {
|
|
40
|
+
via: "relay";
|
|
41
|
+
relay: string;
|
|
42
|
+
} | null;
|
|
43
|
+
relays: RelayHealth[];
|
|
44
|
+
}
|
|
45
|
+
export interface RelayBreakerOptions {
|
|
46
|
+
threshold?: number;
|
|
47
|
+
baseMs?: number;
|
|
48
|
+
maxMs?: number;
|
|
49
|
+
/** `BREAKER_ALL_DOWN_PROBE_MS`. */
|
|
50
|
+
allDownProbeMs?: number;
|
|
51
|
+
now?: () => number;
|
|
52
|
+
/** Told each time a relay trips: which, why, and for how long. */
|
|
53
|
+
onTrip?: (relay: string, reason: string, forMs: number) => void;
|
|
54
|
+
/** Told when a tripped relay answered its probe. */
|
|
55
|
+
onRecover?: (relay: string) => void;
|
|
56
|
+
}
|
|
57
|
+
export declare class RelayBreaker {
|
|
58
|
+
private readonly options;
|
|
59
|
+
private readonly circuits;
|
|
60
|
+
private readonly threshold;
|
|
61
|
+
private readonly baseMs;
|
|
62
|
+
private readonly maxMs;
|
|
63
|
+
private readonly allDownProbeMs;
|
|
64
|
+
private readonly now;
|
|
65
|
+
/** When a relay was last asked because every relay was left alone. */
|
|
66
|
+
private lastAllDownProbe;
|
|
67
|
+
constructor(options?: RelayBreakerOptions);
|
|
68
|
+
private circuit;
|
|
69
|
+
/** How long the relay is still left alone, in ms; 0 when a request may go (closed, or its probe is due). */
|
|
70
|
+
blockedFor(relay: string): number;
|
|
71
|
+
/** Why the relay is left alone, while it is: its rate limit or failures. */
|
|
72
|
+
blockedKind(relay: string): RelayFailure | undefined;
|
|
73
|
+
/** A request is going to the relay now: its probe, when the wait is over. Call only when `blockedFor` is 0. */
|
|
74
|
+
begin(relay: string): void;
|
|
75
|
+
/**
|
|
76
|
+
* When every relay of `relays` is left alone for failing (none for its rate limit, none with its probe due or out),
|
|
77
|
+
* the one whose wait ends first may be asked now, once every `BREAKER_ALL_DOWN_PROBE_MS`. Returns it, or null. The
|
|
78
|
+
* caller marks the request with `beginAllDown` when it really goes (a request its budget holds back is no probe).
|
|
79
|
+
*/
|
|
80
|
+
allDownProbe(relays: string[]): string | null;
|
|
81
|
+
/** The probe `allDownProbe` named is going now: its answer closes the breaker, a failure trips it again. */
|
|
82
|
+
beginAllDown(relay: string): void;
|
|
83
|
+
/**
|
|
84
|
+
* A request that went to the relay was dropped before it answered, by this client (another relay answered first), or
|
|
85
|
+
* its answer says nothing either way: a probe among them is no longer out, and the next request may probe again.
|
|
86
|
+
*/
|
|
87
|
+
cancel(relay: string): void;
|
|
88
|
+
/** The relay answered: whatever was wrong is over. */
|
|
89
|
+
success(relay: string): void;
|
|
90
|
+
/** The relay failed a request; a probe that fails trips it again at once. */
|
|
91
|
+
failure(relay: string, kind: RelayFailure, reason: string): void;
|
|
92
|
+
private trip;
|
|
93
|
+
/** How long until a relay left alone is asked again: its wait, or the next probe while every relay of `relays` is left alone. */
|
|
94
|
+
askedAgainIn(relay: string, relays: string[]): number;
|
|
95
|
+
/** A new network: every relay starts fresh. */
|
|
96
|
+
reset(): void;
|
|
97
|
+
/** Each relay's health, in the order given. */
|
|
98
|
+
health(relays: string[]): RelayHealth[];
|
|
99
|
+
}
|