@rei-standard/amsg-server 2.6.0-next.5 → 2.6.0-next.7

package/README.md

@@ -104,10 +104,32 @@ AI 配置消息的提示词可以用两种形态之一，**互斥二选一**：
 - 限制：每项 ≤ 200 字符，数组 ≤ 10 项；非法或无法 `new RegExp(...)` 通过 → `400 INVALID_PARAMETERS`（schedule）/ `400 INVALID_UPDATE_DATA`（update）。
 - `update-message` 显式传 `splitPattern: null` 可重置回默认；不传则保留原值。
 
+## 一条 Web Push 能塞多少
+
+推送服务（FCM / APNs / Mozilla autopush）限的是**加密后** body 的 4096 字节，超了当场 413 拒收，用户什么也收不到。明文额度要把 aes128gcm 的固定开销减掉——header 86（salt 16 + record size 4 + keyid 长度 1 + 应用服务器公钥 65）+ 填充分隔符 1 + GCM auth tag 16 = 103 字节——所以**一条 push 的 payload 上限是 3993 字节**，按 UTF-8 字节算，不是字符数。
+
+`sendWebPush` 会在发出去之前挡下超限的 payload，抛出 `err.code === 'PUSH_PAYLOAD_TOO_LARGE'` 的错误，消息里带实际字节数和上限。
+
+组 payload 之前想自己做预算，用导出的常量和工具函数，别写死魔法数字：
+
+```js
+import { MAX_PUSH_PAYLOAD_BYTES, measurePushPayload } from '@rei-standard/amsg-server';
+
+const { bytes, remainingBytes, withinLimit } = measurePushPayload(JSON.stringify(push));
+// remainingBytes = 还能再塞多少字节（已超限时为负）
+```
+
+装不下的内容（长文、附件详情）建议走旁路：正文存进 `client_state`，push 里只带一个引用键，客户端上线后用 `GET /client-state` 取回。单用户 Worker 的 fire-time hook 用 `ctx.writeState()` 写，见 [`examples/cloudflare-single-user/README.md`](https://github.com/Tosd0/ReiStandard/blob/main/packages/rei-standard-amsg/server/examples/cloudflare-single-user/README.md)。
+
 ## 导出（新增）
 
 - `validateLlmMessagesArray(messages)` — 同步预校验 messages 数组，返回 `string | null`（错误信息 / 通过）。和 `@rei-standard/amsg-instant` 的校验规则字节级一致。
 - `validateSplitPattern(value)` — 同步预校验 splitPattern（string / string[] / null），返回 `string | null`。
+- `MAX_PUSH_PAYLOAD_BYTES` — 一条 push 的明文上限，3993 字节。
+- `WEB_PUSH_MAX_BODY_BYTES` / `WEB_PUSH_ENCRYPTION_OVERHEAD_BYTES` — 推送服务的密文 body 上限（4096）与 aes128gcm 固定开销（103），上面那个数就是两者相减。
+- `measurePushPayload(payload)` — 量一段 payload 的字节数与剩余额度，返回 `{ bytes, maxBytes, remainingBytes, withinLimit }`。
+
+以上四个在包根和 `@rei-standard/amsg-server/cloudflare` 两个入口都有。
 
 ## 一体化初始化流程
 
@@ -123,6 +145,22 @@ AI 配置消息的提示词可以用两种形态之一，**互斥二选一**：
 - `send-notifications`
   - `Authorization: Bearer <cronToken>` 或 `?token=<cronToken>`
 
+## 触发任务时的占位
+
+`send-notifications`（以及单用户 Worker 的 `scheduled()`）每条任务开跑前会先占位：在这一行的 `lease_until` 上写下「归我管到现在 + 租期为止」，本次投递期间别的 tick 领不走它；占位改到 0 行说明别人先领走了，本次直接跳过。cron 一分钟一跳而带工具的 AI 任务常常跑过一分钟，没有这层占位同一条任务会被相邻几跳重复触发。
+
+租约写在自己的列上，`next_send_at` 全程不动——任务列表读到的一直是用户设的那个时刻，循环任务也按它推进到下一次。投递收尾时租约就放掉，失败重试的退避（2 分钟起）不会被租期压住。
+
+领了任务的那一跳中途没了（Worker 被回收之类）就没人来放租约，这条任务要等租约到期才会被后面的 tick 接手。把租期设得比最慢的一次投递长一点即可。
+
+租期默认 10 分钟；配了 `totalTimeoutMs` 的话按它 + 2 分钟往上抬。想自己定就在 `runScheduledTick` 的 ctx（或单用户 Worker 的 config）里传 `claimLeaseMs`——注意 `createReiServer` 内置的 `/send-notifications` 处理器不透传这两个值，要调租期就自己调 `runScheduledTick`。`onBeforeFire` 里按次放宽的预算占位时看不到，那种情况也要显式设 `claimLeaseMs`。
+
+占位管的是定时触发这条路径。`messageType: 'instant'` 走的是「建行 → 当场投递」，不经过占位。
+
+内置适配器都实现了占位。自定义适配器可以不实现 `claimTask`，跑得动，只是回到不占位的行为。
+
+`lease_until` 是这次新加的列。走 `POST /init-tenant`（或任何一次 `initSchema`）会自动给已有的表补上；手工建表的看 `examples/cloudflare-single-user/schema.sql`。
+
 ## 导出 API（Exports）
 
 - `createReiServer`
@@ -134,6 +172,10 @@ AI 配置消息的提示词可以用两种形态之一，**互斥二选一**：
 - `encryptForStorage`
 - `decryptFromStorage`
 - `validateScheduleMessagePayload`
+- `measurePushPayload`
+- `MAX_PUSH_PAYLOAD_BYTES`
+- `WEB_PUSH_MAX_BODY_BYTES`
+- `WEB_PUSH_ENCRYPTION_OVERHEAD_BYTES`
 - `isValidISO8601`
 - `isValidUrl`
 - `isValidUUID`

package/dist/{chunk-RGECD4OH.cjs → chunk-DCKCAGFV.cjs}

@@ -7,12 +7,20 @@ var TABLE_SQL = `
     encrypted_payload TEXT NOT NULL,
     message_type VARCHAR(50) NOT NULL CHECK (message_type IN ('fixed', 'prompted', 'auto', 'instant')),
     next_send_at TIMESTAMP WITH TIME ZONE NOT NULL,
+    lease_until TIMESTAMP WITH TIME ZONE,
     status VARCHAR(50) NOT NULL DEFAULT 'pending' CHECK (status IN ('pending', 'sent', 'failed')),
     retry_count INTEGER DEFAULT 0,
     created_at TIMESTAMP WITH TIME ZONE DEFAULT NOW(),
     updated_at TIMESTAMP WITH TIME ZONE DEFAULT NOW()
   )
 `;
+var MIGRATIONS = [
+  {
+    name: "add_lease_until",
+    sql: "ALTER TABLE scheduled_messages ADD COLUMN IF NOT EXISTS lease_until TIMESTAMP WITH TIME ZONE",
+    description: "Task claim lease (2.6.0)"
+  }
+];
 var INDEXES = [
   {
     name: "idx_pending_tasks_optimized",
@@ -69,4 +77,5 @@ var COLUMNS_SQL = `
 
 
 
-exports.TABLE_SQL = TABLE_SQL; exports.INDEXES = INDEXES; exports.VERIFY_TABLE_SQL = VERIFY_TABLE_SQL; exports.COLUMNS_SQL = COLUMNS_SQL;
+
+exports.TABLE_SQL = TABLE_SQL; exports.MIGRATIONS = MIGRATIONS; exports.INDEXES = INDEXES; exports.VERIFY_TABLE_SQL = VERIFY_TABLE_SQL; exports.COLUMNS_SQL = COLUMNS_SQL;

package/dist/{chunk-5ENJGVZX.mjs → chunk-GOBCWCJP.mjs}

@@ -7,12 +7,20 @@ var TABLE_SQL = `
     encrypted_payload TEXT NOT NULL,
     message_type VARCHAR(50) NOT NULL CHECK (message_type IN ('fixed', 'prompted', 'auto', 'instant')),
     next_send_at TIMESTAMP WITH TIME ZONE NOT NULL,
+    lease_until TIMESTAMP WITH TIME ZONE,
     status VARCHAR(50) NOT NULL DEFAULT 'pending' CHECK (status IN ('pending', 'sent', 'failed')),
     retry_count INTEGER DEFAULT 0,
     created_at TIMESTAMP WITH TIME ZONE DEFAULT NOW(),
     updated_at TIMESTAMP WITH TIME ZONE DEFAULT NOW()
   )
 `;
+var MIGRATIONS = [
+  {
+    name: "add_lease_until",
+    sql: "ALTER TABLE scheduled_messages ADD COLUMN IF NOT EXISTS lease_until TIMESTAMP WITH TIME ZONE",
+    description: "Task claim lease (2.6.0)"
+  }
+];
 var INDEXES = [
   {
     name: "idx_pending_tasks_optimized",
@@ -66,6 +74,7 @@ var COLUMNS_SQL = `
 
 export {
   TABLE_SQL,
+  MIGRATIONS,
   INDEXES,
   VERIFY_TABLE_SQL,
   COLUMNS_SQL