@weifuwujs/messages 0.0.0-stage → 1.0.0

package/dist/testing.js

@@ -0,0 +1,248 @@
+import assert from 'node:assert/strict';
+import { describe, test } from 'node:test';
+import { encodeCursor } from "./cursor.js";
+const T0 = new Date('2026-01-01T00:00:00.000Z');
+const at = (offsetMs) => new Date(T0.getTime() + offsetMs);
+function baseInsert(overrides = {}) {
+    return {
+        userId: 'u1',
+        kind: 'default',
+        title: 'a',
+        body: null,
+        data: null,
+        idempotencyKey: null,
+        createdAt: T0,
+        ...overrides,
+    };
+}
+/**
+ * 消息存储契约套件：memory / sqlite / postgres / redis 与自定义驱动共用。
+ *
+ * ```ts
+ * import { messagesStoreContract } from '@weifuwujs/messages/testing'
+ * messagesStoreContract('my-store', () => myMessageStore())
+ * ```
+ */
+export function messagesStoreContract(name, create, options = {}) {
+    describe(`message store contract (${name})`, { skip: options.skip }, () => {
+        test('insert/get：字段落库、get 必须带 userId（IDOR 防线）', async () => {
+            const store = await create();
+            const first = await store.insert(baseInsert({ title: '欢迎', data: { href: '/x' } }));
+            assert.equal(first.created, true);
+            assert.equal(first.message.userId, 'u1');
+            assert.equal(first.message.kind, 'default');
+            assert.equal(first.message.title, '欢迎');
+            assert.deepEqual(first.message.data, { href: '/x' });
+            assert.equal(first.message.readAt, null);
+            assert.equal(first.message.createdAt.getTime(), T0.getTime());
+            const loaded = await store.get(first.message.id, 'u1');
+            assert.equal(loaded?.id, first.message.id);
+            assert.deepEqual(loaded?.data, { href: '/x' });
+            assert.equal(await store.get(first.message.id, 'u2'), null, '他人 get 必须为 null');
+            assert.equal(await store.get('missing', 'u1'), null);
+        });
+        test('insert 幂等键：重复返回已有且不覆盖；不同用户同键互不影响', async () => {
+            const store = await create();
+            const first = await store.insert(baseInsert({ title: '原消息', idempotencyKey: 'k1' }));
+            const again = await store.insert(baseInsert({ title: '改了', idempotencyKey: 'k1' }));
+            assert.equal(again.created, false);
+            assert.equal(again.message.id, first.message.id);
+            assert.equal(again.message.title, '原消息', '幂等命中不得覆盖');
+            assert.equal((await store.list({ userId: 'u1' })).items.length, 1);
+            const other = await store.insert(baseInsert({ userId: 'u2', idempotencyKey: 'k1' }));
+            assert.equal(other.created, true);
+            assert.notEqual(other.message.id, first.message.id);
+        });
+        test('list：新→旧、unread/kind 过滤、游标续页不重不漏', async () => {
+            const store = await create();
+            for (let index = 1; index <= 5; index++) {
+                await store.insert(baseInsert({ title: `m${index}`, createdAt: at(index * 1000) }));
+            }
+            await store.insert(baseInsert({
+                title: 'k',
+                kind: 'task-done',
+                createdAt: at(6000),
+            }));
+            const page1 = await store.list({ userId: 'u1', limit: 2 });
+            assert.deepEqual(page1.items.map((item) => item.title), ['k', 'm5']);
+            assert.ok(page1.nextCursor);
+            const page2 = await store.list({
+                userId: 'u1',
+                limit: 2,
+                cursor: page1.nextCursor,
+            });
+            assert.deepEqual(page2.items.map((item) => item.title), ['m4', 'm3']);
+            assert.ok(page2.nextCursor);
+            const page3 = await store.list({
+                userId: 'u1',
+                limit: 2,
+                cursor: page2.nextCursor,
+            });
+            assert.deepEqual(page3.items.map((item) => item.title), ['m2', 'm1']);
+            assert.equal(page3.nextCursor, null, '最后一页 nextCursor 为 null');
+            const kind = await store.list({ userId: 'u1', kind: 'task-done' });
+            assert.deepEqual(kind.items.map((item) => item.title), ['k']);
+            assert.equal(kind.nextCursor, null);
+            assert.deepEqual((await store.list({ userId: 'u2' })).items, []);
+        });
+        test('list：同毫秒消息游标分页不重不漏（双键稳定）', async () => {
+            const store = await create();
+            for (let index = 1; index <= 5; index++) {
+                await store.insert(baseInsert({ title: `same-${index}`, createdAt: T0 }));
+            }
+            const seen = [];
+            let cursor = null;
+            for (let page = 0; page < 5; page++) {
+                const result = await store.list({ userId: 'u1', limit: 2, cursor });
+                seen.push(...result.items.map((item) => item.id));
+                cursor = result.nextCursor;
+                if (cursor === null)
+                    break;
+            }
+            assert.equal(seen.length, 5);
+            assert.equal(new Set(seen).size, 5, '同毫秒分页不得重复');
+        });
+        test('unreadCount/markRead/markAllRead：按人隔离、幂等、只影响本人', async () => {
+            const store = await create();
+            const mine1 = await store.insert(baseInsert({ title: 'mine-1' }));
+            const mine2 = await store.insert(baseInsert({ title: 'mine-2' }));
+            const theirs = await store.insert(baseInsert({ userId: 'u2', title: 'theirs' }));
+            assert.equal(await store.unreadCount('u1'), 2);
+            assert.equal(await store.unreadCount('u2'), 1);
+            assert.equal(await store.unreadCount('nobody'), 0);
+            assert.equal(await store.markRead('u1', [theirs.message.id], at(1000)), 0, '越权 ids 不生效');
+            assert.equal(await store.unreadCount('u2'), 1);
+            assert.equal(await store.markRead('u1', [mine1.message.id, 'missing'], at(1000)), 1);
+            assert.equal(await store.markRead('u1', [mine1.message.id], at(2000)), 0, '重复标记返回 0');
+            assert.equal(await store.unreadCount('u1'), 1);
+            assert.equal((await store.get(mine1.message.id, 'u1'))?.readAt?.getTime(), at(1000).getTime());
+            const unreadOnly = await store.list({ userId: 'u1', unreadOnly: true });
+            assert.deepEqual(unreadOnly.items.map((item) => item.title), ['mine-2']);
+            assert.equal(await store.markAllRead('u1', at(3000)), 1);
+            assert.equal(await store.unreadCount('u1'), 0);
+            assert.equal(await store.markAllRead('u1', at(4000)), 0, '重复全部已读返回 0');
+            assert.equal(await store.unreadCount('u2'), 1, 'u2 未读不受影响');
+            assert.ok(mine2.message.id);
+        });
+        test('listAfter：游标之后升序补投、hasMore 续接、仅本人、无效游标报错', async () => {
+            const store = await create();
+            for (let index = 1; index <= 5; index++) {
+                await store.insert(baseInsert({ title: `m${index}`, createdAt: at(index * 1000) }));
+            }
+            await store.insert(baseInsert({ userId: 'u2', title: 'theirs', createdAt: at(60_000) }));
+            const page1 = await store.listAfter({ userId: 'u1', cursor: null, limit: 2 });
+            assert.deepEqual(page1.items.map((item) => item.title), ['m1', 'm2']);
+            assert.equal(page1.hasMore, true);
+            const page2 = await store.listAfter({
+                userId: 'u1',
+                cursor: encodeCursor(page1.items[1]),
+                limit: 2,
+            });
+            assert.deepEqual(page2.items.map((item) => item.title), ['m3', 'm4']);
+            assert.equal(page2.hasMore, true);
+            const page3 = await store.listAfter({
+                userId: 'u1',
+                cursor: encodeCursor(page2.items[1]),
+                limit: 2,
+            });
+            assert.deepEqual(page3.items.map((item) => item.title), ['m5']);
+            assert.equal(page3.hasMore, false);
+            const empty = await store.listAfter({
+                userId: 'u1',
+                cursor: encodeCursor(page3.items[0]),
+                limit: 2,
+            });
+            assert.deepEqual(empty.items, []);
+            assert.equal(empty.hasMore, false);
+            const theirs = await store.listAfter({ userId: 'u2', cursor: null, limit: 10 });
+            assert.deepEqual(theirs.items.map((item) => item.title), ['theirs']);
+            await assert.rejects(() => store.listAfter({ userId: 'u1', cursor: 'bogus', limit: 2 }), /invalid cursor/);
+        });
+        test('listAfter：同毫秒升序稳定，续接不重不漏', async () => {
+            const store = await create();
+            for (let index = 0; index < 5; index++) {
+                await store.insert(baseInsert({ title: `s${index}`, createdAt: T0 }));
+            }
+            const seen = [];
+            let cursor = null;
+            for (;;) {
+                const page = await store.listAfter({ userId: 'u1', cursor, limit: 2 });
+                seen.push(...page.items.map((item) => item.id));
+                if (!page.hasMore)
+                    break;
+                assert.ok(page.items.length > 0, 'hasMore 时不得返回空页');
+                cursor = encodeCursor(page.items[page.items.length - 1]);
+            }
+            assert.equal(seen.length, 5);
+            assert.equal(new Set(seen).size, 5, '同毫秒升序续接不得重复');
+        });
+    });
+}
+const sleep = (ms) => new Promise((resolve) => setTimeout(resolve, ms));
+async function waitFor(condition, timeoutMs = 3000) {
+    const deadline = Date.now() + timeoutMs;
+    while (!condition()) {
+        if (Date.now() > deadline)
+            throw new Error('waitFor 超时');
+        await sleep(10);
+    }
+}
+/**
+ * 消息总线契约套件：local / redis 与自定义总线共用。
+ *
+ * ```ts
+ * import { messageBusContract } from '@weifuwujs/messages/testing'
+ * messageBusContract('my-bus', () => myMessageBus())
+ * ```
+ */
+export function messageBusContract(name, create, options = {}) {
+    describe(`message bus contract (${name})`, { skip: options.skip }, () => {
+        test('watch/publish：多 watcher 全收、按用户隔离、无 watcher 不抛', async () => {
+            const bus = await create();
+            try {
+                const u1a = [];
+                const u1b = [];
+                const u2 = [];
+                bus.watch('u1', (event) => u1a.push(event));
+                bus.watch('u1', (event) => u1b.push(event));
+                bus.watch('u2', (event) => u2.push(event));
+                await bus.ready?.();
+                const first = { type: 'unread', unread: 1 };
+                await bus.publish('u1', first);
+                await waitFor(() => u1a.length === 1 && u1b.length === 1);
+                assert.deepEqual(u1a[0], first);
+                assert.deepEqual(u1b[0], first);
+                assert.equal(u2.length, 0, '不同用户不得串台');
+                const second = { type: 'unread', unread: 2 };
+                await bus.publish('u2', second);
+                await waitFor(() => u2.length === 1);
+                assert.deepEqual(u2[0], second);
+                await bus.publish('nobody', second);
+            }
+            finally {
+                await bus.close?.();
+            }
+        });
+        test('unwatch：退订后旧 handler 不得再收（订阅泄漏回归）', async () => {
+            const bus = await create();
+            try {
+                const seen = [];
+                const stop = bus.watch('u1', (event) => seen.push(event));
+                await bus.ready?.();
+                await bus.publish('u1', { type: 'unread', unread: 1 });
+                await waitFor(() => seen.length === 1);
+                stop();
+                bus.watch('u1', (event) => seen.push(event));
+                await bus.ready?.();
+                await bus.publish('u1', { type: 'unread', unread: 2 });
+                await waitFor(() => seen.length === 2);
+                await sleep(150);
+                assert.equal(seen.length, 2, 'unwatch 后旧 handler 泄漏，收到重复事件');
+            }
+            finally {
+                await bus.close?.();
+            }
+        });
+    });
+}
+//# sourceMappingURL=testing.js.map

