@wovin/core 0.2.0 → 0.3.0

package/src/applog/datom-types.ts

@@ -25,8 +25,14 @@ export type CidString = Tagged<string, CID>
 export type IpnsString = Tagged<CidString, 'IPNS'>
 export type AgentID = EntityID
 export type Attribute = string
-export type ApplogValue = string | boolean | number | null // TODO: use Tagged types
-// ? allow objects? or just as serialized strings? Or serialize everything anyways?
+// JSON-serializable value space for a datom's `vl` field.
+export type JsonPrimitive = string | boolean | number | null
+export interface JsonObject {
+	[key: string]: JsonValue
+}
+export type JsonArray = JsonValue[]
+export type JsonValue = JsonPrimitive | JsonObject | JsonArray
+export type ApplogValue = JsonValue // TODO: use Tagged types
 
 export interface Atom {
 	en: EntityID
@@ -112,18 +118,31 @@ type MapKeysStripPrefix<SELECT extends string, TPrefix extends string> = {
 }
 
 FormatRegistry.Set('CID', (value) => !!value.match(isCID))
-export const CIDTB = Type.String({ format: 'CID' })
+export const CIDTB = Type.String({ pattern: isCID.source })
 export type CIDTB = Static<typeof EntityID>
 
 const isURL = /^http([s]?):\/\/.*\..*/
 FormatRegistry.Set('URL', (value) => !!value.match(isURL))
-export const URL = Type.String({ format: 'URL' })
+export const URL = Type.String({ pattern: isURL.source })
 export type URL = Static<typeof URL>
 
+// Recursive JSON value: primitives plus nested arrays/objects (mirrors ApplogValue / JsonValue).
+export const JsonValueTB = Type.Recursive(This =>
+	Type.Union([
+		Type.String(),
+		Type.Number(),
+		Type.Boolean(),
+		Type.Null(),
+		Type.Array(This),
+		Type.Record(Type.String(), This),
+	])
+)
+export type JsonValueTB = Static<typeof JsonValueTB>
+
 export const AppLogNoCidTB = Type.Object({
 	en: EntityID, // EntityID
 	at: Type.String(), // Attribute
-	vl: Nullable(Type.Union([Type.String(), Type.Boolean(), Type.Number()])), // TODO refactor to semantic typesafe ApplogValue
+	vl: JsonValueTB, // ApplogValue (JSON-serializable: primitives, arrays, objects)
 	ts: Type.String(), // Timestamp
 	ag: Type.String(), // AgentHash
 	pv: Nullable(CIDTB), // CidString

package/src/applog/object-values.test.ts

@@ -0,0 +1,106 @@
+/**
+ * Tests for JSON object/array support in a datom's `vl` field.
+ *
+ * Covers: schema validation, deep-equality dedup, value-index keying,
+ * matcher semantics (deep-eq literal match, anyOf membership, predicate
+ * for nested access) and the fail-loud behaviour for bare-array patterns.
+ */
+import { describe, expect, it } from 'vitest'
+import { isValidApplog } from './datom-types.ts'
+import { matchPartStatic, valueEq, valueKey } from './applog-utils.ts'
+import { anyOf } from '../query/matchers.ts'
+import { finalizeApplogForInsert } from './applog-helpers.ts'
+import { applogsByAttrValue } from '../thread/indexes.ts'
+import { ThreadInMemory } from '../thread/writeable.ts'
+import type { Applog, ApplogForInsert } from './datom-types.ts'
+
+let tsCounter = 0
+function makeLog(spec: Pick<ApplogForInsert, 'en' | 'at' | 'vl'> & Partial<Applog>): Applog {
+	tsCounter++
+	return finalizeApplogForInsert({
+		ts: new Date(1700000000000 + tsCounter * 1000).toISOString(),
+		pv: null,
+		ag: 'testAgent',
+		...spec,
+	} as ApplogForInsert, {})
+}
+
+describe('object/array applog values', () => {
+	it('schema accepts nested objects and arrays as vl', () => {
+		const obj = makeLog({ en: 'e1', at: 'config', vl: { theme: 'dark', nested: { n: [1, 2, 3] } } })
+		const arr = makeLog({ en: 'e1', at: 'tags', vl: ['a', 'b', { x: 1 }] })
+		expect(isValidApplog(obj)).toBe(true)
+		expect(isValidApplog(arr)).toBe(true)
+		// primitives still valid
+		expect(isValidApplog(makeLog({ en: 'e1', at: 'name', vl: 'hi' }))).toBe(true)
+		expect(isValidApplog(makeLog({ en: 'e1', at: 'n', vl: null }))).toBe(true)
+	})
+
+	it('valueEq compares object/array values by structure', () => {
+		expect(valueEq({ a: 1, b: 2 }, { b: 2, a: 1 })).toBe(true)
+		expect(valueEq([1, 2, 3], [1, 2, 3])).toBe(true)
+		expect(valueEq({ a: 1 }, { a: 2 })).toBe(false)
+		expect(valueEq('x', 'x')).toBe(true)
+	})
+
+	it('valueKey canonicalizes objects (key-order independent) without colliding with strings', () => {
+		expect(valueKey({ a: 1, b: 2 })).toBe(valueKey({ b: 2, a: 1 }))
+		// a literal string equal to an object's serialization must NOT collide
+		expect(valueKey('{"a":1}')).not.toBe(valueKey({ a: 1 }))
+		// primitives pass through as their own value
+		expect(valueKey('hi')).toBe('hi')
+		expect(valueKey(42)).toBe(42)
+		expect(valueKey(null)).toBe(null)
+	})
+
+	it('hasApplogWithDiffTs matches structurally-equal object values (deep, key-order independent)', () => {
+		const existing = makeLog({ en: 'e1', at: 'config', vl: { a: 1, b: 2 } })
+		const thread = ThreadInMemory.fromArray([existing], 'dedup')
+		// same en/at/ag, deep-equal vl with different key order → recognised as the same datom
+		expect(thread.hasApplogWithDiffTs({ en: 'e1', at: 'config', vl: { b: 2, a: 1 }, ag: 'testAgent' } as any)).toBeTruthy()
+		// a structurally different value is NOT matched
+		expect(thread.hasApplogWithDiffTs({ en: 'e1', at: 'config', vl: { a: 9 }, ag: 'testAgent' } as any)).toBeFalsy()
+	})
+
+	it('applogsByAttrValue groups structurally-equal object values into one bucket', () => {
+		const logs = [
+			makeLog({ en: 'e1', at: 'config', vl: { a: 1, b: 2 } }),
+			makeLog({ en: 'e2', at: 'config', vl: { b: 2, a: 1 } }),
+			makeLog({ en: 'e3', at: 'config', vl: { a: 9 } }),
+		]
+		const thread = ThreadInMemory.fromArray(logs, 'idx')
+		const index = applogsByAttrValue(thread, 'config').value
+		expect(index.get(valueKey({ a: 1, b: 2 }))).toHaveLength(2)
+		expect(index.get(valueKey({ a: 9 }))).toHaveLength(1)
+	})
+
+	it('matchPartStatic matches a literal object value by deep equality', () => {
+		expect(matchPartStatic('vl', { a: 1, b: 2 }, { b: 2, a: 1 })).toBe(true)
+		expect(matchPartStatic('vl', { a: 1 }, { a: 2 })).toBe(false)
+	})
+
+	it('matching a literal array value requires a predicate (a bare array throws)', () => {
+		// bare arrays are reserved/rejected, so an array value is matched via a predicate
+		expect(matchPartStatic('vl', (v: any) => valueEq(v, [1, 2, 3]), [1, 2, 3])).toBe(true)
+		expect(() => matchPartStatic('vl', [1, 2, 3] as any, [1, 2, 3])).toThrow(/anyOf/)
+	})
+
+	it('anyOf(...) provides set-membership and matches via matchPartStatic', () => {
+		expect(matchPartStatic('at', anyOf('a', 'b', 'c'), 'b')).toBe(true)
+		expect(matchPartStatic('at', anyOf('a', 'b'), 'z')).toBe(false)
+	})
+
+	it('a predicate matcher can reach into nested object values', () => {
+		const isDark = (v: any) => v?.theme === 'dark'
+		expect(matchPartStatic('vl', isDark, { theme: 'dark' })).toBe(true)
+		expect(matchPartStatic('vl', isDark, { theme: 'light' })).toBe(false)
+	})
+
+	it('a bare array pattern fails loudly rather than matching ambiguously', () => {
+		expect(() => matchPartStatic('at', ['a', 'b'] as any, 'a')).toThrow(/anyOf/)
+	})
+
+	it('anyOf rejects object/array members (would silently never match)', () => {
+		expect(() => anyOf({ a: 1 } as any)).toThrow(/object\/array/)
+	})
+})

package/src/ipfs/car.ts

@@ -72,8 +72,14 @@ export async function decodePubFromBlocks(
 			pubLogsArray = await unchunkApplogsBlock(applogsBlock, blockStore)
 			// Info only from first (most recent) snapshot
 			if (!firstInfo) {
-				firstInfo = (await getDecodedBlock(blockStore, root.info)) as SnapBlockLogs
-				DEBUG(`new format - infoLogs`, firstInfo.logs.map(l => ({ [l.toString()]: l })))
+				const decoded = (await getDecodedBlock(blockStore, root.info)) as SnapBlockLogs
+				if (decoded) {
+					firstInfo = decoded
+					DEBUG(`new format - infoLogs`, firstInfo.logs.map(l => ({ [l.toString()]: l })))
+				} else {
+					WARN(`[decodePubFromBlocks] info block not found for ${root.info}, using empty info`)
+					firstInfo = { logs: [] }
+				}
 			}
 			// TODO: verify signatures
 		} else {

package/src/ipns/gateway-resolver.ts

@@ -0,0 +1,63 @@
+import { CID } from 'multiformats/cid'
+import { Logger } from 'besonders-logger'
+
+const { WARN, LOG, DEBUG } = Logger.setup(Logger.INFO) // eslint-disable-line unused-imports/no-unused-vars
+
+/**
+ * Resolve an IPNS name to a CID using a public IPFS gateway's HTTP HEAD response.
+ *
+ * Mechanism: per the IPFS HTTP Gateway spec, `HEAD <gateway>/ipns/<name>/` returns the
+ * IPNS-resolved root CID in the `X-Ipfs-Roots` response header (space-separated, ordered
+ * from root to leaf). The first entry is the IPNS-resolved CID.
+ *
+ * This works against any gateway that follows the spec and exposes CORS for HEAD
+ * (most public gateways do, e.g. ipfs.zt.ax, ipfs.io, dweb.link).
+ *
+ * The legacy w3name HTTP endpoint (`GET <base>/name/<ipns>` returning `{value: "/ipfs/<cid>"}`)
+ * is also supported here for back-compat with self-hosted w3name-like services — but the
+ * X-Ipfs-Roots path is preferred since it's the standardised gateway mechanism.
+ *
+ * @param ipns - The IPNS name (k51... string)
+ * @param gateways - List of gateway base URLs (e.g. `["https://ipfs.zt.ax"]`)
+ * @returns The resolved CID, or null if no gateway could resolve the name
+ */
+export async function resolveIPNSViaGateway(ipns: string, gateways: string[]): Promise<CID | null> {
+	if (!ipns.startsWith('k51')) return null // only IPNS libp2p-key names go through gateway
+	if (!gateways?.length) return null
+
+	for (const rawGateway of gateways) {
+		const gateway = rawGateway.replace(/\/+$/, '')
+		const url = `${gateway}/ipns/${ipns}/`
+		try {
+			DEBUG(`[resolveIPNSViaGateway] HEAD ${url}`)
+			const response = await fetch(url, { method: 'HEAD' })
+			if (!response.ok) {
+				DEBUG(`[resolveIPNSViaGateway] ${gateway} returned ${response.status}`)
+				continue
+			}
+			const roots = response.headers.get('x-ipfs-roots') ?? response.headers.get('X-Ipfs-Roots')
+			if (roots) {
+				const first = roots.split(/[\s,]+/)[0]?.trim()
+				if (first) {
+					const cid = CID.parse(first)
+					DEBUG(`[resolveIPNSViaGateway] resolved via ${gateway} x-ipfs-roots:`, cid.toString())
+					return cid
+				}
+			}
+			// Some gateways omit X-Ipfs-Roots but put the CID in etag (e.g. `<cid>.dag-json`)
+			const etag = response.headers.get('etag')
+			if (etag) {
+				const m = etag.match(/^"?([a-z0-9]+)/i)
+				if (m) {
+					const cid = CID.parse(m[1])
+					DEBUG(`[resolveIPNSViaGateway] resolved via ${gateway} etag:`, cid.toString())
+					return cid
+				}
+			}
+			WARN(`[resolveIPNSViaGateway] ${gateway} returned 200 but no usable CID header`)
+		} catch (err) {
+			WARN(`[resolveIPNSViaGateway] ${gateway} failed:`, err)
+		}
+	}
+	return null
+}

package/src/ipns/ipns-record.ts

@@ -5,9 +5,9 @@ import { base64pad } from 'multiformats/bases/base64'
 import type { CID } from 'multiformats/cid'
 
 export interface SignedIPNSRecord {
-	recordBytes: Uint8Array   // marshalled protobuf, signed — the wire format
-	ipnsName: string          // k51... string
-	value: string             // /ipfs/<cid>
+	recordBytes: Uint8Array // marshalled protobuf, signed — the wire format
+	ipnsName: string // k51... string
+	value: string // /ipfs/<cid>
 	sequence: bigint
 }
 
@@ -37,16 +37,31 @@ export async function createSignedIPNSRecord(
 
 export { unmarshalIPNSRecord }
 
-/** A target that can receive a signed IPNS record */
+/**
+ * A target that can receive a signed IPNS record, advertise its current
+ * sequence, or both.
+ *
+ * - `publish` is called by `publishIPNSRecord` to actually store the record
+ *   on the target's backing service. Targets without `publish` are skipped
+ *   during the fan-out (e.g. a sequence-only source).
+ * - `resolveSequence` is consulted by `publishIPNSRecord` to compute the
+ *   next IPNS sequence. The first target to return a value (including
+ *   `null` for "never published") wins. Throw to indicate a transient
+ *   error — the caller will try the next target.
+ *
+ * Most real targets (e.g. a storage connector) provide both. A simple
+ * "track sequence in localStorage" target only needs `resolveSequence`.
+ */
 export interface IPNSPublishTarget {
 	name: string
-	publish(ipnsName: string, recordBytes: Uint8Array): Promise<void>
+	publish?(ipnsName: string, recordBytes: Uint8Array): Promise<void>
+	resolveSequence?(ipnsName: string): Promise<bigint | null>
 }
 
 /**
- * Resolve current IPNS sequence number from a naming service.
+ * Resolve the current IPNS sequence from a generic naming service.
  * Returns null if the name was never published (404).
- * Throws on network/server errors.
+ * Throws on network/server errors so the caller can try a different target.
  */
 export async function resolveIPNSSequence(
 	nameServiceUrl: string,
@@ -75,41 +90,77 @@ export async function resolveIPNSSequence(
 		return entry.sequence
 	}
 
-	// Some servers return value but not raw record — can't get sequence
+	// Server only returned a value, no raw record — can't know the exact sequence.
+	// Most services still accept this as "previous published"; treat as seq=0n.
 	return 0n
 }
 
 /**
  * Create a signed IPNS record and publish to all configured targets.
- * Resolves sequence from sequenceServiceUrl, creates record once, fans out.
- * Throws if ALL targets fail; warns on partial failure.
+ *
+ * Sequence resolution: walks `targets` in order asking each one with a
+ * `resolveSequence` method. The first target to successfully return a value
+ * (including `null` for "never published") determines the next sequence.
+ * If every target throws or none supports `resolveSequence`, falls back to 0n.
+ *
+ * Publish fan-out: only targets with a `publish` method are called.
+ * Throws if every publish-capable target fails; partial failures are logged.
  */
 export async function publishIPNSRecord(
 	privateKey: Uint8Array,
 	cid: CID,
 	targets: IPNSPublishTarget[],
-	sequenceServiceUrl = 'https://name.web3.storage',
 ): Promise<SignedIPNSRecord> {
 	const ipnsName = ipnsNameFromPrivateKey(privateKey)
-	const currentSeq = await resolveIPNSSequence(sequenceServiceUrl, ipnsName)
-	const sequence = currentSeq != null ? currentSeq + 1n : 0n
+	const sequence = await pickNextSequence(ipnsName, targets)
 	const signed = await createSignedIPNSRecord(privateKey, cid, sequence)
 
+	const publishTargets = targets.filter(t => typeof t.publish === 'function')
+	if (publishTargets.length === 0) {
+		throw new Error('No publish-capable targets supplied to publishIPNSRecord')
+	}
+
 	const results = await Promise.allSettled(
-		targets.map(t => t.publish(ipnsName, signed.recordBytes))
+		publishTargets.map(t => t.publish!(ipnsName, signed.recordBytes)),
 	)
 	const failures = results
-		.map((r, i) => ({ r, name: targets[i].name }))
+		.map((r, i) => ({ r, name: publishTargets[i].name }))
 		.filter(({ r }) => r.status === 'rejected') as { r: PromiseRejectedResult; name: string }[]
 
-	if (failures.length > 0 && failures.length < targets.length) {
+	if (failures.length > 0 && failures.length < publishTargets.length) {
 		// Partial failure — log but don't throw
 		for (const { r, name } of failures) {
 			console.warn(`[publishIPNSRecord] target '${name}' failed:`, r.reason)
 		}
-	} else if (failures.length === targets.length) {
+	} else if (failures.length === publishTargets.length) {
 		throw new Error(`All IPNS publish targets failed: ${failures.map(({ r, name }) => `${name}: ${r.reason}`).join('; ')}`)
 	}
 
 	return signed
 }
+
+/**
+ * Walk targets, asking each to resolve the current IPNS sequence. First success wins.
+ * Falls back to 0n if no target can answer.
+ */
+async function pickNextSequence(
+	ipnsName: string,
+	targets: IPNSPublishTarget[],
+): Promise<bigint> {
+	const capable = targets.filter(t => typeof t.resolveSequence === 'function')
+	if (capable.length === 0) {
+		return 0n
+	}
+
+	for (const target of capable) {
+		try {
+			const current = await target.resolveSequence!(ipnsName)
+			return current == null ? 0n : current + 1n
+		} catch (err) {
+			console.warn(`[publishIPNSRecord] target '${target.name}' sequence resolve failed:`, err)
+		}
+	}
+
+	console.warn(`[publishIPNSRecord] no target could resolve sequence for ${ipnsName} — starting at 0n`)
+	return 0n
+}

package/src/ipns/ipns-w3name.ts

@@ -0,0 +1,103 @@
+import type { IPNSPublishTarget } from '@wovin/core/ipns'
+import { Logger } from 'besonders-logger'
+import { base64pad } from 'multiformats/bases/base64'
+import { CID } from 'multiformats/cid'
+import * as W3Name from 'w3name'
+
+const { WARN, LOG, DEBUG, ERROR } = Logger.setup(Logger.INFO)
+
+/**
+ * Try to resolve IPNS name to get existing revision.
+ * Returns null if record doesn't exist (404).
+ * Throws on network errors or server errors.
+ *
+ * This does a custom HTTP check first to distinguish 404 from network errors,
+ * then delegates to W3Name.resolve() for validation if record exists.
+ */
+async function tryResolveIPNS(ipns: W3Name.WritableName): Promise<W3Name.Revision | null> {
+	const url = `https://name.web3.storage/name/${ipns.toString()}`
+
+	let response: Response
+	try {
+		response = await fetch(url, { signal: AbortSignal.timeout(30_000) })
+	} catch (err) {
+		// Network error (no connection, DNS failure, etc.)
+		throw ERROR('[w3name] Network error resolving IPNS:', err)
+	}
+
+	// 404 = record never published
+	if (response.status === 404) {
+		DEBUG('[w3name] IPNS record not found (never published):', ipns.toString())
+		return null
+	}
+
+	// Other HTTP errors (5xx server error, etc.)
+	if (!response.ok) {
+		throw ERROR(`[w3name] HTTP ${response.status} resolving IPNS:`, response.statusText)
+	}
+
+	// Success - use W3Name.resolve to get validated Revision
+	// (We could parse the record ourselves, but W3Name does validation/signature checks)
+	const existing = await W3Name.resolve(ipns)
+	return existing
+}
+
+/**
+ * Publish CID to IPNS, automatically handling increment vs v0.
+ * Returns the revision for further processing (e.g., Kubo integration).
+ */
+export async function publishIPNS(ipnsPrivateKey: Uint8Array, cid: CID): Promise<W3Name.Revision> {
+	const TIMEOUT_MS = 30_000
+	const timeout = new Promise<never>((_, reject) =>
+		setTimeout(() => reject(new Error(`publishIPNS timed out after ${TIMEOUT_MS}ms`)), TIMEOUT_MS),
+	)
+	return Promise.race([_publishIPNSImpl(ipnsPrivateKey, cid), timeout])
+}
+
+async function _publishIPNSImpl(ipnsPrivateKey: Uint8Array, cid: CID): Promise<W3Name.Revision> {
+	const value = `/ipfs/${cid}`
+	const ipns = await W3Name.from(ipnsPrivateKey)
+
+	let revision: W3Name.Revision
+	const existing = await tryResolveIPNS(ipns)
+
+	if (existing) {
+		// Record exists - increment sequence number
+		revision = await W3Name.increment(existing, value)
+		DEBUG('[w3name] incrementing revision for', ipns.toString())
+	} else {
+		// First publish - use v0
+		revision = await W3Name.v0(ipns, value)
+		DEBUG('[w3name] creating initial revision for', ipns.toString())
+	}
+
+	await W3Name.publish(revision, ipns.key)
+	DEBUG('[w3name] published', cid.toString(), 'to', ipns.toString())
+
+	return revision // Return for Kubo integration or other uses
+}
+
+/**
+ * Create an IPNSPublishTarget that publishes to W3Name service via HTTP POST.
+ */
+export function w3nameTarget(serviceUrl = 'https://name.web3.storage'): IPNSPublishTarget {
+	return {
+		name: 'w3name',
+		async publish(ipnsName: string, recordBytes: Uint8Array) {
+			const res = await fetch(`${serviceUrl}/name/${ipnsName}`, {
+				method: 'POST',
+				body: base64pad.baseEncode(recordBytes),
+			})
+			if (!res.ok) throw new Error(`W3Name HTTP ${res.status}`)
+		},
+	}
+}
+
+export async function generateIpnsKey() {
+	return W3Name.create() // Returns W3Name.WritableName type
+}
+
+export async function getW3NamePublic(pk: Uint8Array) {
+	const ipns = await W3Name.from(pk)
+	return ipns.toString()
+}