@cloudpss/message-stream 0.4.20

package/README.md

@@ -0,0 +1,26 @@
+# @cloudpss/message-stream
+
+Message stream client for cloudpss APIs.
+
+## Example
+
+```ts
+import { HttpClient } from '@cloudpss/http-client';
+import { MessageStreamPlugin } from '@cloudpss/message-stream/plugin';
+import type { Stream } from '@cloudpss/message-stream';
+import { interval } from 'rxjs';
+import { map, take } from 'rxjs/operators';
+
+const http = new HttpClient({
+  /* config */
+}).use(MessageStreamPlugin());
+const stream = await http.stream.create({ type: 'object', comment: 'test', durability: 0 });
+await http.stream.write(
+  stream.token,
+  stream.type,
+  interval(100)
+    .pipe(take(10))
+    .pipe(map((i) => ({ i }))),
+);
+await http.stream.freeze(stream.token);
+```

package/dist/index.d.ts

@@ -0,0 +1,77 @@
+import type { Opaque } from 'type-fest';
+/** UUID */
+type UUID = `${string}-${string}-${string}-${string}-${string}`;
+/**
+ * 标识流的读权限
+ */
+export type StreamId = Opaque<UUID, 'StreamId'>;
+/**
+ * 标识流的写权限
+ */
+export type StreamToken = Opaque<UUID, 'StreamToken'>;
+export declare const StreamType: readonly ["object", "binary"];
+/**
+ * 流中消息的类型
+ *  - 'object'，在 StreamMessage 中使用 ubjson 存储
+ *  - 'binary'，在 StreamMessage 中原样存储
+ */
+export type StreamType = (typeof StreamType)[number];
+/**
+ * 流的状态
+ */
+export type StreamState = 'inactive' | 'active' | 'frozen';
+/** 记录调用 `open` 操作的控制器，对应的 `close` 只能由相同的控制器调用 */
+export type StreamWriteHandler = Opaque<string, 'StreamWriteHandler'>;
+/**
+ * 消息流，需要使用 {@link StreamToken} 查询
+ */
+export interface Stream {
+    /** id */
+    readonly id: StreamId;
+    /** token */
+    readonly token: StreamToken;
+    /** 存储流中消息的类型 */
+    readonly type: StreamType;
+    /** 可选的注释 */
+    readonly comment: string;
+    /** 流的状态 */
+    state: StreamState;
+    /** 打开流的控制器，在 `active` 状态下此项非空 */
+    handler: StreamWriteHandler | null;
+    /** 创建时间 */
+    readonly createdAt: Date;
+    /** 最后写入时间 */
+    lastWrittenAt?: Date;
+    /** 最后读取时间 */
+    lastReadAt?: Date;
+    /** 流的持久性 */
+    readonly durability: number;
+}
+/** 消息流信息，使用 {@link StreamId} 查询 */
+export type StreamInfo = Omit<Stream, 'token' | 'handler'>;
+/** 创建流需要的数据 */
+export type StreamArgs = Pick<Stream, 'type'> & Partial<Pick<Stream, 'comment' | 'durability'>>;
+/** 消息 ID */
+export type MessageId = Opaque<UUID, 'MessageId'>;
+/** 原始消息 */
+export interface RawMessage {
+    /** 消息 ID */
+    readonly id: MessageId;
+    /** 消息创建时间 */
+    readonly timestamp: Date;
+    /** 序列化的消息体 */
+    readonly data: Uint8Array;
+}
+/** 消息数据 */
+interface MessageData extends Record<StreamType, unknown> {
+    /** 消息数据 */
+    object: unknown;
+    /** 消息数据 */
+    binary: Uint8Array;
+}
+/** 消息 */
+export interface Message<T extends StreamType = StreamType> extends Omit<RawMessage, 'data'> {
+    /** 消息数据 */
+    readonly data: MessageData[T];
+}
+export {};

package/dist/index.js

@@ -0,0 +1,2 @@
+export const StreamType = ['object', 'binary'];
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAYA,MAAM,CAAC,MAAM,UAAU,GAAG,CAAC,QAAQ,EAAE,QAAQ,CAAU,CAAC"}

package/dist/plugin.d.ts