package/dist/testing.js.map

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

package/dist/types.d.ts

@@ -0,0 +1,171 @@
+import type { App, MountableRoute } from '@weifuwujs/weifuwu';
+/** 站内信消息（userId 是归属人；data 必须 JSON 可序列化） */
+export interface Message {
+    id: string;
+    userId: string;
+    /** 分类，如 `welcome` / `task-done` */
+    kind: string;
+    title: string;
+    body: string | null;
+    /** 深链/附加数据（JSON 可序列化） */
+    data: unknown;
+    readAt: Date | null;
+    /** (userId, key) 唯一；重复 send 返回已有消息 */
+    idempotencyKey: string | null;
+    createdAt: Date;
+}
+/** store.insert 入参：createdAt 由门面注入的时钟决定（测试确定性） */
+export interface InsertMessageInput {
+    userId: string;
+    kind: string;
+    title: string;
+    body: string | null;
+    data: unknown;
+    idempotencyKey: string | null;
+    createdAt: Date;
+}
+export interface StoreInsertResult {
+    message: Message;
+    created: boolean;
+}
+export interface ListQuery {
+    userId: string;
+    unreadOnly?: boolean;
+    kind?: string;
+    /** 默认 20（由门面填充），store 按 1..100 处理 */
+    limit?: number;
+    /** 上一页的 `nextCursor`；无效游标应抛错 */
+    cursor?: string | null;
+}
+export interface ListPage {
+    items: Message[];
+    /** 非 null 表示还有更早的一页 */
+    nextCursor: string | null;
+}
+/** 断线补投：查询游标之后（更晚）的消息 */
+export interface ListAfterQuery {
+    userId: string;
+    /** null = 从最早开始全量；无效游标应招错 */
+    cursor: string | null;
+    limit: number;
+}
+export interface ListAfterPage {
+    /** 升序（旧→新），便于客户端按序播放 */
+    items: Message[];
+    /** true = 还有更晚的消息（用最后一条的游标续接） */
+    hasMore: boolean;
+}
+/**
+ * 消息存储契约（memory / sqlite / postgres / redis 同一套）。
+ *
+ * 语义要点：
+ * - 查询一律带 `userId`（IDOR 防线）；`get` 非本人返回 null；
+ * - `insert` 幂等键命中返回已有消息（created=false），不覆盖；
+ * - `list` 按 `(createdAt, id)` 降序（新→旧），同毫秒也稳定；
+ * - `markRead`/`markAllRead` 只写本人消息且幂等，返回实际更新数。
+ */
+export interface MessageStore {
+    insert(input: InsertMessageInput): Promise<StoreInsertResult>;
+    get(id: string, userId: string): Promise<Message | null>;
+    list(query: ListQuery): Promise<ListPage>;
+    /** 游标之后（更晚）的消息，升序；断线补投用 */
+    listAfter(query: ListAfterQuery): Promise<ListAfterPage>;
+    unreadCount(userId: string): Promise<number>;
+    markRead(userId: string, ids: string[], now: Date): Promise<number>;
+    markAllRead(userId: string, now: Date): Promise<number>;
+    /** 可选：建表/迁移（sqlite/postgres 实现；memory 不需要） */
+    migrate?(): Promise<void>;
+}
+export interface SendInput {
+    userId: string;
+    title: string;
+    kind?: string;
+    body?: string | null;
+    data?: unknown;
+    idempotencyKey?: string | null;
+}
+export interface SendResult {
+    message: Message;
+    /** false = 幂等键命中已有消息 */
+    created: boolean;
+}
+/** WS 推送事件（`message` 新消息 / `unread` 徽标变化 / `sync` 断线补投快照） */
+export interface MessagesEventMap {
+    message: {
+        type: 'message';
+        message: Message;
+    };
+    unread: {
+        type: 'unread';
+        unread: number;
+    };
+    sync: {
+        type: 'sync';
+        /** 升序（旧→新），客户端按 id 去重后播放 */
+        items: Message[];
+        hasMore: boolean;
+        unread: number;
+    };
+}
+export type MessagesEvent = MessagesEventMap[keyof MessagesEventMap];
+/**
+ * 跨节点推送总线（`localMessageBus()` 默认；`redisMessageBus()` 多副本）。
+ * 语义：至少一次、可乱序；`unread` 是快照值，`message` 由客户端按 id 去重。
+ */
+export interface MessageBus {
+    /** 发布到所有节点（含本节点）；失败不应影响业务写入 */
+    publish(userId: string, event: MessagesEvent): void | Promise<void>;
+    /** 本节点开始接收该用户事件；返回停止函数 */
+    watch(userId: string, handler: (event: MessagesEvent) => void): () => void;
+    /** 等待订阅就绪（redis 连接）；in-process 可省略 */
+    ready?(): void | Promise<void>;
+    close?(): void | Promise<void>;
+}
+export interface InstallMessagesOptions {
+    /** WS 端点路径，默认 `/messages/ws` */
+    wsPath?: string;
+    /** 是否同时 `app.mount(messages)`，默认 true */
+    rest?: boolean;
+}
+export interface MessageLogger {
+    warn(message: string): void;
+    error(message: string): void;
+}
+export interface CreateMessagesOptions {
+    store: MessageStore;
+    /** 实时总线；默认进程内 `localMessageBus()`（多副本用 `redisMessageBus()`） */
+    bus?: MessageBus;
+    /** 新消息创建后回调；抛错只告警（消息已持久化），幂等命中不触发 */
+    onSend?: (message: Message) => void | Promise<void>;
+    logger?: MessageLogger;
+    /** 可注入时钟（测试用） */
+    now?: () => Date;
+    /** REST 前缀，默认 `/messages` */
+    routePrefix?: string;
+    /** 分页默认页大小，默认 20（上限 100） */
+    pageSize?: number;
+    /** 断线补投单次最大条数，默认 100 */
+    syncLimit?: number;
+}
+export interface Messages {
+    store: MessageStore;
+    send(input: SendInput): Promise<SendResult>;
+    list(query: ListQuery): Promise<ListPage>;
+    unread(userId: string): Promise<number>;
+    markRead(userId: string, ids: string[]): Promise<number>;
+    markAllRead(userId: string): Promise<number>;
+    /** 挂到 `app.mount(messages)` 的只读 REST 路由（未认证 401） */
+    routes(): MountableRoute[];
+    /** 一条线接线：`app.mount(messages)` + WS 端点（未认证升级 401），并随 `app.close()` 收连接 */
+    install(app: App<any>, options?: InstallMessagesOptions): Messages;
+    /** 在线连接数（省略 userId = 全部） */
+    connections(userId?: string): number;
+    /** 手动推送（自定义流程/测试）；正常路径由 send / markRead 自动推送 */
+    publish(userId: string, event: MessagesEvent): Promise<void>;
+    /** 等待总线订阅就绪（redis 连接后调一次） */
+    ready(): Promise<void>;
+    /** 停止订阅、关闭本实例拥有的总线与全部连接；可重复调（幂等） */
+    close(): Promise<void>;
+    migrate(): Promise<void>;
+}
+//# sourceMappingURL=types.d.ts.map

