@atcute/tap 0.1.0

package/dist/types.d.ts

@@ -0,0 +1,56 @@
+import type { Did, Handle, Nsid, RecordKey, Tid } from '@atcute/lexicons/syntax';
+import type { CloseEvent, ErrorEvent, Options } from 'partysocket/ws';
+export type TapRecordAction = 'create' | 'update' | 'delete';
+export type TapRepoStatus = 'active' | 'takendown' | 'suspended' | 'deactivated' | 'deleted';
+export interface TapRecordEvent {
+    id: number;
+    type: 'record';
+    live: boolean;
+    did: Did;
+    rev: Tid;
+    collection: Nsid;
+    rkey: RecordKey;
+    action: TapRecordAction;
+    record?: Record<string, unknown>;
+    cid?: string;
+}
+export interface TapIdentityEvent {
+    id: number;
+    type: 'identity';
+    did: Did;
+    handle: Handle;
+    isActive: boolean;
+    status: TapRepoStatus;
+}
+export type TapEvent = TapRecordEvent | TapIdentityEvent;
+export interface RepoInfo {
+    did: Did;
+    handle: Handle;
+    state: string;
+    rev: Tid;
+    records: number;
+    error?: string;
+    retries?: number;
+}
+export interface TapClientOptions {
+    url: string | URL;
+    adminPassword?: string;
+    fetch?: typeof globalThis.fetch;
+}
+export interface TapSubscribeOptions {
+    /**
+     * whether to validate incoming events.
+     * @default true
+     */
+    validateEvents?: boolean;
+    onConnectionOpen?: (event: Event) => void;
+    onConnectionClose?: (event: CloseEvent) => void;
+    onConnectionError?: (event: ErrorEvent) => void;
+    onError?: (error: unknown) => void;
+    ws?: Options;
+}
+export interface TapSubscriptionMessage {
+    event: TapEvent;
+    ack: () => Promise<void>;
+}
+//# sourceMappingURL=types.d.ts.map

package/dist/types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../lib/types.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,GAAG,EAAE,MAAM,EAAE,IAAI,EAAE,SAAS,EAAE,GAAG,EAAE,MAAM,yBAAyB,CAAC;AACjF,OAAO,KAAK,EAAE,UAAU,EAAE,UAAU,EAAE,OAAO,EAAE,MAAM,gBAAgB,CAAC;AAEtE,MAAM,MAAM,eAAe,GAAG,QAAQ,GAAG,QAAQ,GAAG,QAAQ,CAAC;AAE7D,MAAM,MAAM,aAAa,GAAG,QAAQ,GAAG,WAAW,GAAG,WAAW,GAAG,aAAa,GAAG,SAAS,CAAC;AAE7F,MAAM,WAAW,cAAc;IAC9B,EAAE,EAAE,MAAM,CAAC;IACX,IAAI,EAAE,QAAQ,CAAC;IAEf,IAAI,EAAE,OAAO,CAAC;IACd,GAAG,EAAE,GAAG,CAAC;IACT,GAAG,EAAE,GAAG,CAAC;IACT,UAAU,EAAE,IAAI,CAAC;IACjB,IAAI,EAAE,SAAS,CAAC;IAChB,MAAM,EAAE,eAAe,CAAC;IACxB,MAAM,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IACjC,GAAG,CAAC,EAAE,MAAM,CAAC;CACb;AAED,MAAM,WAAW,gBAAgB;IAChC,EAAE,EAAE,MAAM,CAAC;IACX,IAAI,EAAE,UAAU,CAAC;IAEjB,GAAG,EAAE,GAAG,CAAC;IACT,MAAM,EAAE,MAAM,CAAC;IACf,QAAQ,EAAE,OAAO,CAAC;IAClB,MAAM,EAAE,aAAa,CAAC;CACtB;AAED,MAAM,MAAM,QAAQ,GAAG,cAAc,GAAG,gBAAgB,CAAC;AAEzD,MAAM,WAAW,QAAQ;IACxB,GAAG,EAAE,GAAG,CAAC;IACT,MAAM,EAAE,MAAM,CAAC;IACf,KAAK,EAAE,MAAM,CAAC;IACd,GAAG,EAAE,GAAG,CAAC;IACT,OAAO,EAAE,MAAM,CAAC;IAChB,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,OAAO,CAAC,EAAE,MAAM,CAAC;CACjB;AAED,MAAM,WAAW,gBAAgB;IAChC,GAAG,EAAE,MAAM,GAAG,GAAG,CAAC;IAClB,aAAa,CAAC,EAAE,MAAM,CAAC;IACvB,KAAK,CAAC,EAAE,OAAO,UAAU,CAAC,KAAK,CAAC;CAChC;AAED,MAAM,WAAW,mBAAmB;IACnC;;;OAGG;IACH,cAAc,CAAC,EAAE,OAAO,CAAC;IAEzB,gBAAgB,CAAC,EAAE,CAAC,KAAK,EAAE,KAAK,KAAK,IAAI,CAAC;IAC1C,iBAAiB,CAAC,EAAE,CAAC,KAAK,EAAE,UAAU,KAAK,IAAI,CAAC;IAChD,iBAAiB,CAAC,EAAE,CAAC,KAAK,EAAE,UAAU,KAAK,IAAI,CAAC;IAChD,OAAO,CAAC,EAAE,CAAC,KAAK,EAAE,OAAO,KAAK,IAAI,CAAC;IAEnC,EAAE,CAAC,EAAE,OAAO,CAAC;CACb;AAED,MAAM,WAAW,sBAAsB;IACtC,KAAK,EAAE,QAAQ,CAAC;IAChB,GAAG,EAAE,MAAM,OAAO,CAAC,IAAI,CAAC,CAAC;CACzB"}

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":["../lib/types.ts"],"names":[],"mappings":""}