@@ -0,0 +1,49 @@
+import type { HttpClient, HttpClientPlugin } from '@cloudpss/http-client';
+import type { Message, Stream, StreamArgs, StreamId, StreamInfo, StreamToken, StreamType } from './index.js';
+import { Observable, type ObservableInput } from 'rxjs';
+/** 消息流客户端 */
+declare class MessageStreamClient {
+    readonly client: HttpClient;
+    constructor(client: HttpClient);
+    /** 解析响应 */
+    private parse;
+    /** 创建流 */
+    create<T extends StreamType>(args: StreamArgs & {
+        type: T;
+    }): Promise<Stream & {
+        type: T;
+    }>;
+    /** 批量创建流 */
+    create<T extends StreamType>(args: ReadonlyArray<StreamArgs & {
+        type: T;
+    }>): Promise<Array<Stream & {
+        type: T;
+    }>>;
+    /** 冻结流 */
+    freeze(token: StreamToken): Promise<boolean>;
+    /** 删除流 */
+    delete(token: StreamToken): Promise<void>;
+    /** 获取流信息 */
+    info(id: StreamId): Promise<StreamInfo>;
+    /** 获取流信息 */
+    get(token: StreamToken): Promise<Stream>;
+    /** 读取消息 */
+    read<T extends StreamType>(stream: {
+        id: StreamId;
+        type: T;
+    }, options?: {
+        from?: Date;
+    }): Observable<Message<T>>;
+    /** 写入消息 */
+    write<T extends StreamType>(stream: {
+        token: StreamToken;
+        type: T;
+    }, data: ObservableInput<Message<T>['data']>): Promise<void>;
+}
+/**
+ * 添加消息流插件，使得可以通过 `client.stream` 访问消息流相关接口
+ */
+export declare function MessageStreamPlugin(): HttpClientPlugin<{
+    readonly stream: MessageStreamClient;
+}>;
+export {};

package/dist/plugin.js

@@ -0,0 +1,133 @@
+import { WebSocket, connected, disconnected } from '@cloudpss/ws';
+import { Observable, from } from 'rxjs';
+import { decode, encode } from '@cloudpss/ubjson';
+/** 消息流客户端 */
+class MessageStreamClient {
+    constructor(client) {
+        this.client = client;
+    }
+    /** 解析响应 */
+    parse(data) {
+        data.createdAt = new Date(data.createdAt);
+        data.lastReadAt = data.lastReadAt ? new Date(data.lastReadAt) : undefined;
+        data.lastWrittenAt = data.lastWrittenAt ? new Date(data.lastWrittenAt) : undefined;
+        return data;
+    }
+    /** 创建流 */
+    async create(args) {
+        if (Array.isArray(args)) {
+            const list = args;
+            if (list.length === 0)
+                return [];
+            const result = await this.client.restful('/streams/bulk', args);
+            return result.data.map((item) => this.parse(item));
+        }
+        const result = await this.client.restful('/streams', args);
+        return this.parse(result.data);
+    }
+    /** 冻结流 */
+    async freeze(token) {
+        const result = await this.client.restful(`/streams/token/${token}/freeze`, undefined, { method: 'PUT' });
+        if (result.response.status === 204)
+            return false;
+        return true;
+    }
+    /** 删除流 */
+    async delete(token) {
+        await this.client.restful(`/streams/token/${token}`, undefined, { method: 'DELETE' });
+    }
+    /** 获取流信息 */
+    async info(id) {
+        const result = await this.client.restful(`/streams/id/${id}/info`);
+        return this.parse(result.data);
+    }
+    /** 获取流信息 */
+    async get(token) {
+        const result = await this.client.restful(`/streams/token/${token}/info`);
+        return this.parse(result.data);
+    }
+    /** 读取消息 */
+    read(stream, options) {
+        const { id, type } = stream;
+        const from = options?.from && Number(options.from) ? `?from=${options.from.toISOString()}` : '';
+        const url = this.client.config.apiUrl.replace(/^http/, 'ws') + `/streams/id/${id}${from}`;
+        return new Observable((subscriber) => {
+            const ws = new WebSocket(url);
+            if (ws.binaryType === 'blob')
+                ws.binaryType = 'arraybuffer';
+            ws.addEventListener('message', (event) => {
+                if (typeof event.data === 'string' || !event.data)
+                    return;
+                const message = decode(event.data);
+                message.timestamp = new Date(message.timestamp);
+                if (type === 'object') {
+                    message.data = decode(message.data);
+                }
+                subscriber.next(message);
+            });
+            ws.addEventListener('close', (ev) => {
+                if (ev.code !== 1000) {
+                    subscriber.error(new Error(`WebSocket closed with code ${ev.code}: ${ev.reason}`));
+                }
+                else if (ev.reason) {
+                    subscriber.error(new Error(ev.reason));
+                }
+                else {
+                    subscriber.complete();
+                }
+            });
+            ws.addEventListener('error', (ev) => {
+                const error = ev.error ?? new Error(`WebSocket error`);
+                subscriber.error(error);
+            });
+            return () => {
+                if (ws.readyState === ws.OPEN)
+                    ws.close(1000);
+            };
+        });
+    }
+    /** 写入消息 */
+    async write(stream, data) {
+        const { token, type } = stream;
+        const url = this.client.config.apiUrl.replace(/^http/, 'ws') + `/streams/token/${token}`;
+        const ws = new WebSocket(url);
+        await connected(ws);
+        return new Promise((resolve, reject) => {
+            const sub = from(data).subscribe({
+                next: (data) => {
+                    const bin = type === 'binary' ? data : encode(data);
+                    if (!ArrayBuffer.isView(bin)) {
+                        reject(new Error(`Invalid data type: ${typeof data}`));
+                        sub.unsubscribe();
+                        return;
+                    }
+                    ws.send(bin);
+                },
+                error: (error) => {
+                    // error from source observable
+                    reject(error);
+                },
+            });
+            sub.add(() => {
+                if (ws.readyState === ws.OPEN) {
+                    ws.close(1000);
+                }
+            });
+            disconnected(ws)
+                .then(resolve, reject)
+                .finally(() => sub.unsubscribe());
+        });
+    }
+}
+/** 消息流插件 */
+const MessageStream = (client) => {
+    const stream = new MessageStreamClient(client);
+    Object.defineProperty(client, 'stream', { value: stream });
+};
+/**
+ * 添加消息流插件，使得可以通过 `client.stream` 访问消息流相关接口
+ */
+export function MessageStreamPlugin() {
+    return MessageStream;
+}
+//# sourceMappingURL=plugin.js.map