package/dist/types.d.ts.map

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

package/dist/types.js

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=types.js.map

package/dist/types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":""}

package/package.json

@@ -1,6 +1,66 @@
 {
   "name": "@weifuwujs/messages",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "1.0.0",
+  "description": "weifuwu 站内信：幂等发送、REST 收件箱、WS 实时 + 断线 since 补投去重、memory/sqlite/postgres 契约套件、可插拔总线",
+  "type": "module",
+  "engines": {
+    "node": ">=24.0.0"
+  },
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js",
+      "default": "./dist/index.js"
+    },
+    "./sqlite": {
+      "types": "./dist/sqlite.d.ts",
+      "import": "./dist/sqlite.js",
+      "default": "./dist/sqlite.js"
+    },
+    "./postgres": {
+      "types": "./dist/postgres.d.ts",
+      "import": "./dist/postgres.js",
+      "default": "./dist/postgres.js"
+    },
+    "./redis": {
+      "types": "./dist/redis.d.ts",
+      "import": "./dist/redis.js",
+      "default": "./dist/redis.js"
+    },
+    "./testing": {
+      "types": "./dist/testing.d.ts",
+      "import": "./dist/testing.js",
+      "default": "./dist/testing.js"
+    }
+  },
+  "files": [
+    "dist",
+    "templates"
+  ],
+  "scripts": {
+    "build": "tsc -p tsconfig.build.json",
+    "typecheck": "tsc -p tsconfig.json",
+    "test": "node --test --test-force-exit \"test/**/*.test.ts\"",
+    "prepublishOnly": "npm run typecheck && npm run build && npm test"
+  },
+  "peerDependencies": {
+    "@weifuwujs/weifuwu": ">=1 <2",
+    "postgres": ">=3.4.0",
+    "ioredis": ">=5.0.0"
+  },
+  "peerDependenciesMeta": {
+    "postgres": {
+      "optional": true
+    },
+    "ioredis": {
+      "optional": true
+    }
+  },
+  "devDependencies": {
+    "@weifuwujs/weifuwu": "file:../..",
+    "@weifuwujs/tasks": "file:../tasks"
+  },
+  "bin": {
+    "weifuwu-messages": "./dist/cli.js"
+  }
+}

