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@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?

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.

RangerMauve and others added 6 commits July 27, 2026 17:56

feat: Hypercore11 migration code

8fbe5c8

chore: remove debug console logs

dbf5005

chore: bump core dep to fix dep issues

f72aaad

feat: add retry send to nativeModule

850870a

test: add ControlFrame + DeriveState coverage for Migrating/LowSpace

337dc02

Merge branch 'main' into feat/hypercore11-migration

602c7ac

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 added 6 commits July 28, 2026 14:34

fix: exhaust terminalStatus switch for MIGRATING/LOW_SPACE

7db1b3e

fix: lint errors in backend files

380ea00

fix: exhaust JsState when in ComapeoCoreModule for MIGRATING/LOW_SPACE

89ab487

fix: DeriveStateTest migratingDerivesMigrating expectation

2a00845

feat: propagate spaceNeeded through low-space frame

37aab9f

fix(android): convert spaceNeeded Long to String for setState payload

330688d

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

RangerMauve and others added 9 commits July 28, 2026 17:05

fix: respect forceFallback in migrate

7c5a9ca

fix: Correct types in seed-old-storage

d45f13a

feat: pass updated disk space to retry event

e7ea2ee

Merge branch 'main' into feat/hypercore11-migration

6ba8aec

fix: fix ref to data dir in retry

89afedc

Merge branch 'main' into feat/hypercore11-migration

a383f4e

fix: missing filesDir arg

73e8d9e

feat: replay migrating and low storage states on connected

d166ee3

Merge branch 'main' into feat/hypercore11-migration

5e04a75

gmaclennan requested changes Aug 18, 2026

View reviewed changes

		* 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!

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