package/dist/plugin.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"plugin.js","sourceRoot":"","sources":["../src/plugin.ts"],"names":[],"mappings":"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"}

package/jest.config.js

@@ -0,0 +1,3 @@
+import { config } from '../../jest.config.js';
+
+export default { ...config };

package/package.json

@@ -0,0 +1,37 @@
+{
+  "name": "@cloudpss/message-stream",
+  "version": "0.4.20",
+  "author": "CloudPSS",
+  "license": "MIT",
+  "type": "module",
+  "main": "dist/index.js",
+  "module": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
+    },
+    "./*": {
+      "types": "./dist/*.d.ts",
+      "default": "./dist/*.js"
+    }
+  },
+  "scripts": {
+    "start": "yarn clean && tsc --watch",
+    "build": "yarn clean && tsc",
+    "prepublishOnly": "yarn build",
+    "clean": "rimraf dist",
+    "test": "cross-env NODE_OPTIONS=\"$NODE_OPTIONS --experimental-vm-modules\" jest"
+  },
+  "dependencies": {
+    "@cloudpss/ubjson": "~0.4.20",
+    "@cloudpss/ws": "~0.4.20",
+    "rxjs": "^7.8.1",
+    "type-fest": "^3.10.0"
+  },
+  "peerDependencies": {
+    "@cloudpss/http-client": "~0.4.19"
+  },
+  "devDependencies": {}
+}

package/src/index.ts

@@ -0,0 +1,85 @@
+import type { Opaque } from 'type-fest';
+
+/** UUID */
+type UUID = `${string}-${string}-${string}-${string}-${string}`;
+/**
+ * 标识流的读权限
+ */
+export type StreamId = Opaque<UUID, 'StreamId'>;
+/**
+ * 标识流的写权限
+ */
+export type StreamToken = Opaque<UUID, 'StreamToken'>;
+export const StreamType = ['object', 'binary'] as const;
+/**
+ * 流中消息的类型
+ *  - 'object'，在 StreamMessage 中使用 ubjson 存储
+ *  - 'binary'，在 StreamMessage 中原样存储
+ */
+export type StreamType = (typeof StreamType)[number];
+/**
+ * 流的状态
+ */
+export type StreamState = 'inactive' | 'active' | 'frozen';
+/** 记录调用 `open` 操作的控制器，对应的 `close` 只能由相同的控制器调用 */
+export type StreamWriteHandler = Opaque<string, 'StreamWriteHandler'>;
+
+/**
+ * 消息流，需要使用 {@link StreamToken} 查询
+ */
+export interface Stream {
+    /** id */
+    readonly id: StreamId;
+    /** token */
+    readonly token: StreamToken;
+
+    /** 存储流中消息的类型 */
+    readonly type: StreamType;
+    /** 可选的注释 */
+    readonly comment: string;
+    /** 流的状态 */
+    state: StreamState;
+    /** 打开流的控制器，在 `active` 状态下此项非空 */
+    handler: StreamWriteHandler | null;
+
+    /** 创建时间 */
+    readonly createdAt: Date;
+    /** 最后写入时间 */
+    lastWrittenAt?: Date;
+    /** 最后读取时间 */
+    lastReadAt?: Date;
+    /** 流的持久性 */
+    readonly durability: number;
+}
+
+/** 消息流信息，使用 {@link StreamId} 查询 */
+export type StreamInfo = Omit<Stream, 'token' | 'handler'>;
+/** 创建流需要的数据 */
+export type StreamArgs = Pick<Stream, 'type'> & Partial<Pick<Stream, 'comment' | 'durability'>>;
+
+/** 消息 ID */
+export type MessageId = Opaque<UUID, 'MessageId'>;
+
+/** 原始消息 */
+export interface RawMessage {
+    /** 消息 ID */
+    readonly id: MessageId;
+    /** 消息创建时间 */
+    readonly timestamp: Date;
+    /** 序列化的消息体 */
+    readonly data: Uint8Array;
+}
+
+/** 消息数据 */
+interface MessageData extends Record<StreamType, unknown> {
+    /** 消息数据 */
+    object: unknown;
+    /** 消息数据 */
+    binary: Uint8Array;
+}
+
+/** 消息 */
+export interface Message<T extends StreamType = StreamType> extends Omit<RawMessage, 'data'> {
+    /** 消息数据 */
+    readonly data: MessageData[T];
+}