package/dist/utils.d.ts

@@ -0,0 +1,2 @@
+export declare const formatAdminAuthHeader: (password: string) => string;
+//# sourceMappingURL=utils.d.ts.map

package/dist/utils.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"utils.d.ts","sourceRoot":"","sources":["../lib/utils.ts"],"names":[],"mappings":"AAGA,eAAO,MAAM,qBAAqB,8BAEjC,CAAC"}

package/dist/utils.js

@@ -0,0 +1,6 @@
+import { toBase64Pad } from '@atcute/multibase';
+import { encodeUtf8 } from '@atcute/uint8array';
+export const formatAdminAuthHeader = (password) => {
+    return `Basic ${toBase64Pad(encodeUtf8(`admin:${password}`))}`;
+};
+//# sourceMappingURL=utils.js.map

package/dist/utils.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"utils.js","sourceRoot":"","sources":["../lib/utils.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,WAAW,EAAE,MAAM,mBAAmB,CAAC;AAChD,OAAO,EAAE,UAAU,EAAE,MAAM,oBAAoB,CAAC;AAEhD,MAAM,CAAC,MAAM,qBAAqB,GAAG,CAAC,QAAgB,EAAU,EAAE,CAAC;IAClE,OAAO,SAAS,WAAW,CAAC,UAAU,CAAC,SAAS,QAAQ,EAAE,CAAC,CAAC,EAAE,CAAC;AAAA,CAC/D,CAAC"}

package/lib/dev-index.ts

@@ -0,0 +1,24 @@
+import { TapClient } from './tap-client.js';
+
+const tap = new TapClient({ url: 'http://localhost:2480' });
+
+const subscription = tap.subscribe({
+	onConnectionOpen() {
+		console.log(`ws open`);
+	},
+	onConnectionClose() {
+		console.log(`ws close`);
+	},
+	onConnectionError(ev) {
+		console.log(`ws error`, ev);
+	},
+	onError(err) {
+		console.error('tap subscription error', err);
+	},
+});
+
+for await (const { event, ack } of subscription) {
+	console.log(event);
+
+	await ack();
+}

package/lib/index.ts

@@ -0,0 +1,5 @@
+export { TapClient } from './tap-client.js';
+export { TapSubscription } from './tap-subscription.js';
+
+export * as defs from './typedefs.js';
+export type * from './types.js';

package/lib/tap-client.ts

