@ethersphere/bee-js 13.0.1-upcoming.gd3bc2f5 → 13.1.0

package/dist/mjs/bee.js

@@ -1,5 +1,5 @@
-import { Objects } from 'cafe-utility';
 import { BatchId, PrivateKey, Reference, makeContentAddressedChunk, unmarshalContentAddressedChunk } from '@ethersphere/core-sdk';
+import { Objects } from 'cafe-utility';
 import { postEnvelope } from "./api/envelope.js";
 import { rchash } from "./api/rchash.js";
 import { makeSOCAddress, makeSingleOwnerChunk, unmarshalSingleOwnerChunk } from "./chunk/soc.js";
@@ -15,6 +15,7 @@ import { File as FileNamespace } from "./modules/file.js";
 import { Grantee } from "./modules/grantee.js";
 import { Messaging } from "./modules/messaging.js";
 import { Pin } from "./modules/pin.js";
+import { RollingFeed } from "./modules/rolling-feed.js";
 import { Settlement } from "./modules/settlement.js";
 import { Soc } from "./modules/soc.js";
 import { Stake } from "./modules/stake.js";
@@ -87,6 +88,7 @@ export class Bee {
     this.chunk = new ChunkNamespace(context);
     this.file = new FileNamespace(context);
     this.collection = new Collection(context);
+    this.rollingFeed = new RollingFeed(context);
   }
   /**
    * Creates a Content Addressed Chunk.

package/dist/mjs/index.js

@@ -1,7 +1,7 @@
 import { Bee } from "./bee.js";
 export { BatchId, Bytes, ChunkBuilder, ChunkSplitter, EthAddress, FeedIndex, Identifier, PeerAddress, PrivateKey, PublicKey, Reference, Signature, Span, Stamper, Topic, TransactionId } from '@ethersphere/core-sdk';
 export { MantarayNode } from "./manifest/manifest.js";
-export { SUPPORTED_BEE_VERSION, SUPPORTED_BEE_VERSION_EXACT } from "./version.js";
+export { RollingFeedReader, RollingFeedWriter } from "./modules/rolling-feed.js";
 export * from "./types/index.js";
 export * from "./utils/constants.js";
 export { Duration } from "./utils/duration.js";
@@ -9,4 +9,5 @@ export * from "./utils/error.js";
 export * as Utils from "./utils/expose.js";
 export { Size } from "./utils/size.js";
 export * from "./utils/tokens.js";
+export { SUPPORTED_BEE_VERSION, SUPPORTED_BEE_VERSION_EXACT } from "./version.js";
 export { Bee };

package/dist/mjs/modules/rolling-feed.js

@@ -0,0 +1,189 @@
+import { BatchId, keccak256, numberToUint64, Reference, Topic } from '@ethersphere/core-sdk';
+import { BeeError, Bytes } from "../index.js";
+import { fetchLatestFeedUpdate, probeFeed } from "../api/feed.js";
+import { uploadSingleOwnerChunkWithWrappedChunk } from "../chunk/soc.js";
+import { downloadFeedUpdate, downloadFeedUpdateAsCAC, updateFeedWithPayload, updateFeedWithReference } from "../feed/index.js";
+import { makeFeedIdentifier } from "../feed/identifier.js";
+import { BeeResponseError } from "../utils/error.js"; // RollingFeedReader.downloadPayload/downloadReference only ever fall back one period, so
+// backfilling deeper than that serves no reader by default - see catchUp's maxBackfill param.
+const DEFAULT_MAX_BACKFILL = 1;
+function periodIndex(t, periodLength) {
+  if (periodLength <= 0) {
+    throw new BeeError('Period length must be greater than zero!');
+  }
+  return Math.floor(t / periodLength);
+}
+function topicFor(baseTopic, periodIdx) {
+  const baseTopicBytes = baseTopic.toUint8Array();
+  return new Topic(keccak256(Bytes.concat(baseTopicBytes, numberToUint64(BigInt(periodIdx), 'BE'))));
+}
+async function isPeriodPopulated(requestOptions, owner, topic) {
+  try {
+    await probeFeed(requestOptions, owner, topic);
+    return true;
+  } catch (e) {
+    if (e instanceof BeeResponseError) {
+      return false;
+    }
+    throw e;
+  }
+}
+async function fetchLatestReference(requestOptions, owner, topic) {
+  const {
+    feedIndex
+  } = await probeFeed(requestOptions, owner, topic);
+  const update = await downloadFeedUpdate(requestOptions, owner, topic, feedIndex, true);
+  return {
+    reference: new Reference(update.payload.toUint8Array()),
+    feedIndex,
+    feedIndexNext: feedIndex.next()
+  };
+}
+export class RollingFeed {
+  constructor(context) {
+    this.context = context;
+  }
+  makeWriter(baseTopic, signer, periodLength) {
+    return new RollingFeedWriter(this.context, baseTopic, signer, periodLength);
+  }
+  makeReader(baseTopic, owner, periodLength) {
+    return new RollingFeedReader(this.context, baseTopic, owner, periodLength);
+  }
+}
+export class RollingFeedWriter {
+  constructor(context, baseTopic, signer, periodLength) {
+    this.context = context;
+    this.baseTopic = baseTopic;
+    this.signer = signer;
+    this.periodLength = periodLength;
+  }
+  async uploadPayload(postageBatchId, payload, options) {
+    const requestOptions = this.context.getRequestOptionsForCall();
+    const stamp = new BatchId(postageBatchId);
+    const {
+      currentTopic,
+      nextTopic,
+      mirrorOptions
+    } = this.currentAndNextTopics(options);
+    const [result] = await Promise.all([updateFeedWithPayload(requestOptions, this.signer, currentTopic, payload, stamp, options), updateFeedWithPayload(requestOptions, this.signer, nextTopic, payload, stamp, mirrorOptions)]);
+    return result;
+  }
+  async uploadReference(postageBatchId, reference, options) {
+    const requestOptions = this.context.getRequestOptionsForCall();
+    const stamp = new BatchId(postageBatchId);
+    const {
+      currentTopic,
+      nextTopic,
+      mirrorOptions
+    } = this.currentAndNextTopics(options);
+    const [result] = await Promise.all([updateFeedWithReference(requestOptions, this.signer, currentTopic, reference, stamp, options), updateFeedWithReference(requestOptions, this.signer, nextTopic, reference, stamp, mirrorOptions)]);
+    return result;
+  }
+  /**
+   * True unless the period right before `periodIdx` (default: current) never got mirrored
+   * forward into it, i.e. the writer went silent for at least one whole period.
+   */
+  async isCaughtUp(periodIdx) {
+    const requestOptions = this.context.getRequestOptionsForCall();
+    const targetPeriod = periodIdx ?? periodIndex(Date.now() / 1000, this.periodLength);
+    const owner = this.signer.publicKey().address();
+    return isPeriodPopulated(requestOptions, owner, topicFor(this.baseTopic, targetPeriod));
+  }
+  /**
+   * Backfills up to `maxBackfill` periods strictly between the last populated one and
+   * `periodIdx` (default: current) with that period's last known payload/reference. Never
+   * writes `periodIdx` itself - keeping it populated during silence is the caller's job (a
+   * periodic `uploadPayload`/`uploadReference` heartbeat), not catchUp's. A conditional
+   * "write it if empty" would race that heartbeat: there's no compare-and-swap on a SOC
+   * address, so a stale write can still land after a concurrent fresh one and shadow it.
+   *
+   * `maxBackfill` bounds both the backward scan and the backfill itself, since scanning
+   * further back than you're willing to backfill only wastes round trips. Defaults to 1,
+   * matching the reader's one-period fallback - nothing deeper is ever read anyway. Throws
+   * if no populated period is found within that bound.
+   */
+  async catchUp(postageBatchId, periodIdx, maxBackfill = DEFAULT_MAX_BACKFILL) {
+    const requestOptions = this.context.getRequestOptionsForCall();
+    const stamp = new BatchId(postageBatchId);
+    const owner = this.signer.publicKey().address();
+    const targetPeriod = periodIdx ?? periodIndex(Date.now() / 1000, this.periodLength);
+    // periods before 0 can't exist (period index is derived from Unix time), so the scan
+    // must not probe them even when the lookback window would otherwise reach that far
+    const scanFloor = Math.max(0, targetPeriod - 1 - maxBackfill);
+    let lastGoodPeriod = targetPeriod - 1;
+    while (lastGoodPeriod >= scanFloor) {
+      if (await isPeriodPopulated(requestOptions, owner, topicFor(this.baseTopic, lastGoodPeriod))) {
+        break;
+      }
+      lastGoodPeriod--;
+    }
+    if (lastGoodPeriod < scanFloor) {
+      throw new BeeError(`No populated period found within ${maxBackfill} periods to catch up from!`);
+    }
+    if (lastGoodPeriod === targetPeriod - 1) {
+      return; // no gap - nothing to backfill
+    }
+    const sourceTopic = topicFor(this.baseTopic, lastGoodPeriod);
+    const {
+      feedIndex: sourceIndex
+    } = await probeFeed(requestOptions, owner, sourceTopic);
+    const sourceChunk = await downloadFeedUpdateAsCAC(requestOptions, owner, sourceTopic, sourceIndex);
+    const periodsToBackfill = Array.from({
+      length: targetPeriod - 1 - lastGoodPeriod
+    }, (_, i) => lastGoodPeriod + 1 + i);
+    await Promise.all(periodsToBackfill.map(async period => {
+      const identifier = makeFeedIdentifier(topicFor(this.baseTopic, period), 0);
+      return uploadSingleOwnerChunkWithWrappedChunk(requestOptions, this.signer, stamp, identifier, sourceChunk);
+    }));
+  }
+  currentAndNextTopics(options) {
+    const currentPeriod = periodIndex(Date.now() / 1000, this.periodLength);
+    return {
+      currentTopic: topicFor(this.baseTopic, currentPeriod),
+      nextTopic: topicFor(this.baseTopic, currentPeriod + 1),
+      mirrorOptions: {
+        ...options,
+        index: undefined
+      }
+    };
+  }
+}
+export class RollingFeedReader {
+  constructor(context, baseTopic, owner, periodLength) {
+    this.context = context;
+    this.baseTopic = baseTopic;
+    this.owner = owner;
+    this.periodLength = periodLength;
+  }
+  /**
+   * Reads the current period's feed; falls back to the previous period once if empty,
+   * to tolerate clock skew between writer and reader.
+   */
+  async downloadPayload(options) {
+    const requestOptions = this.context.getRequestOptionsForCall();
+    const currentPeriod = periodIndex(Date.now() / 1000, this.periodLength);
+    try {
+      return await fetchLatestFeedUpdate(requestOptions, this.owner, topicFor(this.baseTopic, currentPeriod), options);
+    } catch (e) {
+      if (!(e instanceof BeeResponseError)) {
+        throw e;
+      }
+      return fetchLatestFeedUpdate(requestOptions, this.owner, topicFor(this.baseTopic, currentPeriod - 1), options);
+    }
+  }
+  /**
+   * Same as `downloadPayload`, but for a reference to data uploaded elsewhere.
+   */
+  async downloadReference() {
+    const requestOptions = this.context.getRequestOptionsForCall();
+    const currentPeriod = periodIndex(Date.now() / 1000, this.periodLength);
+    try {
+      return await fetchLatestReference(requestOptions, this.owner, topicFor(this.baseTopic, currentPeriod));
+    } catch (e) {
+      if (!(e instanceof BeeResponseError)) {
+        throw e;
+      }
+      return fetchLatestReference(requestOptions, this.owner, topicFor(this.baseTopic, currentPeriod - 1));
+    }
+  }
+}