package/src/plugin.ts

@@ -0,0 +1,163 @@
+import type { HttpClient, HttpClientPlugin } from '@cloudpss/http-client';
+import { WebSocket, connected, disconnected } from '@cloudpss/ws';
+import type { Writable } from 'type-fest';
+import type {
+    Message,
+    RawMessage,
+    Stream,
+    StreamArgs,
+    StreamId,
+    StreamInfo,
+    StreamToken,
+    StreamType,
+} from './index.js';
+import { Observable, type ObservableInput, from } from 'rxjs';
+import { decode, encode } from '@cloudpss/ubjson';
+
+/** 消息流客户端 */
+class MessageStreamClient {
+    constructor(readonly client: HttpClient) {}
+
+    /** 解析响应 */
+    private parse<T extends Stream | StreamInfo>(data: T): T {
+        (data as Writable<T>).createdAt = new Date(data.createdAt);
+        data.lastReadAt = data.lastReadAt ? new Date(data.lastReadAt) : undefined;
+        data.lastWrittenAt = data.lastWrittenAt ? new Date(data.lastWrittenAt) : undefined;
+        return data;
+    }
+
+    /** 创建流 */
+    async create<T extends StreamType>(args: StreamArgs & { type: T }): Promise<Stream & { type: T }>;
+    /** 批量创建流 */
+    async create<T extends StreamType>(
+        args: ReadonlyArray<StreamArgs & { type: T }>,
+    ): Promise<Array<Stream & { type: T }>>;
+    /** 创建流 */
+    async create(args: StreamArgs | readonly StreamArgs[]): Promise<Stream | Stream[]> {
+        if (Array.isArray(args)) {
+            const list = args as readonly StreamArgs[];
+            if (list.length === 0) return [];
+            const result = await this.client.restful<Stream[]>('/streams/bulk', args);
+            return result.data.map((item) => this.parse(item));
+        }
+        const result = await this.client.restful<Stream>('/streams', args);
+        return this.parse(result.data);
+    }
+
+    /** 冻结流 */
+    async freeze(token: StreamToken): Promise<boolean> {
+        const result = await this.client.restful(`/streams/token/${token}/freeze`, undefined, { method: 'PUT' });
+        if (result.response.status === 204) return false;
+        return true;
+    }
+
+    /** 删除流 */
+    async delete(token: StreamToken): Promise<void> {
+        await this.client.restful(`/streams/token/${token}`, undefined, { method: 'DELETE' });
+    }
+
+    /** 获取流信息 */
+    async info(id: StreamId): Promise<StreamInfo> {
+        const result = await this.client.restful<StreamInfo>(`/streams/id/${id}/info`);
+        return this.parse(result.data);
+    }
+
+    /** 获取流信息 */
+    async get(token: StreamToken): Promise<Stream> {
+        const result = await this.client.restful<Stream>(`/streams/token/${token}/info`);
+        return this.parse(result.data);
+    }
+
+    /** 读取消息 */
+    read<T extends StreamType>(
+        stream: {
+            id: StreamId;
+            type: T;
+        },
+        options?: { from?: Date },
+    ): Observable<Message<T>> {
+        const { id, type } = stream;
+        const from = options?.from && Number(options.from) ? `?from=${options.from.toISOString()}` : '';
+        const url = this.client.config.apiUrl.replace(/^http/, 'ws') + `/streams/id/${id}${from}`;
+        return new Observable<Message<T>>((subscriber) => {
+            const ws = new WebSocket(url);
+            if (ws.binaryType === 'blob') ws.binaryType = 'arraybuffer';
+            ws.addEventListener('message', (event) => {
+                if (typeof event.data === 'string' || !event.data) return;
+                const message = decode(event.data as BinaryData) as Writable<RawMessage>;
+                message.timestamp = new Date(message.timestamp);
+                if (type === 'object') {
+                    (message as Writable<Message<'object'>>).data = decode(message.data);
+                }
+                subscriber.next(message);
+            });
+            ws.addEventListener('close', (ev) => {
+                if (ev.code !== 1000) {
+                    subscriber.error(new Error(`WebSocket closed with code ${ev.code}: ${ev.reason}`));
+                } else if (ev.reason) {
+                    subscriber.error(new Error(ev.reason));
+                } else {
+                    subscriber.complete();
+                }
+            });
+            ws.addEventListener('error', (ev) => {
+                const error = ((ev as ErrorEvent).error as Error) ?? new Error(`WebSocket error`);
+                subscriber.error(error);
+            });
+            return () => {
+                if (ws.readyState === ws.OPEN) ws.close(1000);
+            };
+        });
+    }
+
+    /** 写入消息 */
+    async write<T extends StreamType>(
+        stream: {
+            token: StreamToken;
+            type: T;
+        },
+        data: ObservableInput<Message<T>['data']>,
+    ): Promise<void> {
+        const { token, type } = stream;
+        const url = this.client.config.apiUrl.replace(/^http/, 'ws') + `/streams/token/${token}`;
+        const ws = new WebSocket(url);
+        await connected(ws);
+        return new Promise((resolve, reject) => {
+            const sub = from(data).subscribe({
+                next: (data) => {
+                    const bin = type === 'binary' ? (data as Message<'binary'>['data']) : encode(data);
+                    if (!ArrayBuffer.isView(bin)) {
+                        reject(new Error(`Invalid data type: ${typeof data}`));
+                        sub.unsubscribe();
+                        return;
+                    }
+                    ws.send(bin);
+                },
+                error: (error) => {
+                    // error from source observable
+                    reject(error);
+                },
+            });
+            sub.add(() => {
+                if (ws.readyState === ws.OPEN) {
+                    ws.close(1000);
+                }
+            });
+            disconnected(ws)
+                .then(resolve, reject)
+                .finally(() => sub.unsubscribe());
+        });
+    }
+}
+/** 消息流插件 */
+const MessageStream: HttpClientPlugin<{ readonly stream: MessageStreamClient }> = (client) => {
+    const stream = new MessageStreamClient(client);
+    Object.defineProperty(client, 'stream', { value: stream });
+};
+
+/**
+ * 添加消息流插件，使得可以通过 `client.stream` 访问消息流相关接口
+ */
+export function MessageStreamPlugin(): HttpClientPlugin<{ readonly stream: MessageStreamClient }> {
+    return MessageStream;
+}