@@ -0,0 +1,114 @@
+import { defs as identityDefs, type DidDocument } from '@atcute/identity';
+
+import type { Did } from '@atcute/lexicons';
+
+import { TapSubscription } from './tap-subscription.js';
+import { repoInfoSchema } from './typedefs.js';
+import type { RepoInfo, TapClientOptions, TapSubscribeOptions } from './types.js';
+import { formatAdminAuthHeader } from './utils.js';
+
+export class TapClient {
+	#url: URL;
+	#fetch: typeof globalThis.fetch;
+	#adminPassword?: string;
+	#authHeader?: string;
+
+	constructor(options: TapClientOptions) {
+		const url = typeof options.url === 'string' ? new URL(options.url) : new URL(options.url);
+
+		if (url.protocol !== 'http:' && url.protocol !== 'https:') {
+			throw new Error(`invalid url protocol, expected http: or https:, got ${url.protocol}`);
+		}
+
+		this.#url = url;
+		this.#fetch = options.fetch ?? fetch;
+
+		if (options.adminPassword) {
+			this.#adminPassword = options.adminPassword;
+			this.#authHeader = formatAdminAuthHeader(options.adminPassword);
+		}
+	}
+
+	subscribe(options?: TapSubscribeOptions): TapSubscription {
+		const wsUrl = new URL(this.#url);
+		wsUrl.protocol = wsUrl.protocol === 'https:' ? 'wss:' : 'ws:';
+		wsUrl.pathname = '/channel';
+
+		return new TapSubscription({
+			url: wsUrl.toString(),
+			adminPassword: this.#adminPassword,
+			...options,
+		});
+	}
+
+	async addRepos(dids: Did[]): Promise<void> {
+		const response = await this.#fetch(new URL('/repos/add', this.#url), {
+			method: 'POST',
+			headers: this.#getHeaders(),
+			body: JSON.stringify({ dids }),
+		});
+
+		await response.body?.cancel();
+		if (!response.ok) {
+			throw new Error(`failed to add repos: ${response.status} ${response.statusText}`);
+		}
+	}
+
+	async removeRepos(dids: Did[]): Promise<void> {
+		const response = await this.#fetch(new URL('/repos/remove', this.#url), {
+			method: 'POST',
+			headers: this.#getHeaders(),
+			body: JSON.stringify({ dids }),
+		});
+
+		await response.body?.cancel();
+		if (!response.ok) {
+			throw new Error(`failed to remove repos: ${response.status} ${response.statusText}`);
+		}
+	}
+
+	async resolveDid(did: Did): Promise<DidDocument | null> {
+		const response = await this.#fetch(new URL(`/resolve/${did}`, this.#url), {
+			method: 'GET',
+			headers: this.#getHeaders(),
+		});
+
+		if (response.status === 404) {
+			await response.body?.cancel();
+			return null;
+		}
+
+		if (!response.ok) {
+			await response.body?.cancel();
+			throw new Error(`failed to resolve did: ${response.status} ${response.statusText}`);
+		}
+
+		return identityDefs.didDocument.parse(await response.json());
+	}
+
+	async getRepoInfo(did: Did): Promise<RepoInfo> {
+		const response = await this.#fetch(new URL(`/info/${did}`, this.#url), {
+			method: 'GET',
+			headers: this.#getHeaders(),
+		});
+
+		if (!response.ok) {
+			await response.body?.cancel();
+			throw new Error(`failed to get repo info: ${response.status} ${response.statusText}`);
+		}
+
+		return repoInfoSchema.parse(await response.json());
+	}
+
+	#getHeaders(): Record<string, string> {
+		const headers: Record<string, string> = {
+			'Content-Type': 'application/json',
+		};
+
+		if (this.#authHeader) {
+			headers['Authorization'] = this.#authHeader;
+		}
+
+		return headers;
+	}
+}

package/lib/tap-subscription.ts

