Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension


Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
7 changes: 6 additions & 1 deletion README.md
Original file line number Diff line number Diff line change
Expand Up @@ -85,7 +85,7 @@ const page = await readMailboxThread(
{ ref: { kind: "workbench", id: "wb-1" }, limit: 50 },
);
// page.items: { id, messageId, inReplyTo?, references, fromAddress, subject?,
// createdAt, read, archived, parentId }
// createdAt, read, archived, parentId, body }
// page.nextCursor: pass back as `cursor` for the next page.

// One message by its Message-ID, scoped to this mailbox.
Expand All @@ -96,6 +96,11 @@ const message = await readMailboxMessageByMessageId(
);
```

`body` is the message's full text, decoded from the stored MIME frame in the
same scan — the same body `getMailboxMessage`'s detail read returns for a
single message. A frame the MIME parser rejects degrades to `""` (logged),
never a failed read.

`parentId` is resolved by RFC 5256 References linking — `In-Reply-To` first,
then the `References` chain newest-to-oldest — across the whole ref-scoped set,
not just the current page. It is `null`, never fabricated, when the nearest
Expand Down
2 changes: 1 addition & 1 deletion package.json
Original file line number Diff line number Diff line change
@@ -1,6 +1,6 @@
{
"name": "@corbits/mailbox",
"version": "0.1.0",
"version": "0.2.0",
"type": "module",
"license": "LGPL-2.1-only",
"description": "Universal principal-keyed inbox, mountable onto any Interchange host. Requires @intx 0.2.2 or newer.",
Expand Down
53 changes: 52 additions & 1 deletion src/thread.test.ts
Original file line number Diff line number Diff line change
Expand Up @@ -34,6 +34,7 @@ beforeEach(async () => {
async function send(args: {
principalId?: string;
subject: string;
body?: string;
inReplyTo?: string;
references?: string[];
refs?: { kind: string; id: string }[];
Expand All @@ -46,7 +47,7 @@ async function send(args: {
address: `${principalId}@t1.example`,
fromAddress: "sender@t1.example",
subject: args.subject,
body: "Body",
body: args.body ?? "Body",
messageKey: args.messageKey,
...(args.inReplyTo !== undefined ? { inReplyTo: args.inReplyTo } : {}),
...(args.references !== undefined ? { references: args.references } : {}),
Expand Down Expand Up @@ -97,6 +98,32 @@ describe("readMailboxThread", () => {
expect(byId.get(second.id)?.parentId).toBe(first.id);
});

test("each message carries its own decoded body", async () => {
const root = await send({
subject: "Root",
body: "Root body text",
refs: [WORKBENCH],
messageKey: "root",
});
const reply = await send({
subject: "Re: Root",
body: "Reply body text",
inReplyTo: root.messageId,
references: [root.messageId],
refs: [WORKBENCH],
messageKey: "reply",
});

const page = await readMailboxThread(
db,
{ tenantId: "t1", principalId: "p1" },
{ ref: WORKBENCH },
);
const byId = new Map(page.items.map((item) => [item.id, item.body]));
expect(byId.get(root.id)).toBe("Root body text");
expect(byId.get(reply.id)).toBe("Reply body text");
});

test("falls back to References, newest ancestor first, when In-Reply-To names nothing present", async () => {
const root = await send({
subject: "Root",
Expand Down Expand Up @@ -696,6 +723,30 @@ describe("readMailboxThreadByMessageId", () => {
expect(page?.items.map((item) => item.id)).toEqual([root.id, reply.id]);
});

test("each message carries its own decoded body", async () => {
const root = await send({
subject: "Root",
body: "Root body text",
messageKey: "root",
});
const reply = await send({
subject: "Re: Root",
body: "Reply body text",
inReplyTo: root.messageId,
references: [root.messageId],
messageKey: "reply",
});

const page = await readMailboxThreadByMessageId(
db,
{ tenantId: "t1", principalId: "p1" },
{ rootMessageId: root.messageId },
);
const byId = new Map(page?.items.map((item) => [item.id, item.body]));
expect(byId.get(root.id)).toBe("Root body text");
expect(byId.get(reply.id)).toBe("Reply body text");
});

test("a non-root Message-ID resolves to null", async () => {
const root = await send({ subject: "Root", messageKey: "root" });
const reply = await send({
Expand Down
37 changes: 34 additions & 3 deletions src/thread.ts
Original file line number Diff line number Diff line change
Expand Up @@ -13,6 +13,7 @@ import { getLogger } from "@intx/log";
import { base64urlDecode, base64urlEncode } from "@intx/types";
import { mailbox, principalMail } from "./schema.js";
import type { MailboxDb } from "./db.js";
import { decodeMailFrame } from "./frame.js";
import {
MailboxRefSchema,
PRINCIPAL_MAIL_LIST_COLUMNS,
Expand Down Expand Up @@ -57,6 +58,13 @@ export const MailboxThreadMessageSchema = type({
read: "boolean",
archived: "boolean",
parentId: "string | null",
/**
* The message's full text body, decoded from the stored MIME frame — the
* same body `MailboxMessageDetailSchema` (`read.ts`) returns for a single
* message. A frame the MIME parser rejects degrades to `""` (logged),
* never a failed read.
*/
body: "string",
});
export type MailboxThreadMessage = typeof MailboxThreadMessageSchema.infer;

Expand Down Expand Up @@ -337,6 +345,9 @@ export async function readMailboxThread(
createdAtText: sql<string>`to_char(${principalMail.createdAt}, 'YYYY-MM-DD"T"HH24:MI:SS.US"Z"')`,
readAt: mailbox.readAt,
archivedAt: mailbox.archivedAt,
// Selected in the same scan (never a per-row follow-up query) so `body`
// can be decoded without an N+1 — see `decodeMailFrame` below.
raw: principalMail.raw,
})
.from(principalMail)
.leftJoin(mailbox, eq(mailbox.id, principalMail.id))
Expand All @@ -351,6 +362,7 @@ export async function readMailboxThread(
const projected = pageRows.map((row) => ({
row,
references: readRowReferences(row.references, row.id, dropped),
body: decodeMailFrame(row.raw)?.body ?? "",
}));
reportDroppedReferences(dropped);

Expand Down Expand Up @@ -442,7 +454,7 @@ export async function readMailboxThread(

const finalParent = resolveAcyclicParents(nodes, rawParent);

const items = projected.map(({ row, references }) => {
const items = projected.map(({ row, references, body }) => {
const item: MailboxThreadMessage = {
id: row.id,
// The row id is the last resort, not the cache: a frame with no
Expand All @@ -454,6 +466,7 @@ export async function readMailboxThread(
read: row.readAt !== null,
archived: row.archivedAt !== null,
parentId: finalParent.get(row.id) ?? null,
body,
};
if (row.inReplyTo !== null) item.inReplyTo = row.inReplyTo;
if (row.subject !== null) item.subject = row.subject;
Expand Down Expand Up @@ -658,7 +671,13 @@ export function decodeMailboxThreadListCursor(
return result;
}

/** One row as scanned for tenant-wide thread grouping — never selects `raw`. */
/**
* One row as scanned for tenant-wide thread grouping.
*
* `body` is decoded from `raw` in the same scan (never a per-row follow-up
* query) so `readMailboxThreadByMessageId` can serve message text without an
* N+1 — see `decodeMailFrame`.
*/
type TenantScanRow = {
id: string;
messageId: string | null;
Expand All @@ -668,12 +687,21 @@ type TenantScanRow = {
subject: string | null;
createdAtText: string;
read: boolean;
body: string;
};

/**
* @param includeBody Also select `raw` and decode `body` in this same scan
* (never a per-row follow-up query). Only `readMailboxThreadByMessageId`
* needs message text; `listMailboxThreads` never surfaces body and does
* not pay for decoding or transferring `raw` across up to
* `MAX_MAILBOX_THREAD_LIST_SCAN_ROWS` rows.
*/
async function scanTenantThreadRows(
db: MailboxDb,
scope: MailboxThreadScope,
refs?: MailboxRef[],
includeBody = false,
): Promise<TenantScanRow[]> {
const conditions = [
eq(principalMail.tenantId, scope.tenantId),
Expand All @@ -696,6 +724,7 @@ async function scanTenantThreadRows(
subject: principalMail.subject,
createdAtText: sql<string>`to_char(${principalMail.createdAt}, 'YYYY-MM-DD"T"HH24:MI:SS.US"Z"')`,
readAt: mailbox.readAt,
...(includeBody ? { raw: principalMail.raw } : {}),
})
.from(principalMail)
.leftJoin(mailbox, eq(mailbox.id, principalMail.id))
Expand All @@ -721,6 +750,7 @@ async function scanTenantThreadRows(
subject: row.subject,
createdAtText: row.createdAtText,
read: row.readAt !== null,
body: "raw" in row && row.raw ? (decodeMailFrame(row.raw)?.body ?? "") : "",
}));
reportDroppedReferences(dropped);
return projected;
Expand Down Expand Up @@ -989,7 +1019,7 @@ export async function readMailboxThreadByMessageId(
cursor = decoded;
}

const rows = await scanTenantThreadRows(db, scope);
const rows = await scanTenantThreadRows(db, scope, undefined, true);
const { nodes, byMessageId, finalParent } = buildTenantThreadGraph(rows);
const startId = byMessageId.get(args.rootMessageId);
if (startId === undefined) return null;
Expand Down Expand Up @@ -1029,6 +1059,7 @@ export async function readMailboxThreadByMessageId(
read: row.read,
archived: false,
parentId: finalParent.get(row.id) ?? null,
body: row.body,
};
if (row.inReplyTo !== null) item.inReplyTo = row.inReplyTo;
if (row.subject !== null) item.subject = row.subject;
Expand Down
Loading