@wovin/core 0.2.2 → 0.3.0

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()
+}