@@ -0,0 +1,267 @@
+import { EventIterator } from '@mary-ext/event-iterator';
+import { SimpleEventEmitter } from '@mary-ext/simple-event-emitter';
+import { WebSocket as ReconnectingWebSocket } from 'partysocket';
+
+import type { ReadonlyDeep } from 'type-fest';
+
+import { decodeUtf8From } from '@atcute/uint8array';
+
+import { flattenTapEvent, tapEventWireSchema } from './typedefs.js';
+import type { TapEvent, TapSubscribeOptions, TapSubscriptionMessage } from './types.js';
+import { formatAdminAuthHeader } from './utils.js';
+
+export interface TapSubscriptionOptions extends TapSubscribeOptions {
+	url: string;
+	adminPassword?: string;
+}
+
+type BufferedAck = {
+	id: number;
+	promise: Promise<void>;
+	resolve: (value: void) => void;
+	reject: (reason?: unknown) => void;
+};
+
+const PARSE_OPTIONS = { mode: 'passthrough' } as const;
+
+export class TapSubscription {
+	#listening = 0;
+	#ws?: ReconnectingWebSocket;
+
+	#emitter = new SimpleEventEmitter<[message: TapSubscriptionMessage]>();
+	#bufferedAcks: BufferedAck[] = [];
+
+	#options: TapSubscriptionOptions;
+	#closed = false;
+
+	constructor(options: TapSubscriptionOptions) {
+		this.#options = options;
+	}
+
+	#sendAck(id: number): boolean {
+		const ws = this.#ws;
+		if (ws === undefined) {
+			return false;
+		}
+
+		if (ws.readyState !== 1) {
+			return false;
+		}
+
+		ws.send(JSON.stringify({ type: 'ack', id }));
+		return true;
+	}
+
+	async #ackEvent(id: number): Promise<void> {
+		if (this.#closed) {
+			throw new Error(`tap subscription is closed`);
+		}
+
+		try {
+			if (this.#sendAck(id)) {
+				return;
+			}
+		} catch {
+			// fall through to buffering
+		}
+
+		const { promise, resolve, reject } = Promise.withResolvers<void>();
+		this.#bufferedAcks.push({ id, promise, resolve, reject });
+		return await promise;
+	}
+
+	#flushBufferedAcks() {
+		while (this.#bufferedAcks.length > 0) {
+			const ack = this.#bufferedAcks[0];
+			if (ack === undefined) {
+				return;
+			}
+
+			try {
+				if (!this.#sendAck(ack.id)) {
+					return;
+				}
+
+				ack.resolve(undefined);
+				this.#bufferedAcks = this.#bufferedAcks.slice(1);
+			} catch (err) {
+				this.#options.onError?.(err);
+				return;
+			}
+		}
+	}
+
+	#create() {
+		if (this.#ws !== undefined) {
+			return;
+		}
+
+		const {
+			url,
+			adminPassword,
+			ws: wsOptions,
+			validateEvents = true,
+			onConnectionClose,
+			onConnectionError,
+			onConnectionOpen,
+			onError,
+		} = this.#options;
+
+		const emitter = this.#emitter;
+
+		const authHeader = adminPassword ? formatAdminAuthHeader(adminPassword) : undefined;
+
+		const mergedWsOptions =
+			authHeader !== undefined && wsOptions?.WebSocket === undefined
+				? {
+						...wsOptions,
+						WebSocket: createAuthedWebSocket(authHeader),
+					}
+				: wsOptions;
+
+		const ws = new ReconnectingWebSocket(() => url, null, mergedWsOptions);
+		this.#ws = ws;
+
+		ws.binaryType = 'arraybuffer';
+
+		ws.onclose = onConnectionClose ?? null;
+		ws.onerror = onConnectionError ?? null;
+
+		ws.onopen = (ev) => {
+			this.#flushBufferedAcks();
+			onConnectionOpen?.(ev);
+		};
+
+		ws.onmessage = (ev) => {
+			let raw: unknown;
+			try {
+				const data = toMessageText(ev.data);
+				raw = JSON.parse(data);
+			} catch (err) {
+				onError?.(new Error(`failed to parse tap message`, { cause: err }));
+				return;
+			}
+
+			let evt: TapEvent;
+			if (validateEvents) {
+				const result = tapEventWireSchema.try(raw, PARSE_OPTIONS);
+				if (!result.ok) {
+					onError?.(result);
+					return;
+				}
+
+				evt = flattenTapEvent(result.value);
+			} else {
+				try {
+					evt = flattenTapEvent(raw as any);
+				} catch (err) {
+					onError?.(err);
+					return;
+				}
+			}
+
+			let acked = false;
+			let ackPromise: Promise<void> | undefined;
+
+			emitter.emit({
+				event: evt,
+				ack: () => {
+					if (!acked) {
+						acked = true;
+						ackPromise = this.#ackEvent(evt.id);
+					}
+					return ackPromise!;
+				},
+			});
+		};
+	}
+
+	#destroy() {
+		const ws = this.#ws;
+		if (ws) {
+			ws.close();
+			this.#ws = undefined;
+		}
+
+		this.#closed = true;
+
+		if (this.#bufferedAcks.length > 0) {
+			const err = new Error(`tap subscription closed before ack was sent`);
+			for (const ack of this.#bufferedAcks) {
+				ack.reject(err);
+			}
+			this.#bufferedAcks = [];
+		}
+	}
+
+	[Symbol.asyncIterator]() {
+		return new EventIterator<TapSubscriptionMessage>((emit) => {
+			if (this.#listening === 0) {
+				this.#closed = false;
+				this.#create();
+			}
+
+			this.#listening++;
+			this.#emitter.subscribe(emit);
+
+			return () => {
+				if (this.#listening === 1) {
+					this.#destroy();
+				}
+
+				this.#listening--;
+				this.#emitter.unsubscribe(emit);
+			};
+		});
+	}
+
+	getOptions(): ReadonlyDeep<TapSubscriptionOptions> {
+		return this.#options;
+	}
+
+	updateOptions(options: Partial<TapSubscriptionOptions>): void {
+		this.#options = { ...this.#options, ...options };
+
+		if (this.#ws !== undefined) {
+			this.#destroy();
+			this.#closed = false;
+			this.#create();
+		}
+	}
+}
+
+const toMessageText = (data: unknown): string => {
+	if (typeof data === 'string') {
+		return data;
+	}
+
+	if (data instanceof ArrayBuffer) {
+		return decodeUtf8From(new Uint8Array(data));
+	}
+
+	if (ArrayBuffer.isView(data)) {
+		return decodeUtf8From(new Uint8Array(data.buffer, data.byteOffset, data.byteLength));
+	}
+
+	return String(data);
+};
+
+const createAuthedWebSocket = (authorization: string) => {
+	const WebSocketCtor = WebSocket as unknown as {
+		new (
+			url: string | URL,
+			protocols?: string | string[],
+			options?: { headers?: Record<string, string> },
+		): WebSocket;
+	};
+
+	return class AuthedWebSocket extends WebSocketCtor {
+		constructor(url: string | URL, protocols?: string | string[]) {
+			super(url, protocols as any, {
+				headers: {
+					Authorization: authorization,
+				},
+			});
+		}
+	};
+};