package/tests/e2e.js

@@ -0,0 +1,24 @@
+/* eslint-disable no-console */
+import { setTimeout } from 'node:timers/promises';
+import { HttpClient } from '@cloudpss/http-client';
+import { MessageStreamPlugin } from '@cloudpss/message-stream/plugin';
+import { interval, map, take } from 'rxjs';
+
+const http = new HttpClient({
+    apiUrl: 'http://dev.local.ddns.cloudpss.net/api/',
+}).use(MessageStreamPlugin());
+console.log(http);
+const stream = await http.stream.create({ type: 'binary', comment: 'test', durability: 0 });
+await http.stream.write(
+    stream,
+    interval(100)
+        .pipe(take(10))
+        .pipe(map((i) => new Uint32Array([i]))),
+);
+await http.stream.freeze(stream.token);
+console.log(stream);
+http.stream.read(stream).subscribe((x) => {
+    console.log(x.data);
+});
+await setTimeout(10);
+await http.stream.delete(stream.token);

package/tests/tsconfig.json

@@ -0,0 +1,9 @@
+{
+  "extends": "../tsconfig",
+  "include": ["./"],
+  "compilerOptions": {
+    "rootDir": "../",
+    "checkJs": true,
+    "noEmit": true
+  }
+}

package/tsconfig.json

@@ -0,0 +1,7 @@
+{
+  "extends": "../../tsconfig",
+  "include": ["./src/"],
+  "compilerOptions": {
+    "outDir": "./dist"
+  }
+}