feat: hypercore11 migration support by RangerMauve · Pull Request #214 · digidem/comapeo-core-react-native

RangerMauve · 2026-07-28T18:28:43Z

Based on the existing work we did in mobile

adds migration related code to index in backend
adds ability to retry init
new states for react side (including progress for migration)
pass avail space from kotlin/swift side
backend test for checking migration can work
native tests for state parsing

socket-security · 2026-07-28T18:30:07Z

Review the following changes in direct dependencies. Learn more about Socket for GitHub.

Diff	Package	Supply Chain Security	Vulnerability	Quality	Maintenance	License
	@comapeo/core@7.4.0 ⏵ 8.0.0-next.1				⁺²

View full report

gmaclennan

This requires quite a few changes before we can safely merge this.

The retry behaviour currently is broken - it just falls through to forceFallback: true. I also don't understand the reasoning for only allowing a single retry - a user would want to keep freeing up space and retrying until they have enough space.

There is no API for the user to skip the retry and just use the old comapeo (fallback) - at least, not if we fix retry to actually retry instead of being "use fallback".

We can remove the iOS migration code and path - we haven't released anything on iOS so no need to release and maintain that.

See my note about testing - my oversight never plugging backend tests into CI, and it's really important that this code has some CI tests that are required before merge. The tests you added I don't think are running from any test script due to the filename glob.

There is no partial migration state handling, e.g. if migration throws an error before completing (e.g. because disk space runs out, despite our attempts to ensure there is enough space). This code allows a user to go into the fallback in this state (partially migrated) which would result in data corruption. Also if migration does fail due to disk space, this isn't exposed as a low-space error, just a generic backend error. I think this needs a fix in core too - we should detect the partial state in core and forbid opening the v7 core. Also low_space needs to indicate whether it is possible to ignore / delay until later, so the UX can decide whether to show the button that results in the fallback.

gmaclennan · 2026-08-18T14:18:42Z

    "@sentry/core": "^10.53.0",
    "@sentry/node-core": "^10.53.0",
    "@sentry/opentelemetry": "^10.53.0",
+    "comapeo-core-old": "npm:@comapeo/core@^7.1.0",


let's pin this as we do other deps.

gmaclennan · 2026-08-18T14:23:08Z

+   * accept fallback) to allow the migration to proceed. A positive value
+   * means the migration needs more space than is currently available.
+   */
+  spaceNeeded?: number;


Nit: This would be easier to work with on the front-end if it's a discriminate union, e.g.

type StateChangeEventPayload = { state: Exclude<ComapeoState, 'ERROR' | 'LOW_SPACE'>; } | { state: 'ERROR'; errorPhase: string; errorMessage: string; } | { state: 'LOW_SPACE'; spaceNeeded: number; }

gmaclennan · 2026-08-18T14:24:19Z