package/lib/typedefs.ts

@@ -0,0 +1,102 @@
+import * as v from '@badrap/valita';
+
+import { isDid, isHandle, isNsid, isRecordKey, isTid } from '@atcute/lexicons/syntax';
+
+import type * as t from './types.js';
+
+const didString = v.string().assert(isDid, `must be a did`);
+const handleString = v.string().assert(isHandle, `must be a handle`);
+const nsidString = v.string().assert(isNsid, `must be an nsid`);
+const rkeyString = v.string().assert(isRecordKey, `must be a record key`);
+const tidString = v.string().assert(isTid, `must be a tid`);
+
+const integer = v
+	.number()
+	.assert((input) => input >= 0 && Number.isSafeInteger(input), `must be a nonnegative integer`);
+
+const recordEventDataSchema = v.object({
+	did: didString,
+	rev: tidString,
+	collection: nsidString,
+	rkey: rkeyString,
+	action: v.union(v.literal('create'), v.literal('update'), v.literal('delete')),
+	record: v.record(v.unknown()).optional(),
+	cid: v.string().optional(),
+	live: v.boolean(),
+});
+
+const identityEventDataSchema = v.object({
+	did: didString,
+	handle: handleString,
+	is_active: v.boolean(),
+	status: v.union(
+		v.literal('active'),
+		v.literal('takendown'),
+		v.literal('suspended'),
+		v.literal('deactivated'),
+		v.literal('deleted'),
+	),
+});
+
+export const tapRecordEventWireSchema = v.object({
+	id: integer,
+	type: v.literal('record'),
+	record: recordEventDataSchema,
+});
+
+export const tapIdentityEventWireSchema = v.object({
+	id: integer,
+	type: v.literal('identity'),
+	identity: identityEventDataSchema,
+});
+
+export const tapEventWireSchema = v.union(tapRecordEventWireSchema, tapIdentityEventWireSchema);
+
+export const repoInfoSchema: v.Type<t.RepoInfo> = v.object({
+	did: didString,
+	handle: handleString,
+	state: v.string(),
+	rev: tidString,
+	records: integer,
+	error: v.string().optional(),
+	retries: integer.optional(),
+});
+
+export const flattenTapEvent = (wire: v.Infer<typeof tapEventWireSchema>): t.TapEvent => {
+	switch (wire.type) {
+		case 'identity': {
+			return {
+				id: wire.id,
+				type: 'identity',
+
+				did: wire.identity.did,
+				handle: wire.identity.handle,
+				isActive: wire.identity.is_active,
+				status: wire.identity.status,
+			};
+		}
+
+		case 'record': {
+			return {
+				id: wire.id,
+				type: 'record',
+				live: wire.record.live,
+
+				rev: wire.record.rev,
+				did: wire.record.did,
+				collection: wire.record.collection,
+				rkey: wire.record.rkey,
+				cid: wire.record.cid,
+				action: wire.record.action,
+				record: wire.record.record,
+			};
+		}
+
+		default: {
+			wire satisfies never;
+
+			const obj = wire as any;
+			throw new Error(`unknown "${obj.type}" type`);
+		}
+	}
+};

