Bump kubo 0.42.0 -> 0.43.0 (blocks pkc-js#225 garbage collection)

[Rinse12]

Summary

bitsocial-cli pins kubo@0.42.0 (package.json) and owns the production daemon spawn
(src/ipfs/startIpfs.ts, spawn(kuboExePath, ["daemon", "--migrate"])). It should be bumped to
kubo@0.43.0.

This is a release blocker for the garbage-collection change in pkcprotocol/pkc-js#225: pkc-js
only carries kubo as a devDependency (its test binary), so the daemon that actually runs in
production is the one this repo ships.

Why it blocks

pkc-js is changing repo.gc from an effectively-never lottery (Math.random() < 0.00001 per
community sync) to a real schedule: GC once the repo crosses 90% of Datastore.StorageMax, with a
1h floor between runs. That is the fix for the node that reached ~190 GB against a 10 GB
StorageMax and then exhausted both disk and inodes.

On kubo <= 0.42.0, running repo gc concurrently with MFS writes can wedge MFS permanently — GC
collects blocks an in-flight write has added but not yet linked into the persisted MFS root, and the
next traversal blocks forever on a missing block while holding the MFS mutex. Making GC actually run
on 0.42.0 would therefore trade a disk-exhaustion failure for a daemon-wedge failure.

kubo 0.43.0 fixes both halves:

• Every MFS mutation now takes the same pin lock ipfs add uses, and GC reads the MFS root while
  holding the GC lock, so GC can no longer collect data a live write still needs
  (fix(mfs): stop repo gc from freezing files ops ipfs/kubo#11386).
• MFS no longer hangs on a missing or unreachable block: the operation ends with an error, and
  files read / files write honor --timeout (feat(mfs): bound under-lock DAG reads ipfs/boxo#1185).

Change needed

1. package.json: "kubo": "0.42.0" -> "0.43.0", regenerate the lockfile.
2. No --enable-gc flag is needed. pkc-js drives GC over the RPC API, which does the same work;
   --enable-gc would only add a second, independent schedule.
3. Worth checking while here: Datastore.StorageMax is what the new pkc-js watermark measures
   against, so whatever value the CLI writes into the repo config is now load-bearing rather than
   decorative.

0.43.0 breaking change to check

The daemon refuses to start when Ipns.RecordLifetime is shorter than Ipns.RepublishPeriod. If
the CLI writes either key into the repo config, verify the pair is still valid.

Related

• Enable Kubo garbage collection once kubo 0.43.0 ships (StorageMax currently unenforced) pkcprotocol/pkc-js#225 - the GC change this blocks
• Kubo blocks datastore defaults to sync:false — power loss can corrupt the repo and crash-loop the daemon #117 - flatfs sync: false / zero-byte blocks; adjacent (it is the corruption mode observed on
  the same node) but a separate fix

[Rinse12]

Implemented on master (pending test suite + commit).

Changes

• kubo 0.42.0 -> 0.43.0
• @pkcprotocol/pkc-js 0.0.73 -> 0.0.77 (this is the version that carries the pkc-js#225 GC change — cleanUpIpfsRepoIfDue with the 90% StorageMax watermark and 1h floor)
• startKuboNode now spawns the daemon with --enable-gc, controlled by a new --enableIpfsGc / --no-enableIpfsGc daemon flag (default on)
• Datastore.StorageMax left alone (still kubo's default 10GB) — out of scope for this issue

On --enable-gc

The issue text said no --enable-gc was needed. Reconsidered, because pkc-js only drives GC from a local community's IPNS sync — a daemon that is up but has no started community never GCs at all. kubo's own schedule is unconditional and uses the same policy (Datastore.GCPeriod 1h, Datastore.StorageGCWatermark 90, Datastore.StorageMax 10GB — all already present in existing repo configs). Both take the same GC lock, so an overlap blocks rather than conflicts.

This was tried once before — f228d7d (Dec 2023), reverted two days later in 69a38d4 with no reason recorded. The timing matches the pre-0.43.0 GC/MFS wedge described in this issue, so it was re-tested empirically rather than assumed.

Empirical verification on kubo 0.43.0

Test repo with Datastore.StorageMax=1MB, GCPeriod=5s, watermark 90, daemon run with --enable-gc, while doing 64 rounds of files write + files stat into MFS and adding an unpinned 128KB block each round:

Check	Result
Daemon starts with Ipns.RecordLifetime="" / RepublishPeriod=""	PASS — the 0.43.0 validation accepts empty (= use default)
GC cycles observed in daemon log	128 (Watermark exceeded. Starting repo GC...)
Unpinned garbage blocks reclaimed	64 / 64
MFS wedge under concurrent GC	none — all 64 write+stat cycles completed, files ls returns all 64 files, CumulativeSize 8396091 intact
GC/MFS errors in daemon log	none

So the failure mode that caused the 2023 revert does not reproduce on 0.43.0.

Notes

• Ipns.RecordLifetime / RepublishPeriod breaking change is a non-issue here. The CLI never writes either key, and existing repos carry "" for both, which 0.43.0 accepts. Verified against a repo seeded with the production values.
• GC only reclaims unpinned blocks. In the test, repo size stayed at 8.4MB against a 1MB ceiling because MFS data is GC-protected. This is the open question already flagged on pkc-js#225: the affected node had >11k recursive pins, and GC will not touch those. --enable-gc bounds unpinned growth; it does not by itself cap a repo whose bulk is pinned.
• kubo@1.0.1 exists on npm but dist-tags.latest is still 0.43.0, so 0.43.0 is the right target.

Tests

Four added to test/kubo/kuboRpcGateway.integration.test.ts: --enable-gc present by default, present when explicitly enabled, absent when disabled, and a guard asserting kubo >= 0.43.0 (the flag is unsafe below that).

[Rinse12]

Correction to my previous comment: --enable-gc does not work and has been dropped. Running the test suite caught it.

What happened

With --enable-gc, 4 kubo-restart tests in test/cli/daemon.test.ts fail deterministically. Controlled A/B on an otherwise idle machine, same upgraded deps (kubo 0.43.0 + pkc-js 0.0.77), only the flag differing:

Build	Result
without --enable-gc	23/23 pass
with --enable-gc	4 failed / 19 passed

Root cause, reproduced standalone with no bitsocial-cli involved:

Shutdown path	plain daemon	daemon with --enable-gc
POST /api/v0/shutdown	exits in ~0.1s	never exits (permanent, still alive past 300s)
SIGTERM	exits	exits

The hung daemon logs failed to access config: cannot access config, repo not open and lingers as a half-shutdown zombie. Datastore.GCPeriod length makes no difference.

This is fatal here because pkc-js POSTs /api/v0/shutdown when it rewrites the kubo Routing config on first connect and relies on the daemon restarting kubo afterwards. With --enable-gc that restart never happens.

It also means the 2023 revert (f228d7d -> 69a38d4) most likely had nothing to do with the MFS/GC wedge described in the issue body — that revert predates 0.43.0, and this shutdown hang is a much closer match to "enabled it, it broke, reverted two days later". The MFS-wedge concern itself is genuinely fixed in 0.43.0: 64 rounds of files write + files stat against GC every 5s at a 1MB ceiling completed with MFS fully intact and all 64 unpinned garbage blocks reclaimed.

What shipped instead

src/ipfs/repoGc.ts — GC driven over the RPC API on the daemon's own schedule, which never touches kubo's daemon lifecycle:

• POST /api/v0/repo/stat?size-only=true, and if RepoSize >= 90% of StorageMax, POST /api/v0/repo/gc?quiet=true
• hourly by default (matches kubo's Datastore.GCPeriod), single-flighted so a long GC never stacks, timer unref'd, errors swallowed inside the tick so a rejected interval callback can't take the daemon down
• size-only on purpose — the default repo/stat walks the entire flatfs blockstore
• new flags: --enableIpfsGc / --no-enableIpfsGc (default on) and --ipfsGcIntervalMinutes (default 60)
• runs against whichever kubo the daemon talks to, including an externally started one via --pkcOptions.kuboRpcClientsOptions

Verified against a live kubo 0.43.0 node: correctly skipped while below the watermark, and a forced run reclaimed 10 CIDs, shrinking the repo 1,010,267 -> 9,727 bytes.

This still covers the gap that motivated adding GC to the CLI at all: pkc-js only GCs from a started local community's IPNS sync, so a daemon that is up with no community started never reclaims anything.

Status

• kubo 0.42.0 -> 0.43.0, pkc-js 0.0.73 -> 0.0.77
• Datastore.StorageMax left alone (kubo default 10GB)
• Ipns.RecordLifetime / RepublishPeriod: non-issue, the CLI writes neither and 0.43.0 accepts the "" that existing repos carry (verified)
• 12 new unit tests in test/kubo/repoGc.test.ts; full suite green at 41 files / 322 passed / 1 skipped

Unresolved and worth deciding separately: the --enable-gc shutdown hang looks like an upstream kubo bug. I have not filed anything on ipfs/kubo.

[Rinse12]

Reported upstream: ipfs/kubo#11424

Confirmed it is a kubo bug, not a misuse on our side, and not a 0.43.0 regression — it reproduces identically on 0.24.0, 0.42.0 and 0.43.0.

Cause: maybeRunGC hands PeriodicGC the command request context, but ipfs shutdown only calls nd.Close(), which cancels the node context. gcErrc therefore never closes and daemonFunc blocks forever draining merge(apiErrc, gwErrc, gcErrc, ...). Every other channel in that merge is node-context-wired; gcErrc is the lone exception, which is exactly why the hang appears only with --enable-gc. SIGINT/SIGTERM work because the interrupt handler does cancel the request context. The Internal.ShutdownTimeout watchdog from ipfs/kubo#11329 does not catch it — that bounds node.Close(), not the drain afterwards.

That 0.24.0 result also settles the archaeology: 0.24.0 is the era of f228d7d (Dec 2023), so this shutdown hang is what caused that revert, not the MFS/GC wedge. The MFS wedge was a real concern but a coincidental one, and it is genuinely fixed in 0.43.0.

No action needed here — src/ipfs/repoGc.ts drives GC over the RPC API and never passes --enable-gc, so we do not depend on an upstream fix. If kubo fixes it we could revisit, but there would be little reason to: the RPC scheduler also covers the case where kubo was started by another program.