package/templates/react-router-messages/app/messages.ts

@@ -0,0 +1,13 @@
+import { createMessages } from '@weifuwujs/weifuwu/messages'
+import { sqliteMessageStore } from '@weifuwujs/weifuwu/messages/sqlite'
+
+/**
+ * 站内信：默认 sqlite（构造自动建表，零迁移步骤）。
+ *
+ * - 换 postgres：`postgresMessageStore(process.env.DATABASE_URL!)`（`./messages/postgres`）；
+ * - 多副本实时：`bus: redisMessageBus(process.env.REDIS_URL!, { prefix: 'ww:messages' })`
+ *   （`./messages/redis`；注入的 bus 由你负责 close）。
+ */
+export const messages = createMessages({
+  store: sqliteMessageStore('data/messages.db'),
+})

package/templates/react-router-messages/app/routes/home.tsx

@@ -0,0 +1,51 @@
+import { Link } from 'react-router'
+import type { Route } from './+types/home'
+import { authUserContext, greetingContext } from '~/context.ts'
+import { messages } from '~/messages.ts'
+
+export function meta() {
+  return [{ title: '首页' }]
+}
+
+export async function loader({ context }: Route.LoaderArgs) {
+  const user = context.get(authUserContext)
+  if (!user) {
+    return { greeting: context.get(greetingContext) ?? 'missing-context', unread: 0 }
+  }
+  // 首访欢迎信：幂等键让重复访问/重试只落一条（站内信核心保证的现场演示）
+  await messages.send({
+    userId: user.id,
+    kind: 'welcome',
+    title: '欢迎使用站内信',
+    body: '这是你的第一条消息；到通知页可以标记已读，并看到实时推送。',
+    idempotencyKey: `welcome:${user.id}`,
+  })
+  return {
+    greeting: context.get(greetingContext) ?? 'missing-context',
+    unread: await messages.unread(user.id),
+  }
+}
+
+export default function Home({ loaderData }: Route.ComponentProps) {
+  return (
+    <main className="mx-auto max-w-xl p-8">
+      <h1 className="text-3xl font-bold text-blue-600">
+        Hello from React Router
+      </h1>
+      <p className="mt-2 text-gray-600">{loaderData.greeting}</p>
+      <Link
+        to="/notifications"
+        data-testid="messages-link"
+        data-unread={loaderData.unread}
+        className="mt-6 inline-flex items-center gap-2 border px-3 py-1.5 text-sm"
+      >
+        消息
+        {loaderData.unread > 0 ? (
+          <span className="rounded-full bg-red-600 px-2 text-white">
+            {loaderData.unread}
+          </span>
+        ) : null}
+      </Link>
+    </main>
+  )
+}