package/lib/types.ts

@@ -0,0 +1,68 @@
+import type { Did, Handle, Nsid, RecordKey, Tid } from '@atcute/lexicons/syntax';
+import type { CloseEvent, ErrorEvent, Options } from 'partysocket/ws';
+
+export type TapRecordAction = 'create' | 'update' | 'delete';
+
+export type TapRepoStatus = 'active' | 'takendown' | 'suspended' | 'deactivated' | 'deleted';
+
+export interface TapRecordEvent {
+	id: number;
+	type: 'record';
+
+	live: boolean;
+	did: Did;
+	rev: Tid;
+	collection: Nsid;
+	rkey: RecordKey;
+	action: TapRecordAction;
+	record?: Record<string, unknown>;
+	cid?: string;
+}
+
+export interface TapIdentityEvent {
+	id: number;
+	type: 'identity';
+
+	did: Did;
+	handle: Handle;
+	isActive: boolean;
+	status: TapRepoStatus;
+}
+
+export type TapEvent = TapRecordEvent | TapIdentityEvent;
+
+export interface RepoInfo {
+	did: Did;
+	handle: Handle;
+	state: string;
+	rev: Tid;
+	records: number;
+	error?: string;
+	retries?: number;
+}
+
+export interface TapClientOptions {
+	url: string | URL;
+	adminPassword?: string;
+	fetch?: typeof globalThis.fetch;
+}
+
+export interface TapSubscribeOptions {
+	/**
+	 * whether to validate incoming events.
+	 * @default true
+	 */
+	validateEvents?: boolean;
+
+	onConnectionOpen?: (event: Event) => void;
+	onConnectionClose?: (event: CloseEvent) => void;
+	onConnectionError?: (event: ErrorEvent) => void;
+	onError?: (error: unknown) => void;
+
+	ws?: Options;
+}
+
+export interface TapSubscriptionMessage {
+	event: TapEvent;
+	ack: () => Promise<void>;
+}

package/lib/utils.ts

@@ -0,0 +1,6 @@
+import { toBase64Pad } from '@atcute/multibase';
+import { encodeUtf8 } from '@atcute/uint8array';
+
+export const formatAdminAuthHeader = (password: string): string => {
+	return `Basic ${toBase64Pad(encodeUtf8(`admin:${password}`))}`;
+};