+ * frame (subsequent retries after the first are no-ops in the backend).
+ */
+export function sendRetry(): void {
+  nativeModule.sendRetry?.();


Why the nullish optional chaining? Wouldn't it be better to throw rather than do nothing?

gmaclennan · 2026-08-18T14:25:48Z

  comapeoServicesClient,
  getNotificationPermissionsAsync,
  requestNotificationPermissionsAsync,
+  sendRetry,


nit: This is confusing naming. Retry what? "send" to where? Maybe call it retryMigration()?

gmaclennan · 2026-08-18T14:30:26Z

-        });
+        // Old and new MapeoManager have incompatible #private fields; cast
+        // to the newer type. Both share the same public API surface.
+        comapeoManager = /** @type {import("@comapeo/core").MapeoManager} */ (


Rather than cast the type, either redefine the type of comapeoManager to be either the old or the new type, or use this helper:

type Public<T> = { [K in keyof T]: T[K] } let comapeoManager: Public<MapeoManager>

This is a really useful trick, I've been running into this with mocks in other codebases. 🙇

not enough because other places ask for the full manager class. Maybe we can change the type exported in core?

gmaclennan · 2026-08-18T14:48:44Z

+                        is ControlFrame.Migrating -> setState(JsState.MIGRATING)
+                        is ControlFrame.LowSpace -> setState(
+                            JsState.LOW_SPACE,
+                            mapOf("spaceNeeded" to frame.spaceNeeded.toString()),


This is sent as a string, but in JS it's typed as a number, so I don't think this will work as-is?

gmaclennan · 2026-08-18T14:50:09Z

+ * Safe to call from any state — if not parked, the backend ignores the
+ * frame (subsequent retries after the first are no-ops in the backend).


Is this true? if sent before parked then I think it would break things. Maybe gate this on being parked?

gmaclennan · 2026-08-18T14:52:46Z

+        // boot after a `LOW_SPACE` park.
+        Function("sendRetry") {
+          val availableDiskSpace =
+            java.nio.file.Files.getFileStore(java.nio.file.Paths.get(appContext.persistentFilesDirectory.path)).usableSpace


This could throw an IOException - i guess ok since that just bubbles to RN JS?

Yes, I think we should bubble it

gmaclennan · 2026-08-18T14:53:07Z

            SentryConfig.readApplicationMetaDataString(this, META_DEFAULT_ONLINE_STYLE_URL) ?: ""
+        // 6th positional: available disk space in bytes for migration decision.
+        val availableDiskSpace =
+            java.nio.file.Files.getFileStore(java.nio.file.Paths.get(dataDir)).usableSpace


This can throw a IOException and crash the FGS

This won't work in Android API < 26, and we support API >= 24.

You can use File(dataDir).usableSpace (java.io.File) but it returns 0 on failure (rather than an error). There is also StorageManager.getAllocatableBytes(storageUuid) which is slightly different because it includes "bytes that could be written" including data Android might evict from other apps' cache folders, but it's API 26+ - we could use this with a fallback.

What do you think should be the failure mode on a device where we can't read free disk space for some reason?

note for future self: we decided to set the val to 0 and attempt to allocate the num bytes we need in core (then delete the file).

gmaclennan · 2026-08-18T15:06:15Z


+/**
+ * One-shot retry gate: resolves on first `retry` frame from native.
+ * Only fires once so a misbehaving native side can't loop the boot.


This doesn't make sense to me, is this an agent copying from the comment below on line 103? Why would we only want to allow retry once? A user would want to keep retrying as they keep trying to free up enough space.

RangerMauve · 2026-08-18T15:58:59Z

Going to totally redo how retries work and how we do migration to align it more with how we did it in pre core-react-native comapeo-mobile.

Remove the shared MigrationDetail struct that bundled phase/message/ spaceNeeded for both MIGRATION_ERROR and LOW_SPACE. Each state now carries only its own data: - MIGRATION_ERROR reuses ErrorInfo + getLastError() — the applyAndEmit(error:) path sets it, the module reads it via the existing getter. No new accessor needed. - LOW_SPACE carries spaceNeeded (a non-nullable number) directly: on iOS it lives on the State enum case (dropped : String raw-value conformance in favour of a computed rawValue); on Android it is built inline in the frame handler. The JS stateChange event now emits a StateChangeDetails union (ComapeoErrorInfo | LowSpaceDetails) instead of a flat ComapeoErrorInfo, so spaceNeeded reaches listeners as a number. Sentry breadcrumbs spread the details object directly.

.lowSpace has an associated Int value so direct == comparison fails. Compare rawValue instead to match the custom Equatable conformance.

RangerMauve changed the title ~~Feat/hypercore11 migration~~ feat: hypercore11 migration support Jul 28, 2026

github-actions Bot added the feature New feature (changelog) label Jul 28, 2026

RangerMauve marked this pull request as ready for review July 28, 2026 20:54

RangerMauve requested a review from gmaclennan July 28, 2026 20:55

gmaclennan requested changes Aug 18, 2026

View reviewed changes

RangerMauve added 15 commits August 18, 2026 14:19

chore: update comapeo-core and add old version as fallback

606ddd7

feat: add flag to use old comapeo core version

3ded2c4

chore: extract core init code into reusable function

adc94d3

feat: add retryInit method to module

68e666a

fix: avoid retry overwriting existing core instance

97ee58c

fix: allow forceSkipMigrate to be undefined on android retryInit

832c5ea

feat: migration code and states in backend

f5282b9

feat: wire up migration states to ios/rn

e2d46ef

feat: add migration states to android. make spaceNeeded a number

85744b9

feat: add state guards for new states

376c7e2

feat: provide actual avail disk space

e455188

fix: add static paths for old comapeo module

70a9201

test: migration rpc events including low space

8081363

feat: handle new transient states in simple-rpc

c64fa2c

RangerMauve force-pushed the feat/hypercore11-migration branch from 5e04a75 to c64fa2c Compare August 24, 2026 21:19

RangerMauve and others added 7 commits August 25, 2026 12:10

Merge branch 'main' into feat/hypercore11-migration

cdf5b79

fix: info renamed to details in merge

006a96e

fix: update types for sentry error logging

cd99d6b

fix: iOS add equitable to state so we can compare with lowSpace

35ecad7

fix: handle new states and types in android

6e5a1b7

fix(iOS): use rawValue comparison for .lowSpace enum case in retry guard

7bf3a08

.lowSpace has an associated Int value so direct == comparison fails. Compare rawValue instead to match the custom Equatable conformance.

fix: let stop intent outrank migration states in derivation

8406117

RangerMauve added 7 commits August 25, 2026 16:38

fix: export retryInit in native module

b0ac2ba

fix: Improve parsing of availableDiskSpaceArg

67aa8ae

tests: ensure manager gets closed in test process

2cb00bd

chore: move mock-data to dev dependency of backend

b47ab34

fix: Add stronger type check to backend retry

83b9468

fix: log migration errors to sentry

5292d50

chore: fix up lockfile and ts config

1ca938d

		* Safe to call from any state — if not parked, the backend ignores the
		* frame (subsequent retries after the first are no-ops in the backend).

Uh oh!

Conversation

RangerMauve commented Jul 28, 2026

Uh oh!

socket-security Bot commented Jul 28, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

gmaclennan left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

RangerMauve commented Aug 18, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

socket-security Bot commented Jul 28, 2026 •

edited

Loading