From 9858cb2bd888093f7c7e3a9129bc118f975dc1ee Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Viktor=20Levente=20T=C3=B3th?= Date: Mon, 21 Aug 2023 18:04:31 +0200 Subject: [PATCH] docs: fix --- README.md | 56 +++++++++------------ src/sequential-feed.ts | 18 +++---- src/streaming.ts | 108 ----------------------------------------- 3 files changed, 32 insertions(+), 150 deletions(-) delete mode 100644 src/streaming.ts diff --git a/README.md b/README.md index 654dbcb..598d903 100644 --- a/README.md +++ b/README.md @@ -24,8 +24,8 @@ Creates a new Feed reader | Name | Type | Description | | ---- | ---- | ----------- | -| `topic` | `Topic | Uint8Array | string` | The feeds topic | -| `owner` | `EthAddress | Uint8Array | string` | Address of signer | +| `topic` | `Topic \| Uint8Array \| string` | The feeds topic | +| `owner` | `EthAddress \| Uint8Array \| string` | Address of signer | | `options` | `any ` | Options | ### Returns @@ -83,13 +83,13 @@ A FeedChunk object ## getUpdate -Gets a chunk update from a index +Gets the chunk update the given index ### Arguments | Name | Type | Description | | ---- | ---- | ----------- | -| `index` | `Index ` | Options | +| `index` | `Index` | Options | ### Returns @@ -110,7 +110,7 @@ Gets a set of chunks ### Returns -A FeedChunk object +A FeedChunk[] array ## Feed Writer @@ -192,6 +192,14 @@ A Reference object ## Streaming feeds +### Arguments + +| Name | Type | Description | +| ---- | ---- | ----------- | +| `bee` | `Bee` | Bee instance | +| `initialTime` | `number ` | initial time of streaming feed | +| `updatePeriod` | `number ` | feed update frequency | + ## Feed Reader ## makeFeedR @@ -222,7 +230,9 @@ const myIdentity = { address: '8d3766440f0d7b949a5e32995d09619a7f86e632' as HexString, } const topic = '0000000000000000000000000000000000000000000000000000000000000000' as Topic -const streamingFeed = new StreamingFeed(new Bee('http://localhost:1633')) +const initialTime = Date.now() +const period = 5000 // ms +const streamingFeed = new StreamingFeed(new Bee('http://localhost:1633'), initialTime, period) // Feed Reader const emptyTopic = '1200000000000000000000000000000000000000000000000000000000000001' as Topic @@ -238,8 +248,6 @@ Gets an index from an arbitrary time | Name | Type | Description | | ---- | ---- | ----------- | | `lookupTime` | `number ` | Time position to lookup | -| `initialTime` | `number ` | feed chunk timestamp for index at 0 | -| `updatePeriod` | `number ` | feed update frequency | ### Returns @@ -254,8 +262,6 @@ Gets a chunk update from an arbitrary time, if lookup time is empty, it will ret | Name | Type | Description | | ---- | ---- | ----------- | -| `initialTime` | `number ` | feed chunk timestamp for index at 0 | -| `updatePeriod` | `number ` | feed update frequency | | `lookupTime` | `number ` | Time position to lookup (optional) | @@ -268,17 +274,10 @@ A StreamingFeedChunk object Gets a set of chunks from an arbitray time -### Arguments - -| Name | Type | Description | -| ---- | ---- | ----------- | -| `initialTime` | `number ` | feed chunk timestamp for index at 0 | -| `updatePeriod` | `number ` | feed update frequency | - ### Returns -A StreamingFeedChunk object +A StreamingFeedChunk array ## Feed Writer @@ -314,7 +313,9 @@ const myIdentity = { } const signer = makePrivateKeySigner(hexToBytes(myIdentity.privateKey) as Bytes<32>) const topic = '0000000000000000000000000000000000000000000000000000000000000000' as Topic -const streamingFeed = new StreamingFeed(new Bee('http://localhost:1633')) +const initialTime = Date.now() +const period = 5000 // ms +const streamingFeed = new StreamingFeed(new Bee('http://localhost:1633'), initialTime, period) // Feed Reader/Writer const feedRw = streamingFeed.makeFeedRW(topic, signer) @@ -330,11 +331,6 @@ Appends a new chunk to a feed, if the lookup time is empty, it will be added to | ---- | ---- | ----------- | | `postageBatchId` | `string | BatchId ` | postage batch id | | `reference` | `Reference` | reference | -| `initialTime` | `number ` | feed chunk timestamp for index at 0 | -| `updatePeriod` | `number ` | feed update frequency | -| `lookupTime` | `number ` | Time position to lookup (optional) | - - ### Returns @@ -350,15 +346,9 @@ Sets a chunk to a feed at an index number | Name | Type | Description | | ---- | ---- | ----------- | | `index` | `number` | index | -| `postageBatchId` | `string | BatchId ` | postage batch id | -| `reference` | `Reference` | reference | -| `initialTime` | `number ` | feed chunk timestamp for index at 0 | -| `updatePeriod` | `number ` | feed update frequency | -| `lookupTime` | `number ` | Time position to lookup (optional) | - - +| `postageBatchId` | `string \| BatchId` | postage batch id | +| `reference` | `Reference` | wrapped chunk reference | ### Returns -A Reference object - +A Reference of the Feed chunk diff --git a/src/sequential-feed.ts b/src/sequential-feed.ts index 7e2a682..38b6eed 100644 --- a/src/sequential-feed.ts +++ b/src/sequential-feed.ts @@ -71,7 +71,7 @@ export class SequentialFeed implements SwarmFeed { /** * Downloads a chunk by index number - * @param index index number + * @param index index number of the feed chunk * @returns A feed chunk */ const getUpdate = async (index: number): Promise => { @@ -81,9 +81,9 @@ export class SequentialFeed implements SwarmFeed { } /** - * Download all chunk by indices - * @param indices an array of index numbers - * @returns An array of chunks + * Download all chunks by indices + * @param indices an array of indices + * @returns An array of feed chunks */ const getUpdates = async (indices: number[]): Promise => { const promises: Promise[] = [] @@ -126,8 +126,8 @@ export class SequentialFeed implements SwarmFeed { * Sets the upload chunk to update * @param index the chunk index to update * @param postageBatchId swarm postage batch id - * @param reference chunk reference - * @returns a chunk reference + * @param reference wrapped chunk reference + * @returns a SOC reference */ const setUpdate = async ( index: number, @@ -146,8 +146,8 @@ export class SequentialFeed implements SwarmFeed { /** * Sets the next upload chunk * @param postageBatchId swarm postage batch id - * @param reference chunk reference - * @returns a chunk reference + * @param reference wrapped chunk reference + * @returns a SOC reference */ const setLastUpdate = async (postageBatchId: string | BatchId, reference: Reference): Promise => { let index: number @@ -172,7 +172,7 @@ export class SequentialFeed implements SwarmFeed { * Get Single Owner Chunk identifier * @param topic a swarm topic, bytes 32 length * @param index the chunk index - * @returns a bytes 32 + * @returns 32 bytes */ public getIdentifier(topic: Utils.Bytes.Bytes<32>, index: number): Utils.Bytes.Bytes<32> { const indexBytes = writeUint64BigEndian(index) diff --git a/src/streaming.ts b/src/streaming.ts deleted file mode 100644 index cf9594c..0000000 --- a/src/streaming.ts +++ /dev/null @@ -1,108 +0,0 @@ -import { BatchId, Bee, Reference, Signer, Topic } from '@ethersphere/bee-js' -import type { SingleOwnerChunk } from '@ethersphere/bee-js/dist/src/chunk/soc' -import type { ChunkReference } from '@ethersphere/bee-js/dist/src/feed' -import type { EthAddress } from '@ethersphere/bee-js/dist/src/utils/eth' -import { SwarmFeedHandler } from './feed' -import { Bytes, readUint64BigEndian, serializeBytes, writeUint64BigEndian } from './utils' - -export interface StreamingFeedChunk extends SingleOwnerChunk { - index: number - reference: ChunkReference - timestamp: number - updatePeriod: number -} - -export type FaultTolerantStreamType = 'fault-tolerant-stream' - -/** Interface for feed type classes */ -export interface IStreamingFeed { - /** Feed type identifier */ - readonly type: FaultTolerantStreamType - /** initialised BeeJS instance */ - readonly bee: Bee - /** get Feed interface with read operations */ - makeFeedR( - topic: Topic | Uint8Array | string, - owner: EthAddress | Uint8Array | string, - ...options: any[] - ): SwarmStreamingFeedR - /** get Feed interface with write and read operations */ - makeFeedRW( - topic: Topic | Uint8Array | string, - signer: Signer | Uint8Array | string, - options?: any, - ): SwarmStreamingFeedRW - /** Get Single Owner Chunk identifier */ - getIdentifier(topic: Bytes<32>, index: Index): Bytes<32> -} - -/** Swarm Feed Read operations */ -export interface SwarmStreamingFeedR extends SwarmFeedHandler { - getIndexForArbitraryTime(lookupTime: number, initialTime?: number, updatePeriod?: number): number - getUpdate(initialTime: number, updatePeriod: number, lookupTime?: number): Promise - getUpdates(initialTime: number, updatePeriod: number): Promise - findLastUpdate(initialTime: number, updatePeriod: number): Promise - getLastIndex(initialTime: number, updatePeriod: number): Promise -} - -/** Swarm Feed Read and Write operations */ -export interface SwarmStreamingFeedRW extends SwarmStreamingFeedR { - setLastUpdate( - postageBatchId: string | BatchId, - reference: Reference, - initialTime: number, - updatePeriod: number, - lookupTime?: number, - ): Promise - setUpdate( - index: number, - postageBatchId: string | BatchId, - reference: Reference, - initialTime: number, - updatePeriod: number, - lookupTime?: number, - ): Promise -} - -export function extractDataFromSocPayload(payload: Uint8Array): StreamingFeedChunk { - const index = readUint64BigEndian(payload.slice(0, 8) as Bytes<8>) - const updatePeriod = readUint64BigEndian(payload.slice(8, 16) as Bytes<8>) - const timestamp = readUint64BigEndian(payload.slice(16, 24) as Bytes<8>) - const p = payload.slice(24) // 32 bytes - - if (p.length === 32 || p.length === 64) { - return { - timestamp, - updatePeriod, - index, - reference: p as ChunkReference, - } as any - } - - // TODO handle JSON-like metadata - throw new Error('NotImplemented: payload is longer than expected') -} - -export function mapSocToFeed(socChunk: SingleOwnerChunk): StreamingFeedChunk { - const { reference, timestamp, updatePeriod, index } = extractDataFromSocPayload(socChunk.payload()) - - return { - ...socChunk, - index, - timestamp, - updatePeriod, - reference: reference, - } -} - -export function assembleSocPayload( - reference: ChunkReference, - options: { at: number; updatePeriod: number; index: number }, -): Uint8Array { - const at = options.at ?? Date.now() / 1000.0 - const timestamp = writeUint64BigEndian(at) - const updatePeriod = writeUint64BigEndian(options.updatePeriod) - const chunkIndex = writeUint64BigEndian(options.index) - - return serializeBytes(chunkIndex, updatePeriod, timestamp, reference) -}