package/dist/types/bee.d.ts

@@ -12,6 +12,7 @@ import { File as FileNamespace } from './modules/file';
 import { Grantee } from './modules/grantee';
 import { Messaging } from './modules/messaging';
 import { Pin } from './modules/pin';
+import { RollingFeed } from './modules/rolling-feed';
 import { Settlement } from './modules/settlement';
 import { Soc } from './modules/soc';
 import { Stake } from './modules/stake';
@@ -152,6 +153,10 @@ export declare class Bee {
      * Collection (multi-file) operations backed by the `/bzz` endpoint.
      */
     readonly collection: Collection;
+    /**
+     * Rolling feed operations.
+     */
+    readonly rollingFeed: RollingFeed;
     /**
      * Creates a Content Addressed Chunk.
      *

package/dist/types/index.d.ts

@@ -3,7 +3,7 @@ export { BatchId, Bytes, ChunkBuilder, ChunkSplitter, EthAddress, FeedIndex, Ide
 export type { Chunk } from '@ethersphere/core-sdk';
 export type { SingleOwnerChunk } from './chunk/soc';
 export { MantarayNode } from './manifest/manifest';
-export { SUPPORTED_BEE_VERSION, SUPPORTED_BEE_VERSION_EXACT } from './version';
+export { RollingFeedReader, RollingFeedWriter } from './modules/rolling-feed';
 export * from './types';
 export * from './utils/constants';
 export { Duration } from './utils/duration';
@@ -12,6 +12,7 @@ export * as Utils from './utils/expose';
 export { Size } from './utils/size';
 export * from './utils/tokens';
 export type { UploadProgress } from './utils/upload-progress';
+export { SUPPORTED_BEE_VERSION, SUPPORTED_BEE_VERSION_EXACT } from './version';
 export { Bee };
 declare global {
     interface Window {

package/dist/types/modules/rolling-feed.d.ts

@@ -0,0 +1,56 @@
+import { BatchId, EthAddress, PrivateKey, Reference, Topic } from '@ethersphere/core-sdk';
+import { FeedPayloadResult, FeedReferenceResult, FeedUpdateOptions } from '../api/feed';
+import { FeedUploadOptions } from '../feed';
+import { UploadResult } from '../types';
+import { BeeContext } from './context';
+export declare class RollingFeed {
+    private readonly context;
+    constructor(context: BeeContext);
+    makeWriter(baseTopic: Topic, signer: PrivateKey, periodLength: number): RollingFeedWriter;
+    makeReader(baseTopic: Topic, owner: EthAddress, periodLength: number): RollingFeedReader;
+}
+export declare class RollingFeedWriter {
+    private readonly context;
+    private readonly baseTopic;
+    private readonly signer;
+    private readonly periodLength;
+    constructor(context: BeeContext, baseTopic: Topic, signer: PrivateKey, periodLength: number);
+    uploadPayload(postageBatchId: string | BatchId, payload: Uint8Array | string, options?: FeedUploadOptions): Promise<UploadResult>;
+    uploadReference(postageBatchId: string | BatchId, reference: Reference | string | Uint8Array, options?: FeedUploadOptions): Promise<UploadResult>;
+    /**
+     * True unless the period right before `periodIdx` (default: current) never got mirrored
+     * forward into it, i.e. the writer went silent for at least one whole period.
+     */
+    isCaughtUp(periodIdx?: number): Promise<boolean>;
+    /**
+     * Backfills up to `maxBackfill` periods strictly between the last populated one and
+     * `periodIdx` (default: current) with that period's last known payload/reference. Never
+     * writes `periodIdx` itself - keeping it populated during silence is the caller's job (a
+     * periodic `uploadPayload`/`uploadReference` heartbeat), not catchUp's. A conditional
+     * "write it if empty" would race that heartbeat: there's no compare-and-swap on a SOC
+     * address, so a stale write can still land after a concurrent fresh one and shadow it.
+     *
+     * `maxBackfill` bounds both the backward scan and the backfill itself, since scanning
+     * further back than you're willing to backfill only wastes round trips. Defaults to 1,
+     * matching the reader's one-period fallback - nothing deeper is ever read anyway. Throws
+     * if no populated period is found within that bound.
+     */
+    catchUp(postageBatchId: string | BatchId, periodIdx?: number, maxBackfill?: number): Promise<void>;
+    private currentAndNextTopics;
+}
+export declare class RollingFeedReader {
+    private readonly context;
+    private readonly baseTopic;
+    private readonly owner;
+    private readonly periodLength;
+    constructor(context: BeeContext, baseTopic: Topic, owner: EthAddress, periodLength: number);
+    /**
+     * Reads the current period's feed; falls back to the previous period once if empty,
+     * to tolerate clock skew between writer and reader.
+     */
+    downloadPayload(options?: Omit<FeedUpdateOptions, 'index'>): Promise<FeedPayloadResult>;
+    /**
+     * Same as `downloadPayload`, but for a reference to data uploaded elsewhere.
+     */
+    downloadReference(): Promise<FeedReferenceResult>;
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ethersphere/bee-js",
-  "version": "13.0.1-upcoming.gd3bc2f5",
+  "version": "13.1.0",
   "description": "Javascript client for Bee",
   "keywords": [
     "bee",