@le-space/orbitdb-storage-bridge 0.20.0 → 0.21.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.
@@ -94,6 +94,11 @@ async function sha256Hex(payload) {
94
94
  * by default
95
95
  * @param {string} args.cid - what to keep
96
96
  * @param {string} [args.channel]
97
+ * @param {string} [args.ref] - Aleph's free-text `ref` on the STORE: a label the
98
+ * messages API filters by (`refs=`), so an application can keep several
99
+ * chains on one account and channel and list one of them — the increments of
100
+ * one database, say — without downloading anything. Opaque to Aleph; what it
101
+ * discloses is the caller's choice (a derived fingerprint, not an address)
97
102
  * @param {"credit" | "hold" | null} [args.payment] - `credit` by default; `null`
98
103
  * sends no `payment`, as every version up to 0.16.1 did, which Aleph books as
99
104
  * `hold`
@@ -105,10 +110,17 @@ export async function buildStoreMessage({
105
110
  owner,
106
111
  cid,
107
112
  channel = DEFAULT_ALEPH_CHANNEL,
113
+ ref,
108
114
  payment = "credit",
109
115
  now,
110
116
  hasher = sha256Hex,
111
117
  }) {
118
+ if (ref != null && (typeof ref !== "string" || !ref)) {
119
+ throw new BackendError(
120
+ "INVALID_BACKEND",
121
+ "a STORE's ref is a non-empty string, or absent",
122
+ );
123
+ }
112
124
  if (payment !== null && !STORE_PAYMENTS.includes(payment)) {
113
125
  throw new BackendError(
114
126
  "INVALID_BACKEND",
@@ -123,6 +135,7 @@ export async function buildStoreMessage({
123
135
  // "the thing to keep is an IPFS CID" — not the envelope's item_type
124
136
  item_type: "ipfs",
125
137
  item_hash: cid,
138
+ ...(ref ? { ref } : {}),
126
139
  // How that account pays. Without it Aleph books the STORE as `hold`, and an
127
140
  // account funded with credits covers nothing (see the file's header).
128
141
  ...(payment ? { payment: { type: payment } } : {}),
@@ -157,11 +170,13 @@ export const signaturePayload = (message) =>
157
170
  * `personal_sign`, or anything shaped like it. The library never sees a key.
158
171
  * @param {string} [options.apiHost]
159
172
  * @param {string} [options.channel]
173
+ * @param {string} [options.ref] - the `ref` every STORE from this pin carries
174
+ * (see {@link buildStoreMessage}); a `meta.ref` on one call wins over it
160
175
  * @param {"credit" | "hold" | null} [options.payment] - see {@link buildStoreMessage}
161
176
  * @param {(payload: string) => Promise<string>} [options.hasher]
162
177
  * @param {typeof fetch} [options.fetch]
163
178
  * @param {() => number} [options.now] - seconds
164
- * @returns {(cid: string, meta?: object) => Promise<{ itemHash: string, status: string }>}
179
+ * @returns {(cid: string, meta?: { name?: string, ref?: string }) => Promise<{ itemHash: string, status: string }>}
165
180
  * `status` is what Aleph answered: `processed`, or `pending` until it has
166
181
  * checked the signature, the authorization and the credit — follow a pending
167
182
  * one with {@link waitForMessage}.
@@ -188,12 +203,13 @@ export function createAlephPin(options = {}) {
188
203
  if (typeof doFetch !== "function")
189
204
  throw new BackendError("INVALID_BACKEND", "createAlephPin needs fetch");
190
205
 
191
- return async function pin(cid) {
206
+ return async function pin(cid, meta = {}) {
192
207
  const unsigned = await buildStoreMessage({
193
208
  sender,
194
209
  owner,
195
210
  cid,
196
211
  channel,
212
+ ref: meta?.ref ?? options.ref,
197
213
  payment,
198
214
  hasher,
199
215
  now: now?.(),
@@ -317,6 +333,7 @@ export async function waitForMessage(itemHash, options = {}) {
317
333
  * @param {string} options.owner - the paying account, EIP-55 checksummed (Aleph
318
334
  * keys accounts by that form)
319
335
  * @param {string} [options.channel] - one channel; every channel when absent
336
+ * @param {string} [options.ref] - only STOREs carrying this `ref` (`refs=`); every STORE when absent
320
337
  * @param {string} [options.apiHost]
321
338
  * @param {typeof fetch} [options.fetch]
322
339
  * @param {number} [options.pagination] - per page; default 50
@@ -326,7 +343,7 @@ export async function waitForMessage(itemHash, options = {}) {
326
343
  * the handle's `id`
327
344
  */
328
345
  export async function listAlephStores(options = {}) {
329
- const { owner, channel } = options;
346
+ const { owner, channel, ref } = options;
330
347
  const apiHost = options.apiHost || DEFAULT_ALEPH_API_HOST;
331
348
  const doFetch = options.fetch || globalThis.fetch;
332
349
  if (!owner)
@@ -334,6 +351,11 @@ export async function listAlephStores(options = {}) {
334
351
  "INVALID_BACKEND",
335
352
  "listAlephStores needs the paying account's address as `owner`",
336
353
  );
354
+ if (ref != null && (typeof ref !== "string" || !ref))
355
+ throw new BackendError(
356
+ "INVALID_BACKEND",
357
+ "listAlephStores takes `ref` as a non-empty string, or not at all",
358
+ );
337
359
  if (typeof doFetch !== "function")
338
360
  throw new BackendError("INVALID_BACKEND", "listAlephStores needs fetch");
339
361
 
@@ -341,6 +363,7 @@ export async function listAlephStores(options = {}) {
341
363
  url.searchParams.set("owners", owner);
342
364
  url.searchParams.set("msgTypes", "STORE");
343
365
  if (channel) url.searchParams.set("channels", channel);
366
+ if (ref) url.searchParams.set("refs", ref);
344
367
  url.searchParams.set("pagination", String(options.pagination ?? 50));
345
368
  url.searchParams.set("page", String(options.page ?? 1));
346
369
 
@@ -362,11 +385,16 @@ export async function listAlephStores(options = {}) {
362
385
  owner: String(m?.content?.address ?? ""),
363
386
  time: Number(m?.content?.time ?? m?.time ?? 0),
364
387
  ...(m?.channel ? { channel: m.channel } : {}),
388
+ ...(typeof m?.content?.ref === "string" && m.content.ref
389
+ ? { ref: m.content.ref }
390
+ : {}),
365
391
  ...(m?.content?.payment?.type ? { payment: m.content.payment.type } : {}),
366
392
  }))
367
393
  // Aleph answers what it was asked; keeping only this owner's costs nothing
368
394
  // and keeps a misread filter from handing back someone else's files.
369
395
  .filter((store) => store.cid && store.itemHash && same(store.owner, owner))
396
+ // A host that ignored `refs=` must not hand back the other chains.
397
+ .filter((store) => !ref || store.ref === ref)
370
398
  .sort((a, b) => b.time - a.time);
371
399
  return {
372
400
  stores,
@@ -532,6 +560,7 @@ export function createAlephForget(options = {}) {
532
560
  * @param {object} options
533
561
  * @param {string} options.owner - the account the STOREs are for
534
562
  * @param {string} options.channel - one channel; a FORGET across channels is not what anyone means
563
+ * @param {string} [options.ref] - only the STOREs carrying this `ref` (one chain of several on the account); all of the channel when absent
535
564
  * @param {ReturnType<typeof createAlephForget>} options.forget - from {@link createAlephForget}, signing for that account
536
565
  * @param {(store: { cid: string, itemHash: string, time: number }) => boolean} [options.keep]
537
566
  * @param {string} [options.reason]
@@ -549,6 +578,7 @@ export async function forgetAlephStores(options = {}) {
549
578
  const {
550
579
  owner,
551
580
  channel,
581
+ ref,
552
582
  forget,
553
583
  keep,
554
584
  reason,
@@ -580,6 +610,7 @@ export async function forgetAlephStores(options = {}) {
580
610
  const { stores, total } = await listAlephStores({
581
611
  owner,
582
612
  channel,
613
+ ...(ref ? { ref } : {}),
583
614
  apiHost,
584
615
  fetch: doFetch,
585
616
  pagination: 100,
@@ -444,7 +444,12 @@ export async function restoreFromIncrements(
444
444
  log,
445
445
  onProgress,
446
446
  });
447
- return { ...restored, sequences };
447
+ return {
448
+ ...restored,
449
+ sequences,
450
+ gaps: merged.gaps,
451
+ duplicates: merged.duplicates,
452
+ };
448
453
  }
449
454
 
450
455
  /**
@@ -465,7 +470,10 @@ export async function restoreFromIncrements(
465
470
  * where the application's own (non-dag-cbor) blocks go, e.g. `orbitdb.ipfs.blockstore`;
466
471
  * without it they are counted in `skippedRaw` and left out
467
472
  * @param {boolean} [params.allowGaps=false]
468
- * @returns {Promise<{ joined: number, heads: number, blocks: number, skippedRaw?: number }>}
473
+ * @returns {Promise<{ joined: number, heads: number, blocks: number, gaps: number[], duplicates: number[], skippedRaw?: number }>}
474
+ * `gaps`: sequence numbers missing from the chain; `duplicates`: sequence
475
+ * numbers carried by more than one increment (two devices numbering on
476
+ * their own) — both empty unless the join was told `allowGaps`
469
477
  */
470
478
  export async function joinIncrements(
471
479
  database,
@@ -508,6 +516,9 @@ export async function joinIncrements(
508
516
  joined,
509
517
  heads: (described.heads ?? []).length,
510
518
  blocks: blocks.size,
519
+ // What the chain looked like, for a caller that joined it with allowGaps.
520
+ gaps: merged.gaps,
521
+ duplicates: merged.duplicates,
511
522
  ...(skippedRaw ? { skippedRaw } : {}),
512
523
  };
513
524
  }
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@le-space/orbitdb-storage-bridge",
3
- "version": "0.20.0",
3
+ "version": "0.21.0",
4
4
  "description": "Back up, restore and replicate OrbitDB databases through pluggable storage backends, with hash and identity preservation",
5
5
  "main": "lib/orbitdb-storacha-bridge.js",
6
6
  "svelte": "dist/components/",