@ghostlytools/sdk 1.3.10 → 1.4.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/dist/app.js +19 -4
- package/dist/app.js.map +1 -1
- package/dist/core.js +2 -2
- package/dist/{fakes-DRPAYl6q.js → fakes-DkFOiAo6.js} +2 -2
- package/dist/{fakes-DRPAYl6q.js.map → fakes-DkFOiAo6.js.map} +1 -1
- package/dist/fakes.js +1 -1
- package/dist/index.js +2 -2
- package/dist/{keet-identity-key-D-FT8FmL.js → keet-identity-key-CZ27HbZq.js} +2 -2
- package/dist/{keet-identity-key-D-FT8FmL.js.map → keet-identity-key-CZ27HbZq.js.map} +1 -1
- package/dist/{src-DFY7sUQ4.js → src-BBoCvzFt.js} +28665 -26743
- package/dist/src-BBoCvzFt.js.map +1 -0
- package/dist/testing.js +3 -3
- package/dist/types/core/src/appBundle.d.ts +4 -3
- package/dist/types/core/src/chatFiles.d.ts +32 -2
- package/dist/types/core/src/contactInbox.d.ts +68 -0
- package/dist/types/core/src/contactLink.d.ts +27 -0
- package/dist/types/core/src/contactRecords.d.ts +87 -0
- package/dist/types/core/src/dhtDelivery.d.ts +17 -0
- package/dist/types/core/src/ghostlink.d.ts +34 -3
- package/dist/types/core/src/groupCommunity.d.ts +35 -3
- package/dist/types/core/src/groupFiles.d.ts +5 -5
- package/dist/types/core/src/groupMeta.d.ts +19 -0
- package/dist/types/core/src/groupSession.d.ts +47 -5
- package/dist/types/core/src/groupSignals.d.ts +12 -1
- package/dist/types/core/src/index.d.ts +7 -0
- package/dist/types/core/src/link.d.ts +22 -2
- package/dist/types/core/src/miniApp.d.ts +56 -6
- package/dist/types/core/src/pairedCalls.d.ts +8 -3
- package/dist/types/core/src/pairedHttp.d.ts +9 -1
- package/dist/types/core/src/relay.d.ts +71 -6
- package/dist/types/core/src/transport.d.ts +21 -0
- package/dist/types/core/src/x401.d.ts +140 -0
- package/dist/types/core/src/x401Credential.d.ts +58 -0
- package/dist/types/core/src/x401Presentation.d.ts +96 -0
- package/dist/types/core/src/x401Request.d.ts +79 -0
- package/dist/{verify-sFNwqV7P.js → verify-BWtbTAs7.js} +2 -2
- package/dist/{verify-sFNwqV7P.js.map → verify-BWtbTAs7.js.map} +1 -1
- package/package.json +3 -3
- package/dist/src-DFY7sUQ4.js.map +0 -1
|
@@ -278,6 +278,8 @@ export interface GroupState {
|
|
|
278
278
|
nicks: Record<string, string>;
|
|
279
279
|
/** The group's metadata (its picture), as the admin last signed it and I accepted it. */
|
|
280
280
|
meta?: GroupMeta;
|
|
281
|
+
/** A few statements I held before `meta`, oldest first, for a member back from away (`keepPastGroupMeta`). Absent in older states. */
|
|
282
|
+
metaPast?: GroupMeta[];
|
|
281
283
|
/**
|
|
282
284
|
* My frames no edge took when I said them, as `e:n`, oldest first, kept until each was looked at once for saying again
|
|
283
285
|
* (`resealBehind`): I may have been behind on the chain without knowing. Absent in older states.
|
|
@@ -289,6 +291,9 @@ export interface GroupState {
|
|
|
289
291
|
/**
|
|
290
292
|
* `completes`: this message was delivered before from a copy another member handed on without its author's whole
|
|
291
293
|
* signature (its text only); this is the whole one, with the mentions, reply and hop count its author put there.
|
|
294
|
+
* `live`: it came straight from its author, over the author's own edge, as it was written: not handed on by another
|
|
295
|
+
* member, not an answer to my sync (a catch-up) and not one that waited for a secret. How long it took says how far
|
|
296
|
+
* the author's clock is from mine.
|
|
292
297
|
*/
|
|
293
298
|
/**
|
|
294
299
|
* `frame`: the frame the message came in, as it is kept to hand on to a member who missed it (only its author's own
|
|
@@ -308,6 +313,7 @@ export interface GroupIncomingMessage {
|
|
|
308
313
|
file?: GroupFileMeta;
|
|
309
314
|
completes?: true;
|
|
310
315
|
frame?: GroupMessageFrame;
|
|
316
|
+
live?: true;
|
|
311
317
|
}
|
|
312
318
|
export interface GroupSessionHooks {
|
|
313
319
|
save(state: GroupState): Promise<void>;
|
|
@@ -424,8 +430,25 @@ export declare class GroupSession {
|
|
|
424
430
|
* before revision 2026-10-13, and never marks them seen) is not handed them again at every sync. In memory only.
|
|
425
431
|
*/
|
|
426
432
|
private leaversHanded;
|
|
433
|
+
/**
|
|
434
|
+
* The frames a commit took out of the logs (`pruneRelay`), newest last, and whether the app holds them with its
|
|
435
|
+
* messages: a removal's `left` mark can come after its commit, and what the leaver wrote is then kept again
|
|
436
|
+
* (`unprune`). In memory only: started again, the app's rows bring theirs back.
|
|
437
|
+
*/
|
|
438
|
+
private pruned;
|
|
427
439
|
/** Syncs answered per member, a few a minute (`GROUP_LIMITS.syncAnswers`). In memory only. */
|
|
428
440
|
private syncsAnswered;
|
|
441
|
+
/**
|
|
442
|
+
* Per author and epoch, the highest number another member's sync says it has (`have`), for the epochs I was in and
|
|
443
|
+
* of which I hold nothing at all (`hear`): what `lacking` names, so another member is asked for it. Only a member's
|
|
444
|
+
* word, so it never counts as seen. In memory only: the syncs come again when the edges do.
|
|
445
|
+
*/
|
|
446
|
+
private heard;
|
|
447
|
+
/**
|
|
448
|
+
* Per member: until when what comes over its edge may be its answer to my sync (`syncFrame`), a catch-up and not a
|
|
449
|
+
* message written just now. Each frame of the answer keeps it open: it goes a slice at a time. In memory only.
|
|
450
|
+
*/
|
|
451
|
+
private readonly answering;
|
|
429
452
|
/** Catch-up answers still going out, a slice at a time (`handOut`). */
|
|
430
453
|
private readonly answers;
|
|
431
454
|
/**
|
|
@@ -485,6 +508,7 @@ export declare class GroupSession {
|
|
|
485
508
|
private policyOf;
|
|
486
509
|
/** The current epoch's rendezvous secret (its beacon and lobbies), once its secret is here. */
|
|
487
510
|
get rendezvous(): string | undefined;
|
|
511
|
+
private now;
|
|
488
512
|
/** Epochs whose messages this member can still read. */
|
|
489
513
|
get readableEpochs(): number[];
|
|
490
514
|
/**
|
|
@@ -506,8 +530,19 @@ export declare class GroupSession {
|
|
|
506
530
|
* is for another member to hand on.
|
|
507
531
|
*/
|
|
508
532
|
lacking(): Map<string, string>;
|
|
509
|
-
/**
|
|
533
|
+
/**
|
|
534
|
+
* What a sync names in `miss` for one sender now: per epoch, the newest `GROUP_LIMITS.miss` numbers that never arrived.
|
|
535
|
+
* And, for an epoch of which none arrived, the newest numbers another member said it has (`heard`): a member back
|
|
536
|
+
* after someone joined, whose author wrote 32 since (all its own answer holds), had nothing below them to ask for.
|
|
537
|
+
*/
|
|
510
538
|
missOf(sender: string): Record<string, number[]>;
|
|
539
|
+
/**
|
|
540
|
+
* Whether `member` may hold some of what never reached me from `sender` (`missOf`): it was in one of those epochs.
|
|
541
|
+
* One let in since was not, and a member asks it for them in vain.
|
|
542
|
+
*/
|
|
543
|
+
mayHold(member: string, sender: string): boolean;
|
|
544
|
+
/** What another member's sync says it has of the epochs I was in, can read, and hold nothing of (`heard`). */
|
|
545
|
+
private hear;
|
|
511
546
|
/** Whether any of `asked` (per epoch, as `missOf` gave them) arrived since: the member asked holds what is missing. */
|
|
512
547
|
filledSince(sender: string, asked: Record<string, number[]>): boolean;
|
|
513
548
|
private serialize;
|
|
@@ -549,6 +584,8 @@ export declare class GroupSession {
|
|
|
549
584
|
* epochs before its leave (WISP 902 § Catch-up).
|
|
550
585
|
*/
|
|
551
586
|
private pruneRelay;
|
|
587
|
+
/** The frames `pruneRelay` dropped that are handed on again now (a removal's `left` mark came after it), back in their logs. */
|
|
588
|
+
private unprune;
|
|
552
589
|
/** Another member's edit, kept to hand on: the latest per message; the oldest go once the log is full. False: one as new was kept. */
|
|
553
590
|
private keepEdit;
|
|
554
591
|
/** A frame of another member, kept to hand on; the oldest go once the log is full. */
|
|
@@ -636,9 +673,10 @@ export declare class GroupSession {
|
|
|
636
673
|
}>;
|
|
637
674
|
/**
|
|
638
675
|
* What to tell a member whose edge just opened: where I am, what I have from everyone and what never arrived below
|
|
639
|
-
* that. `ask`: the members whose messages I want this one to hand on, since their own edges to me are down.
|
|
676
|
+
* that. `ask`: the members whose messages I want this one to hand on, since their own edges to me are down. `to`: the
|
|
677
|
+
* member it goes to, whose frames for a while may be its answer, a catch-up (never `live`).
|
|
640
678
|
*/
|
|
641
|
-
syncFrame(ask?: readonly string[]): GroupSyncFrame;
|
|
679
|
+
syncFrame(ask?: readonly string[], to?: string): GroupSyncFrame;
|
|
642
680
|
/** Sequence numbers below the highest seen that never arrived, the newest `miss` of them. */
|
|
643
681
|
private gaps;
|
|
644
682
|
setNick(key: string, nick: string | undefined): Promise<void>;
|
|
@@ -711,7 +749,9 @@ export declare class GroupSession {
|
|
|
711
749
|
* The author's name in a message (`nk`), when the author's signature over it (`ns`) holds: any copy, handed on or
|
|
712
750
|
* not, whole or not, since a member handing it on can only drop it. Taken only from a message newer than the one it
|
|
713
751
|
* last came in, or than the moment an edge last said it (`setNick`), so a catch-up's older pages never bring back a
|
|
714
|
-
* name the member changed since.
|
|
752
|
+
* name the member changed since. The name I hold already costs no signature check: a box sealed by a member handing
|
|
753
|
+
* the frame on can only say that name again, at a time under the author's `sig`, and at most hold back an older page's
|
|
754
|
+
* newer name until the author's next message, as withholding those pages would. Whether the name I hold changed.
|
|
715
755
|
*/
|
|
716
756
|
private heardName;
|
|
717
757
|
private openMentions;
|
|
@@ -730,7 +770,8 @@ export declare class GroupSession {
|
|
|
730
770
|
private receiveCommit;
|
|
731
771
|
/**
|
|
732
772
|
* Whether a frame of `author` under `epoch` is taken from another member, kept and handed on: while its author is in
|
|
733
|
-
* the roster, or when it left (its removal marked `left`, and it is not back in) and the frame is from before that
|
|
773
|
+
* the roster, or when it left (its removal marked `left`, and it is not back in) and the frame is from before that,
|
|
774
|
+
* and from after any removal of it before that was not a leave: let back in, it is not handed on for those epochs.
|
|
734
775
|
*/
|
|
735
776
|
private handsOn;
|
|
736
777
|
/** Keeps the admin's mark on a commit that took out a member who left (`GroupCommitFrame.left`) when it holds; true when new. */
|
|
@@ -764,6 +805,7 @@ export declare class GroupSession {
|
|
|
764
805
|
private publishMeta;
|
|
765
806
|
/** My statement, to a member whose sync says it holds an older one (or none); nothing to an app that says nothing. */
|
|
766
807
|
private offerMeta;
|
|
808
|
+
/** The statements a member whose sync says it holds `theirTag` missed, oldest first, sealed under my current epoch (`groupMetaToHand`). */
|
|
767
809
|
private metaFor;
|
|
768
810
|
/**
|
|
769
811
|
* A metadata statement: kept when it is newer than mine, its commit is on my chain, its signer was
|
|
@@ -85,6 +85,12 @@ export interface CarriedHooks {
|
|
|
85
85
|
direct?(payload: Uint8Array): boolean;
|
|
86
86
|
/** `CARRIED_DEFER_MS`, for tests. */
|
|
87
87
|
deferMs?: number;
|
|
88
|
+
/**
|
|
89
|
+
* The date of the last packet an earlier transport of this edge signed (`lastDated`), before the edge started again:
|
|
90
|
+
* mine are dated past it. Dated by the clock alone, the first packet of an edge started again in the same millisecond
|
|
91
|
+
* (its WebRTC gave up, `edgeWithoutRtc`) was no newer than the last one, and a relay refused it (409).
|
|
92
|
+
*/
|
|
93
|
+
after?: bigint;
|
|
88
94
|
}
|
|
89
95
|
/**
|
|
90
96
|
* The Pkarr transport of one edge, with members carrying its packets beside the relays. Publishes under the edge's own
|
|
@@ -129,8 +135,13 @@ export declare class CarriedTransport implements PkarrTransport {
|
|
|
129
135
|
relays: string[];
|
|
130
136
|
};
|
|
131
137
|
publish(identity: Identity, records: GhostRecord[], options?: PkarrRequestOptions): Promise<void>;
|
|
132
|
-
/**
|
|
138
|
+
/**
|
|
139
|
+
* My next packet for this edge, signed and dated: each newer than the last, as the relays' copy keeps them, and past
|
|
140
|
+
* `after` (what a relay that refused one holds).
|
|
141
|
+
*/
|
|
133
142
|
private stamp;
|
|
143
|
+
/** The date of the last packet this transport signed (0 for none): an edge started again dates its own past it. */
|
|
144
|
+
lastDated(): bigint;
|
|
134
145
|
/**
|
|
135
146
|
* The relays get the very packet members carried or the edge itself handed over, byte for byte, where the transport
|
|
136
147
|
* can put a payload signed here: a copy dated again by the relays' transport was a packet the member had not seen,
|
|
@@ -14,6 +14,9 @@ export * from "./deviceLink.js";
|
|
|
14
14
|
export * from "./relayBreaker.js";
|
|
15
15
|
export * from "./invite.js";
|
|
16
16
|
export * from "./deviceInvite.js";
|
|
17
|
+
export * from "./contactLink.js";
|
|
18
|
+
export * from "./contactRecords.js";
|
|
19
|
+
export * from "./contactInbox.js";
|
|
17
20
|
export * from "./enroll.js";
|
|
18
21
|
export * from "./setUpdate.js";
|
|
19
22
|
export * from "./handoff.js";
|
|
@@ -98,3 +101,7 @@ export * from "./appStatements.js";
|
|
|
98
101
|
export * from "./appBundle.js";
|
|
99
102
|
export * from "./appStore.js";
|
|
100
103
|
export * from "./appUpdates.js";
|
|
104
|
+
export * from "./x401.js";
|
|
105
|
+
export * from "./x401Credential.js";
|
|
106
|
+
export * from "./x401Presentation.js";
|
|
107
|
+
export * from "./x401Request.js";
|
|
@@ -74,8 +74,21 @@ export declare const AWAITING_PEER_MS: number;
|
|
|
74
74
|
* to invites nobody may ever open, and a join on one was noticed 90 s later (bug hunt 1013-1642, 2026-10-13).
|
|
75
75
|
*/
|
|
76
76
|
export declare const UNUSED_INVITE_WAIT_MAX_MS: number;
|
|
77
|
-
/**
|
|
78
|
-
|
|
77
|
+
/**
|
|
78
|
+
* The reads a minute the unused invites of an app (their keys and their mailboxes) take between them, half the relays'
|
|
79
|
+
* background share: the slower reads stretch only as far as their count needs. Slowed whatever the count, a single
|
|
80
|
+
* invite opened 20 minutes later was noticed 136 s after the join, where the background pace takes 30 s at most (bug
|
|
81
|
+
* hunt 1014-0136, 2026-10-14).
|
|
82
|
+
*/
|
|
83
|
+
export declare const UNUSED_INVITE_READS_PER_MINUTE = 10;
|
|
84
|
+
/** Counts `reader` (an invite's key or mailbox) among the unused ones read over `transport` while `unused`, or no longer: how many there are. */
|
|
85
|
+
export declare function countUnusedInvite(transport: PkarrTransport, reader: object, unused: boolean): number;
|
|
86
|
+
/**
|
|
87
|
+
* The wait between reads of an unused invite of age `age`, one of `readers` read over the same relays: a fifth of its
|
|
88
|
+
* age, up to `UNUSED_INVITE_WAIT_MAX_MS`, but no longer than their count needs (`UNUSED_INVITE_READS_PER_MINUTE`), and
|
|
89
|
+
* never shorter than the pace's `interval`.
|
|
90
|
+
*/
|
|
91
|
+
export declare function unusedInviteWait(age: number, interval: number, readers: number): number;
|
|
79
92
|
/**
|
|
80
93
|
* A group link's peer whose packet advertises and carries no `_tr` on every read for this long publishes none: what it
|
|
81
94
|
* said before is forgotten (WISP 902 § Transports). Not at the first such packet: an app with no WebRTC (a Linux
|
|
@@ -170,6 +183,11 @@ export interface LinkSessionOptions {
|
|
|
170
183
|
* `FIRST_PUBLISH_MAX_MS`.
|
|
171
184
|
*/
|
|
172
185
|
firstPublish?: "at-start" | "after-first-poll";
|
|
186
|
+
/**
|
|
187
|
+
* Back after a restart with the contact live when this app last ran (`GhostLinkOptions.resume`): its reads say so
|
|
188
|
+
* (`PkarrRequestOptions.resume`) until one is answered.
|
|
189
|
+
*/
|
|
190
|
+
resumed?: boolean;
|
|
173
191
|
/**
|
|
174
192
|
* When the chat was made, for a saved one: the wait for a peer never seen (`AWAITING_PEER_MS`) counts from then, not
|
|
175
193
|
* from this start. Counted from each start of the app, every saved chat whose contact had no packet at the relays
|
|
@@ -248,6 +266,8 @@ export declare class LinkSession {
|
|
|
248
266
|
private readonly firstPublish;
|
|
249
267
|
private firstPublishTimer;
|
|
250
268
|
private firstPollDone;
|
|
269
|
+
/** Back after a restart, and no read of the contact answered yet in this run (`LinkSessionOptions.resumed`). */
|
|
270
|
+
private resumeReads;
|
|
251
271
|
/** When this side last published (0: never). */
|
|
252
272
|
lastPublishedAt: number;
|
|
253
273
|
/** A publish is in flight, or finished this recently: another packet now would only queue behind it at the relays. */
|
|
@@ -34,6 +34,27 @@ export type MiniAppPeerEvent = {
|
|
|
34
34
|
} | {
|
|
35
35
|
open: false;
|
|
36
36
|
};
|
|
37
|
+
/**
|
|
38
|
+
* A file the person picked for the app (WISP 1200 · Linked files): the client keeps a link to it, never a copy, and the
|
|
39
|
+
* app reads it by `id`, which the client chose. `path` is relative to what was picked, the picked folder's name first,
|
|
40
|
+
* never where it is on the device.
|
|
41
|
+
*/
|
|
42
|
+
export interface MiniAppLinkedFile {
|
|
43
|
+
/** 22 base64url characters. */
|
|
44
|
+
id: string;
|
|
45
|
+
path: string;
|
|
46
|
+
/** Bytes, and when it last changed (ms), as when it was picked. */
|
|
47
|
+
size: number;
|
|
48
|
+
modified: number;
|
|
49
|
+
/** Whether the client can read it now: false after a restart where the browser must be asked again, or before. */
|
|
50
|
+
available: boolean;
|
|
51
|
+
}
|
|
52
|
+
/** `ghostly.files.pick`: a folder (with everything under it) or files, of these extensions only when `accept` names some. */
|
|
53
|
+
export interface MiniAppPickOptions {
|
|
54
|
+
folder?: boolean;
|
|
55
|
+
/** Extensions without the dot, lower case, at most `MINI_APP_LIMITS.filesAccept`. */
|
|
56
|
+
accept?: string[];
|
|
57
|
+
}
|
|
37
58
|
/** `window.ghostly` inside the sandbox. */
|
|
38
59
|
export interface MiniAppApi {
|
|
39
60
|
context(): Promise<MiniAppContext>;
|
|
@@ -54,11 +75,28 @@ export interface MiniAppApi {
|
|
|
54
75
|
on(event: "message", listener: (data: MiniAppJson) => void): () => void;
|
|
55
76
|
on(event: "peer", listener: (peer: MiniAppPeerEvent) => void): () => void;
|
|
56
77
|
};
|
|
78
|
+
/**
|
|
79
|
+
* Files the person picks (the `files` permission): absent in a client that has none, so an app tests for it. The
|
|
80
|
+
* client asks the person and shows its own picker; the app reads only what was picked, by id.
|
|
81
|
+
*/
|
|
82
|
+
files?: {
|
|
83
|
+
/** The entries picked now; refused with `cancelled` when the person picks nothing. */
|
|
84
|
+
pick(options?: MiniAppPickOptions): Promise<MiniAppLinkedFile[]>;
|
|
85
|
+
/** Every entry this app keeps. */
|
|
86
|
+
list(): Promise<MiniAppLinkedFile[]>;
|
|
87
|
+
/** At most `MINI_APP_LIMITS.filesReadBytes` from `offset`; fewer at the end of the file. */
|
|
88
|
+
read(id: string, range: {
|
|
89
|
+
offset: number;
|
|
90
|
+
length: number;
|
|
91
|
+
}): Promise<ArrayBuffer>;
|
|
92
|
+
/** Drops one link, or every link with "all". The file itself is never touched. */
|
|
93
|
+
forget(id: string): Promise<void>;
|
|
94
|
+
};
|
|
57
95
|
/** Ends the app. */
|
|
58
96
|
close(): Promise<void>;
|
|
59
97
|
}
|
|
60
98
|
/** The message types on the port (web, extension) or through `app_broker` (Desktop). */
|
|
61
|
-
export type MiniAppRequestType = "context" | "file" | "storage.get" | "storage.set" | "storage.delete" | "storage.keys" | "chat.send" | "close";
|
|
99
|
+
export type MiniAppRequestType = "context" | "file" | "storage.get" | "storage.set" | "storage.delete" | "storage.keys" | "chat.send" | "files.pick" | "files.list" | "files.read" | "files.forget" | "close";
|
|
62
100
|
/** A request from the app: `{id, type, args}`. The broker refuses an unknown `type`. */
|
|
63
101
|
export interface MiniAppRequest {
|
|
64
102
|
id: number;
|
|
@@ -73,12 +111,17 @@ export interface MiniAppRequest {
|
|
|
73
111
|
*
|
|
74
112
|
* - `bad-key`: a storage key that is not a string of 1 to 256 bytes.
|
|
75
113
|
* - `bad-path`: a `file` path that is not a string of 1 to 1024 characters.
|
|
76
|
-
* - `bad-request`: a request that is not `{id, type, args}` with JSON arguments.
|
|
114
|
+
* - `bad-request`: a request that is not `{id, type, args}` with JSON arguments, or whose arguments are not the call's.
|
|
115
|
+
* - `cancelled`: `files.pick` that the person closed without picking anything.
|
|
116
|
+
* - `changed`: `files.read` of a file whose size or date changed since it was picked: it is picked again to be read.
|
|
77
117
|
* - `failed`: anything else; the client's own words never reach the app.
|
|
78
118
|
* - `full`: a storage write would take the scope past 5 MiB (each key counts 128 bytes, its own bytes eight times and
|
|
79
119
|
* its value's), so the app can make room.
|
|
120
|
+
* - `gone`: `files.read` of a file that is no longer there, or that the client cannot read now (`available` false), or
|
|
121
|
+
* of an id it does not keep.
|
|
80
122
|
* - `no-file`: the bundle has no such file.
|
|
81
|
-
* - `not-allowed`: `chat.send` without the `chat` permission, or with the app opened alone
|
|
123
|
+
* - `not-allowed`: `chat.send` without the `chat` permission, or with the app opened alone; `files.*` without the
|
|
124
|
+
* `files` permission, or in a client that cannot keep links.
|
|
82
125
|
* - `not-open`: `chat.send` before this side's chat has the app open.
|
|
83
126
|
* - `offline`: `chat.send` while the chat's session is not live. Nothing is kept to send later.
|
|
84
127
|
* - `peer-closed`: `chat.send` while the contact has not opened the app (or its client does not offer `apps/1`).
|
|
@@ -90,7 +133,7 @@ export interface MiniAppRequest {
|
|
|
90
133
|
*
|
|
91
134
|
* A later client may add a code: treat one you do not know as `failed`.
|
|
92
135
|
*/
|
|
93
|
-
export declare const MINI_APP_ERROR_CODES: readonly ["bad-key", "bad-path", "bad-request", "failed", "full", "no-file", "not-allowed", "not-open", "offline", "peer-closed", "stopped", "too-fast", "too-large", "unknown-type"];
|
|
136
|
+
export declare const MINI_APP_ERROR_CODES: readonly ["bad-key", "bad-path", "bad-request", "cancelled", "changed", "failed", "full", "gone", "no-file", "not-allowed", "not-open", "offline", "peer-closed", "stopped", "too-fast", "too-large", "unknown-type"];
|
|
94
137
|
export type MiniAppErrorCode = typeof MINI_APP_ERROR_CODES[number];
|
|
95
138
|
/** The code of a refused `ghostly.*` call (the rejection's `Error`), or null for anything that is not one. */
|
|
96
139
|
export declare function miniAppErrorCode(error: unknown): MiniAppErrorCode | null;
|
|
@@ -130,10 +173,17 @@ export declare const MINI_APP_LIMITS: {
|
|
|
130
173
|
/** Requests per second, per app. */
|
|
131
174
|
readonly requestsPerSecond: 50;
|
|
132
175
|
/**
|
|
133
|
-
* Bytes of `file` answers per second, per app: a whole bundle's
|
|
134
|
-
* past it
|
|
176
|
+
* Bytes of `file`, `files.read` and `files.list` answers per second, per app, counted together: a whole bundle's
|
|
177
|
+
* worth. A request that starts under it is answered whole; past it the request is refused with `too-fast` until the
|
|
178
|
+
* second has gone.
|
|
135
179
|
*/
|
|
136
180
|
readonly fileBytesPerSecond: number;
|
|
181
|
+
/** One `files.read`, at most. */
|
|
182
|
+
readonly filesReadBytes: number;
|
|
183
|
+
/** The links an app keeps, at most: a pick that would pass it is refused with `too-large`. */
|
|
184
|
+
readonly filesEntries: 100000;
|
|
185
|
+
/** Extensions a `files.pick` may name in `accept`, each 1 to 16 characters of `a-z` and `0-9`. */
|
|
186
|
+
readonly filesAccept: 32;
|
|
137
187
|
/** A storage key, UTF-8. */
|
|
138
188
|
readonly storageKeyBytes: 256;
|
|
139
189
|
/** One stored JSON value, serialized. */
|
|
@@ -50,10 +50,15 @@ export declare class PairedCalls {
|
|
|
50
50
|
get on(): boolean;
|
|
51
51
|
/**
|
|
52
52
|
* This app is going away: a call it placed or answered is hung up, as its person would (its latest signal an
|
|
53
|
-
* offer, an answer, or a picture change, which only a call on sends).
|
|
54
|
-
*
|
|
53
|
+
* offer, an answer, or a picture change, which only a call on sends). `declineRinging` (the app quits: the Desktop app
|
|
54
|
+
* or a CLI daemon) also declines the contact's call still ringing here, so the caller stops ringing for nobody; a web
|
|
55
|
+
* page that goes (a reload looks the same as a close) leaves it ringing, so the reopened page rings again. Returns
|
|
56
|
+
* the hang-up to send before the goodbye, or null when no call is on. Our own call is read by its kind, not its age:
|
|
57
|
+
* a call outlasts its offer's freshness.
|
|
55
58
|
*/
|
|
56
|
-
hangUp(
|
|
59
|
+
hangUp(options?: {
|
|
60
|
+
declineRinging?: boolean;
|
|
61
|
+
}): PairedCallFrame | null;
|
|
57
62
|
/** On a new session that carries calls: the latest signal again, if it is still fresh enough to act on. */
|
|
58
63
|
pending(): PairedCallFrame | null;
|
|
59
64
|
}
|
|
@@ -1,5 +1,13 @@
|
|
|
1
1
|
import { type FrameChannel } from "./frames.js";
|
|
2
2
|
import { HttpClient, HttpHost, type HostedHttpService, type LocalFetch } from "./http.js";
|
|
3
|
+
/**
|
|
4
|
+
* What the session hears of the bodies going on its channel: each chunk written, with its frame's length, and each wait
|
|
5
|
+
* for room. An app's data in the chat keeps its own share above them, as beside a file (WISP 1200 § In a chat).
|
|
6
|
+
*/
|
|
7
|
+
export interface PairedHttpBodies {
|
|
8
|
+
wrote(bytes: number): void;
|
|
9
|
+
waiting(drained: Promise<void>): Promise<void>;
|
|
10
|
+
}
|
|
3
11
|
/**
|
|
4
12
|
* Shared services over a paired session: the same HTTP frames as the older data link, carried as
|
|
5
13
|
* `ph` application frames on the authenticated channel. Binary chunks travel base64url-encoded,
|
|
@@ -8,7 +16,7 @@ import { HttpClient, HttpHost, type HostedHttpService, type LocalFetch } from ".
|
|
|
8
16
|
export declare class PairedHttp {
|
|
9
17
|
readonly client: HttpClient;
|
|
10
18
|
readonly host: HttpHost;
|
|
11
|
-
constructor(channel: FrameChannel, getService: (id: string) => HostedHttpService | undefined, localFetch: LocalFetch);
|
|
19
|
+
constructor(channel: FrameChannel, getService: (id: string) => HostedHttpService | undefined, localFetch: LocalFetch, bodies?: PairedHttpBodies);
|
|
12
20
|
/** One `ph` frame from the peer. Anything that is not HTTP traffic is ignored. */
|
|
13
21
|
handle(frame: Record<string, unknown>): void;
|
|
14
22
|
close(): void;
|
|
@@ -93,8 +93,38 @@ export declare const DEPARTED_READS = 6;
|
|
|
93
93
|
* groups'. A private group's admin that had just let members in and seen them restart had spent its minute in 30 s;
|
|
94
94
|
* a member back then, with no other member online to carry its offer, had it read only when the minute freed: 18 to
|
|
95
95
|
* 42 s later, one round in four of the member-back runs (2026-10-03).
|
|
96
|
+
*
|
|
97
|
+
* It is also theirs whatever the chats do: while the edges' signaling has had fewer than that many requests on a relay
|
|
98
|
+
* in the last minute, neither the limit, nor the chats' own allowance past it, nor their reserve (`CHAT_RESERVE`) holds
|
|
99
|
+
* it back. Its reads leave the last of it to a write there too. A daemon with 30 chats and 5 groups, back after a
|
|
100
|
+
* restart, had its chats signal for 332 s: they kept their reserve, their allowance took what the limit left, and the
|
|
101
|
+
* edges got nothing. By then their attempts had failed and backed off, and the group members were reachable again 13
|
|
102
|
+
* to 25 min after the restart (CLI bug hunt, 2026-10-08).
|
|
103
|
+
*
|
|
104
|
+
* An edge back after a restart reads its member before it offers (`resume`), and those reads are on the floor too: as
|
|
105
|
+
* plain reads, they waited behind the chats as before, and the edges never got to signal. The same daemon had its first
|
|
106
|
+
* member back 71 to 367 s after the restart, and group texts sent in its first minutes were read 2 to 7 min late (CLI
|
|
107
|
+
* bug hunt, 2026-10-14).
|
|
96
108
|
*/
|
|
97
109
|
export declare const GROUP_SIGNALING_ALLOWANCE_SHARE: number;
|
|
110
|
+
/**
|
|
111
|
+
* A community member's way back to its group while it has no edge up (its readings of the beacon, its request in a hub's
|
|
112
|
+
* lobby: `back`) may go past everything that holds a group's request back by this fraction of a relay's minute (6 on a
|
|
113
|
+
* relay of 30, 12 on one of 60, 1 on a relay of 5), its own: not the edges' (`GROUP_SIGNALING_ALLOWANCE_SHARE`),
|
|
114
|
+
* and what it takes counts there alone, so it shortens no one else's minute or allowance. Its reads leave the last of it
|
|
115
|
+
* to a write. A web app opened with 30 chats whose contacts were online and 15 groups whose edges all offered at once:
|
|
116
|
+
* the edges' offers and reads for their members spent the groups' allowance in its first second, the chats' reserve
|
|
117
|
+
* and their offers still waiting held the rest, and its 5 communities read their beacon (who the hubs are) a minute
|
|
118
|
+
* later, or not in 3 minutes; 2 of them were not back in 6 (bug hunt, 2026-10-14). Sized for 5 communities' way back
|
|
119
|
+
* in the first minute on the default relays: a reading of each beacon, and a read and a write in a hub's lobby (a write
|
|
120
|
+
* goes to every relay). A member asks it only while it has no edge up in that community.
|
|
121
|
+
*
|
|
122
|
+
* At worst a relay then sees, in one minute, its limit, the chats' allowance past it, the edges' and this one: 46 on a
|
|
123
|
+
* relay of 30 (pkarr.pubky.org allows 50 an address, `x-ratelimit-limit`), 92 on pkarr.pubky.app's 60 (it allows 1000)
|
|
124
|
+
* and 7 on a relay of 5 (relay.pkarr.org and pkarr.miguelmedeiros.dev allow 10). A share raised past those limits gets
|
|
125
|
+
* 429s (docs/TRANSPORTS.md, "The default list").
|
|
126
|
+
*/
|
|
127
|
+
export declare const WAY_BACK_SHARE: number;
|
|
98
128
|
/** Past the limit, a group's reads within its allowance go no more often than this on a relay. */
|
|
99
129
|
export declare const GROUP_OVER_PACE_MS = 5000;
|
|
100
130
|
/**
|
|
@@ -116,6 +146,16 @@ export declare const GROUP_BURST_ONE_LINK = 8;
|
|
|
116
146
|
* 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).
|
|
117
147
|
*/
|
|
118
148
|
export declare const WATCH_SHARE: number;
|
|
149
|
+
/**
|
|
150
|
+
* 1:1 chats' reads of contacts that went away from a live session and have not shown themselves back (`watch`) take at
|
|
151
|
+
* most this share of a relay's requests the same way, on their own (a chat never waits behind the edges that watch the
|
|
152
|
+
* same contact): 3 in any 10 s on a relay of 30, more than one contact's fast poll asks for. The key read longest ago
|
|
153
|
+
* goes first. Not the few reads of a contact that just went away past the limit (`DEPARTED_READS`). Ten contacts that
|
|
154
|
+
* left a CLI daemon at once were read every 2 s each: those reads spent both relays' minute in the 10 s after their
|
|
155
|
+
* goodbyes, when none could be back yet, then the daemon read nobody, nor answered anyone, for 45 s, and the chats with
|
|
156
|
+
* no HyperDHT listener at the daemon were live again 42 to 51 s after their contacts were back (CLI bug hunt, 2026-10-14).
|
|
157
|
+
*/
|
|
158
|
+
export declare const CHAT_WATCH_SHARE: number;
|
|
119
159
|
/**
|
|
120
160
|
* Once a group's read found a relay's minute full, the groups' reads there are spread over the minute for a minute
|
|
121
161
|
* (`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
|
|
@@ -229,13 +269,20 @@ export declare class RelayTransport implements PkarrTransport {
|
|
|
229
269
|
private readonly spentGroupUrgent;
|
|
230
270
|
/** Watch reads on each relay in the last `GROUP_RATION_WINDOW_MS` (`WATCH_SHARE`). */
|
|
231
271
|
private readonly spentWatch;
|
|
272
|
+
/** 1:1 chats' watch reads on each relay in the last `GROUP_RATION_WINDOW_MS` (`CHAT_WATCH_SHARE`). */
|
|
273
|
+
private readonly spentChatWatch;
|
|
232
274
|
/** Groups' reads past the limit on each relay in the last `GROUP_OVER_PACE_MS` (`GROUP_SIGNALING_ALLOWANCE_SHARE`). */
|
|
233
275
|
private readonly spentGroupOver;
|
|
276
|
+
/** Group edges' signaling requests on each relay in the last minute: their floor (`GROUP_SIGNALING_ALLOWANCE_SHARE`). */
|
|
277
|
+
private readonly spentGroupSignal;
|
|
278
|
+
/** Community members' ways back on each relay in the last minute: their allowance (`WAY_BACK_SHARE`). */
|
|
279
|
+
private readonly spentWayBack;
|
|
234
280
|
/** Per contact, its departed reads past the limit in the last minute, every relay together (`DEPARTED_READS`). */
|
|
235
281
|
private readonly departedOver;
|
|
236
282
|
/**
|
|
237
283
|
* Per key a group reads (not in the background), when a read of it last went out and when it last asked: whose turn
|
|
238
|
-
* it is under the watch share (`WATCH_SHARE`) and while the groups' reads are rationed (`GROUP_RATION_WINDOW_MS`).
|
|
284
|
+
* it is under the watch share (`WATCH_SHARE`) and while the groups' reads are rationed (`GROUP_RATION_WINDOW_MS`). And
|
|
285
|
+
* per key a chat watches, whose turn it is under theirs (`CHAT_WATCH_SHARE`).
|
|
239
286
|
*/
|
|
240
287
|
private readonly readTurns;
|
|
241
288
|
/** Per key read in turn (`isTurnRead`), when a read of it last went out and when it last asked (`READ_TURN_MS`). */
|
|
@@ -342,6 +389,15 @@ export declare class RelayTransport implements PkarrTransport {
|
|
|
342
389
|
* (`signedAt`) and is not checked again. `conflict`: as `publishDated` gives it.
|
|
343
390
|
*/
|
|
344
391
|
publishPayload(pubKeyZ32: string, payload: Uint8Array, options?: PkarrRequestOptions, conflict?: (relay: string) => void): Promise<void>;
|
|
392
|
+
/**
|
|
393
|
+
* A payload signed in this process (a group edge's offer or answer, `CarriedTransport`) put on every relay, past what
|
|
394
|
+
* a relay that answers 409 holds: that one is read, and the records go again at once, signed by `options.redate` dated
|
|
395
|
+
* just past it, `left` times at most. A packet put here is the key's latest too: a publish dated here next
|
|
396
|
+
* (`nextTimestamp`, the goodbye after the edge stops) goes past it. Before, the 409 failed the publish (or, when another
|
|
397
|
+
* relay took it, left the relay's copy in place), the link tried again 4 s on with its clock's date, refused as long as
|
|
398
|
+
* the relay's copy was later, and an edge started again in the same millisecond lost its new offer to its last one.
|
|
399
|
+
*/
|
|
400
|
+
private putRedated;
|
|
345
401
|
/**
|
|
346
402
|
* Puts the packet on every relay and settles as soon as one of them took it. A relay that is slow to
|
|
347
403
|
* answer (one that stores the packet and answers the PUT only at the timeout) must not hold a link's
|
|
@@ -397,13 +453,15 @@ export declare class RelayTransport implements PkarrTransport {
|
|
|
397
453
|
private readFrom;
|
|
398
454
|
/**
|
|
399
455
|
* A relay whose budget (this client's, or its own rate limit) held a packet back that another relay took: it gets
|
|
400
|
-
* that packet when it frees a request, as a background write
|
|
401
|
-
*
|
|
402
|
-
*
|
|
456
|
+
* that packet when it frees a request, as a background write (`who`: a group edge's offer or answer as its own, also
|
|
457
|
+
* after that relay failed it). Only the newest per key and relay; a newer packet put everywhere drops it. Without this,
|
|
458
|
+
* that relay kept the key's older packet for good, and an app that restarted and read it first found a contact's offer
|
|
459
|
+
* long answered, answered it again, and waited on it (bug hunt r7a).
|
|
403
460
|
*/
|
|
404
461
|
private catchUpLater;
|
|
405
462
|
private scheduleCatchUp;
|
|
406
463
|
private runCatchUp;
|
|
464
|
+
/** `sent`: told, once the budget took the request, whether the relay takes the packet (a 2xx). */
|
|
407
465
|
private put;
|
|
408
466
|
/**
|
|
409
467
|
* Discovery reads and writes share a bounded per-relay request budget; background requests only part of it, and
|
|
@@ -421,12 +479,14 @@ export declare class RelayTransport implements PkarrTransport {
|
|
|
421
479
|
* contact that just went away (`DEPARTED_READS`).
|
|
422
480
|
*/
|
|
423
481
|
private heldFor;
|
|
424
|
-
/**
|
|
482
|
+
/** What is left of the community members' way back allowance on this relay (`WAY_BACK_SHARE`); its reads leave a write the last of it. */
|
|
483
|
+
private wayBackLeft;
|
|
484
|
+
/** A group's read of `key`, or a chat's watch read, asks: it waits for its turn from now on, unless it is taken (`readsAhead`). */
|
|
425
485
|
private readAsked;
|
|
426
486
|
/**
|
|
427
487
|
* Keys a group reads, still asking (within `WATCH_TURN_MS`), that were read longer ago than `key`: a share keeps a
|
|
428
488
|
* request for each. With `watchLane`, only watched keys the same other limits hold: one the groups' burst holds back
|
|
429
|
-
* would keep a turn it cannot take.
|
|
489
|
+
* would keep a turn it cannot take. The chats' watched keys only in their own lane (`CHAT_WATCH_SHARE`).
|
|
430
490
|
*/
|
|
431
491
|
private readsAhead;
|
|
432
492
|
/** A read of `key` that takes turns asks: it waits for its turn from now on, unless it is taken (`turnAhead`). */
|
|
@@ -449,6 +509,11 @@ export declare class RelayTransport implements PkarrTransport {
|
|
|
449
509
|
private chatNeed;
|
|
450
510
|
/** How long groups still leave a chat its reserve on this relay (`CHAT_RESERVE`); a chat's need a minute old goes. */
|
|
451
511
|
private chatReservedFor;
|
|
512
|
+
/**
|
|
513
|
+
* How long a chat's packet another relay already took waits for this one: while chats need the relays, a copy takes
|
|
514
|
+
* none of the requests their reserve keeps (`chatReserveOf`), as a group's request does not. 0 when it goes now.
|
|
515
|
+
*/
|
|
516
|
+
private spareHeldFor;
|
|
452
517
|
/** Requests allowed to this relay a minute: this client's budget, or the relay's own share (`RELAY_REQUESTS_PER_MINUTE`). */
|
|
453
518
|
private limitOf;
|
|
454
519
|
/** What the chats that need the relays keep on this relay (`CHAT_RESERVE_PER_CHAT`), never less than `reserveOf`. */
|
|
@@ -55,11 +55,32 @@ export interface PkarrRequestOptions {
|
|
|
55
55
|
* restarts publishes its offer then. A few may go over the relay's minute (`DEPARTED_READS` in relay.ts).
|
|
56
56
|
*/
|
|
57
57
|
departed?: boolean;
|
|
58
|
+
/**
|
|
59
|
+
* A read of a contact that was live when this app last ran, made before any read of it this run was answered
|
|
60
|
+
* (`LinkSessionOptions.resumed`): the link's offer waits on it. A group edge's goes on the edges' floor
|
|
61
|
+
* (`GROUP_SIGNALING_ALLOWANCE_SHARE` in relay.ts).
|
|
62
|
+
*/
|
|
63
|
+
resume?: boolean;
|
|
64
|
+
/**
|
|
65
|
+
* A community member's way back to its group while it has no edge up there (`Communities.wayBack`): its readings of the
|
|
66
|
+
* beacon and its request in a hub's lobby. Its own small allowance past the relay's minute (`WAY_BACK_SHARE` in
|
|
67
|
+
* relay.ts), not the edges' signaling's.
|
|
68
|
+
*/
|
|
69
|
+
back?: boolean;
|
|
58
70
|
/**
|
|
59
71
|
* `publishPayload` only: the payload was signed in this process, dated so (a group edge's, `CarriedTransport`). Its
|
|
60
72
|
* signature is not checked again on the way to the relays, as `RelayTransport.putSigned`'s is not.
|
|
61
73
|
*/
|
|
62
74
|
signedAt?: bigint;
|
|
75
|
+
/**
|
|
76
|
+
* `publishPayload` only, with `signedAt`: the same records signed again, dated past `after` (what a relay that answered
|
|
77
|
+
* 409 holds under the key); null when a newer packet of the key took over. The relays' transport puts that one at
|
|
78
|
+
* once rather than leave the relay's copy in place until the next publish (`RelayTransport.publishPayload`).
|
|
79
|
+
*/
|
|
80
|
+
redate?: (after: bigint) => {
|
|
81
|
+
payload: Uint8Array;
|
|
82
|
+
signedAt: bigint;
|
|
83
|
+
} | null;
|
|
63
84
|
}
|
|
64
85
|
/**
|
|
65
86
|
* `transport` with `extra` added to every request's options: a group's edges say `group` so. The optional methods
|