Skip to content
Closed
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
3 changes: 3 additions & 0 deletions TESTING_COVERAGE.md
Original file line number Diff line number Diff line change
Expand Up @@ -554,6 +554,9 @@ Two things worth knowing about the runners:
| Signed envelopes per resource: `latest`/`all` retention, time order, not indexed, verified attribution per Loro token, tampered envelope unverified, two writers, destroy fold | `lib/src/envelopes.rs` |
| `GET /history-attribution` names the verified signer and is read-gated | `server/tests/it/history_attribution.rs` |
| Attribution parse / version lookup / server+local merge | `browser/lib/src/history-attribution.test.ts` |
| Per-table change list (#1850): created/updated/deleted kinds for create, edit, move out, move in, destroy; one entry per row; per-row Loro version; bounded pages and a row edited between pages; tombstone pruning expires older cursors (410); classtype change rebuilds; backfill of pre-existing rows; replicated (`persist_replicated_resource`) and sync-removed rows; table destroy drops its log; readers without table read learn nothing; restart durability | `lib/src/change_log_test.rs` |
| `GET /changes`: row listed with version, stranger refused, typed `INVALID_CURSOR` / `CURSOR_EXPIRED` | `server/src/tests.rs` (`table_changes_endpoint`) |
| Change list client: parse, request shape, 410 → `TableChangesCursorExpiredError` | `browser/lib/src/table-changes.test.ts`. **Gap:** no `browser/lib` integration test against a real server, and no plugin host call yet (#1851) |
| Engine-level two-store sync, private drives, blobs, live push | `lib/src/sync/tests.rs` |
| Drive hashing; a filtered `SYNC` (`subjects`) diffs like the full one | `lib/src/sync/tests.rs` |
| Remote update merge, drive-spoof rejection, tombstones | `lib/src/sync/ws_apply.rs`, `tombstones.rs` |
Expand Down
11 changes: 11 additions & 0 deletions browser/lib/src/index.ts
Original file line number Diff line number Diff line change
Expand Up @@ -80,6 +80,17 @@ export {
parseHistoryAttribution,
} from './history-attribution.js';
export type { Attribution, HistoryAttribution } from './history-attribution.js';
export {
fetchTableChanges,
parseTableChangesPage,
TableChangesCursorExpiredError,
} from './table-changes.js';
export type {
TableChange,
TableChangeKind,
TableChangesOptions,
TableChangesPage,
} from './table-changes.js';
export type {
ClientDbOutboxWrite,
ClientDbQueryOpts,
Expand Down
24 changes: 24 additions & 0 deletions browser/lib/src/store.ts
Original file line number Diff line number Diff line change
Expand Up @@ -26,6 +26,11 @@ import {
signRequest,
} from './authentication.js';
import { Client, isOwnServerUrl, type FileOrFileLike } from './client.js';
import {
fetchTableChanges,
type TableChangesOptions,
type TableChangesPage,
} from './table-changes.js';
import {
CommitBuilder,
commitIdOf,
Expand Down Expand Up @@ -4514,6 +4519,25 @@ export class Store {
return mergeHistoryAttributions(remote, local);
}

/**
* Rows of `table` that changed since `opts.since`, including rows that
* left it (tombstones), each with its Loro version. Without `since`, lists
* every current row. Page through with the returned `cursor` while
* `hasMore`. Throws {@link TableChangesCursorExpiredError} when the cursor
* is older than the server's retention: resync without `since`.
* `GET /changes` on the connected server (atomic-server #1850).
*/
public async getTableChanges(
table: string,
opts: TableChangesOptions = {},
): Promise<TableChangesPage> {
if (!this.serverUrl) {
throw new Error('getTableChanges needs a server');
}

return fetchTableChanges(this.serverUrl, this.getAgent(), table, opts);
}

private async fetchHistoryAttributionFromServer(
subject: string,
): Promise<HistoryAttribution | null> {
Expand Down
97 changes: 97 additions & 0 deletions browser/lib/src/table-changes.test.ts
Original file line number Diff line number Diff line change
@@ -0,0 +1,97 @@
import { describe, expect, it, vi } from 'vitest';
import {
fetchTableChanges,
parseTableChangesPage,
TableChangesCursorExpiredError,
} from './table-changes.js';

const page = {
changes: [
{
subject: 'https://example.com/row-1',
kind: 'updated',
version: { '123': 4 },
at: 1_700_000_000_000,
},
{
subject: 'https://example.com/row-2',
kind: 'deleted',
version: null,
at: 1_700_000_000_001,
},
],
cursor: 'abc',
hasMore: false,
};

function respond(status: number, body: unknown) {
return vi.fn(
async () =>
new Response(JSON.stringify(body), {
status,
headers: { 'Content-Type': 'application/json' },
}),
);
}

describe('table changes', () => {
it('parses a page', () => {
expect(parseTableChangesPage(page)).toEqual(page);
});

it('rejects malformed pages', () => {
expect(() => parseTableChangesPage({ changes: [] })).toThrow();
expect(() =>
parseTableChangesPage({
...page,
changes: [{ subject: 'x', kind: 'moved', at: 1 }],
}),
).toThrow();
});

it('builds the request from table, since and limit', async () => {
const fetchImpl = respond(200, page);
const result = await fetchTableChanges(
'https://example.com',
undefined,
'https://example.com/table',
{ since: 'c1', limit: 50 },
fetchImpl as unknown as typeof fetch,
);
expect(result.cursor).toBe('abc');
const url = new URL((fetchImpl.mock.calls[0] as unknown as [string])[0]);
expect(url.pathname).toBe('/changes');
expect(url.searchParams.get('table')).toBe('https://example.com/table');
expect(url.searchParams.get('since')).toBe('c1');
expect(url.searchParams.get('limit')).toBe('50');
});

it('turns 410 into a typed resync error', async () => {
const fetchImpl = respond(410, {
error: 'CURSOR_EXPIRED',
message: 'resync',
});
await expect(
fetchTableChanges(
'https://example.com',
undefined,
'https://example.com/table',
{ since: 'old' },
fetchImpl as unknown as typeof fetch,
),
).rejects.toBeInstanceOf(TableChangesCursorExpiredError);
});

it('reports other failures', async () => {
const fetchImpl = respond(400, { error: 'NOT_A_TABLE' });
await expect(
fetchTableChanges(
'https://example.com',
undefined,
'https://example.com/folder',
{},
fetchImpl as unknown as typeof fetch,
),
).rejects.toThrow(/NOT_A_TABLE/);
});
});
136 changes: 136 additions & 0 deletions browser/lib/src/table-changes.ts
Original file line number Diff line number Diff line change
@@ -0,0 +1,136 @@
/**
* The per-table change list (atomic-server #1850): rows of a table that
* changed since an opaque cursor, including rows that left it (tombstones),
* each with its Loro version so a caller can diff fields against its own
* baseline. "Hook for speed, change list for correctness."
*
* A table is a resource of class `Table` with a `classtype`; its rows are its
* children of that class. Served by `GET /changes?table=&since=&limit=` on the
* connected server; see `docs/src/changes.md`.
*/

import { signRequest } from './authentication.js';
import type { Agent } from './agent.js';

export type TableChangeKind = 'created' | 'updated' | 'deleted';

export interface TableChange {
/** The row's subject. */
subject: string;
/**
* `created`: the row entered the table (created, moved in, given the class).
* `updated`: edited and still in the table. `deleted`: left the table
* (destroyed, moved out, lost the class). Only the latest change per row is
* kept, so treat `created` and `updated` alike (upsert).
*/
kind: TableChangeKind;
/**
* The row's Loro version vector after the change, peer id to counter:
* `VersionVector.parseJSON(new Map(Object.entries(version)))`. For
* `deleted`, the last version the server held. Null when it had none.
*/
version: Record<string, number> | null;
/** When the server recorded the change, Unix milliseconds. */
at: number;
}

export interface TableChangesPage {
changes: TableChange[];
/** Pass back as `since` to continue. */
cursor: string;
/** More changes are waiting; ask again with `cursor` right away. */
hasMore: boolean;
}

export interface TableChangesOptions {
/** A cursor from an earlier page. Omit to list every current row. */
since?: string;
/** Page size; the server caps it at 500 (default 100). */
limit?: number;
}

/**
* The cursor predates the server's tombstone retention (or the table's rows
* were redefined). Resync: list again without `since` and reconcile.
*/
export class TableChangesCursorExpiredError extends Error {
public readonly code = 'CURSOR_EXPIRED';

public constructor(message = 'Change list cursor expired; resync') {
super(message);
this.name = 'TableChangesCursorExpiredError';
}
}

/** Parse the server's JSON. Throws on anything malformed. */
export function parseTableChangesPage(input: unknown): TableChangesPage {
if (!input || typeof input !== 'object') {
throw new Error('Malformed change list page');
}

const data = input as Record<string, unknown>;

if (
!Array.isArray(data.changes) ||
typeof data.cursor !== 'string' ||
typeof data.hasMore !== 'boolean'
) {
throw new Error('Malformed change list page');
}

const changes = data.changes.map((raw): TableChange => {
const c = raw as Record<string, unknown>;

if (
typeof c.subject !== 'string' ||
(c.kind !== 'created' && c.kind !== 'updated' && c.kind !== 'deleted') ||
typeof c.at !== 'number'
) {
throw new Error('Malformed change list entry');
}

const version =
c.version && typeof c.version === 'object'
? (c.version as Record<string, number>)
: null;

return { subject: c.subject, kind: c.kind, version, at: c.at };
});

return { changes, cursor: data.cursor, hasMore: data.hasMore };
}

/** `GET /changes` against `serverUrl`, signed by `agent` when given. */
export async function fetchTableChanges(
serverUrl: string,
agent: Agent | undefined,
table: string,
opts: TableChangesOptions = {},
fetchImpl: typeof fetch = fetch,
): Promise<TableChangesPage> {
const url = new URL('/changes', serverUrl);
url.searchParams.set('table', table);

if (opts.since) url.searchParams.set('since', opts.since);
if (opts.limit !== undefined) url.searchParams.set('limit', `${opts.limit}`);

// The server rebuilds the signed message from the full request URL.
const headers = agent
? await signRequest(url.toString(), agent, { Accept: 'application/json' })
: { Accept: 'application/json' };
const res = await fetchImpl(url.toString(), { headers });

if (res.status === 410) {
const body = await res.json().catch(() => ({}));
throw new TableChangesCursorExpiredError(body?.message);
}

if (!res.ok) {
const text = await res.text().catch(() => '');
throw new Error(
`Change list for ${table} failed (${res.status}): ${text.slice(0, 300)}`,
);
}

return parseTableChangesPage(await res.json());
}
1 change: 1 addition & 0 deletions docs/src/SUMMARY.md
Original file line number Diff line number Diff line change
Expand Up @@ -97,6 +97,7 @@
- [Concepts](commits/concepts.md)
- [Compared to](commits/compare.md)
- [Endpoints](endpoints.md)
- [Table change list](changes.md)
- [Collections, filtering, sorting](schema/collections.md)
- [Uploading and downloading files](files.md)

Expand Down
Loading