You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@maka.apache.org by wy...@apache.org on 2026/08/28 13:48:16 UTC
(maka) branch feat/desktop-peer-mesh-management created (now c1615f761)
This is an automated email from the ASF dual-hosted git repository.
M4n5ter pushed a change to branch feat/desktop-peer-mesh-management
in repository https://gitbox.apache.org/repos/asf/maka.git
at c1615f761 feat(runtime-host): manage peer meshes from Desktop
This branch includes the following new commits:
new c1615f761 feat(runtime-host): manage peer meshes from Desktop
The 1 revisions listed above as "new" are entirely new to this
repository and will be described in separate emails. The revisions
listed as "add" were already present in the repository and have only
been added to this reference.
---------------------------------------------------------------------
To unsubscribe, e-mail: commits-unsubscribe@maka.apache.org
For additional commands, e-mail: commits-help@maka.apache.org
(maka) 01/01: feat(runtime-host): manage peer meshes from Desktop
Posted by wy...@apache.org.
This is an automated email from the ASF dual-hosted git repository.
M4n5ter pushed a commit to branch feat/desktop-peer-mesh-management
in repository https://gitbox.apache.org/repos/asf/maka.git
commit c1615f761e613c50843fca43bac3b91bc4bf5b1a
Author: Wang <m4...@gmail.com>
AuthorDate: Fri Aug 28 21:47:02 2026 +0800
feat(runtime-host): manage peer meshes from Desktop
Add owner-only Mesh management operations and expose them through the CLI and Desktop local or SSH-managed endpoints. Preserve Mesh state by peer identity and keep invitations out of command arguments.
Generated-by: OpenAI Codex
---
.../__tests__/runtime-host-ssh-terminal.test.ts | 58 +++-
apps/desktop/src/main/runtime-host-boot.ts | 22 +-
apps/desktop/src/main/runtime-host-peer-client.ts | 18 +-
.../src/main/runtime-host-peer-mesh-management.ts | 194 +++++++++++
apps/desktop/src/main/runtime-host-ssh-terminal.ts | 64 ++++
apps/desktop/src/preload/bridge-contract.d.ts | 20 ++
apps/desktop/src/preload/preload.ts | 16 +
.../src/renderer/locales/settings-projects-copy.ts | 9 +
.../settings/runtime-host-peer-mesh-dialog.tsx | 363 ++++++++++++++++++++
.../settings/runtime-host-profiles-section.tsx | 36 ++
.../src/renderer/styles/settings/runtime-host.css | 46 +++
docs/astryx-surface-file-inventory.md | 3 +-
docs/astryx-surface-file-inventory.paths | 1 +
.../runtime-host-operator-command.test.ts | 44 +++
packages/cli/src/cli-core.ts | 19 ++
packages/cli/src/runtime-host-cli.ts | 99 +++++-
.../runtime-host-peer-mesh-management-command.ts | 309 +++++++++++++++++
packages/cli/src/runtime-host-service-command.ts | 1 +
.../src/runtime-host-service-management-command.ts | 2 +
.../src/__tests__/connection-session.test.ts | 16 +-
.../src/__tests__/operation-dispatcher.test.ts | 4 +-
.../runtime-host/src/__tests__/peer-mesh.test.ts | 4 +
packages/runtime-host/src/operator/index.ts | 9 +
.../src/operator/peer-mesh-management-frame.ts | 150 +++++++++
.../src/operator/service-management-frame.ts | 2 +
.../src/{server/index.ts => peer-mesh/limits.ts} | 19 +-
packages/runtime-host/src/peer-mesh/model.ts | 24 +-
packages/runtime-host/src/peer-mesh/node.ts | 195 ++++++++++-
packages/runtime-host/src/peer-mesh/owner.ts | 11 +-
packages/runtime-host/src/peer-mesh/store.ts | 22 +-
packages/runtime-host/src/protocol/index.ts | 13 +-
packages/runtime-host/src/protocol/operations.ts | 2 +
packages/runtime-host/src/protocol/peer-mesh.ts | 364 +++++++++++++++++++++
.../runtime-host/src/server/execution-service.ts | 54 ++-
packages/runtime-host/src/server/host-kernel.ts | 4 +
packages/runtime-host/src/server/index.ts | 4 +
.../src/server/operation-dispatcher.ts | 17 +-
.../runtime-host/src/server/peer-mesh-authority.ts | 169 ++++++++++
38 files changed, 2330 insertions(+), 77 deletions(-)
diff --git a/apps/desktop/src/main/__tests__/runtime-host-ssh-terminal.test.ts b/apps/desktop/src/main/__tests__/runtime-host-ssh-terminal.test.ts
index 3bbc6c564..2bac17462 100644
--- a/apps/desktop/src/main/__tests__/runtime-host-ssh-terminal.test.ts
+++ b/apps/desktop/src/main/__tests__/runtime-host-ssh-terminal.test.ts
@@ -29,6 +29,7 @@ import {
encodeRuntimeHostAccessManagementFrame,
encodeRuntimeHostServiceManagementFrame,
encodeRuntimeHostSetupFrame,
+ encodeRuntimeHostPeerMeshManagementFrame,
runtimeHostAccessCredentialFingerprint,
RUNTIME_HOST_OPERATOR_PEER_MANAGEMENT_CAPABILITY,
RUNTIME_HOST_SETUP_FRAME_PREFIX,
@@ -607,6 +608,58 @@ test('keeps a prepared access credential out of the SSH terminal projection', as
await harness.terminal.close();
});
+test('sends a Mesh invitation only after the authenticated remote operator requests it', async () => {
+ const harness = createHarness('pending');
+ const invitation = JSON.stringify({ secret: 'one-time-mesh-secret' });
+ const management = harness.terminal.runPeerMeshManagement({
+ destination: 'operator@example.com',
+ operatorPath: '/home/operator/.local/share/maka/operator',
+ action: 'join',
+ invitation,
+ expectedTarget: {
+ serviceId: 'b'.repeat(64),
+ rootPath: '/srv/maka',
+ rootId: 'a'.repeat(64),
+ deploymentId: '00000000-0000-4000-8000-000000000001',
+ },
+ });
+ await waitFor(() => harness.pty.hasDataListener());
+ const command = harness.launchArgs.at(-1)?.at(-1) ?? '';
+ assert.match(command, /mesh.*join.*--framed/u);
+ assert.doesNotMatch(command, /one-time-mesh-secret/u);
+ assert.deepEqual(harness.pty.writes, []);
+
+ harness.pty.emitData(
+ encodeRuntimeHostPeerMeshManagementFrame({ kind: 'input', action: 'join' }),
+ );
+ assert.deepEqual(harness.pty.writes, [`${invitation}\r`]);
+ harness.pty.emitData(
+ encodeRuntimeHostPeerMeshManagementFrame({
+ kind: 'result',
+ action: 'join',
+ result: {
+ meshId: 'mesh-id',
+ role: 'member',
+ localPeerId: 'peer-b',
+ authorityPeerId: 'peer-a',
+ revision: 2,
+ closed: false,
+ members: ['peer-a', 'peer-b'],
+ memberRoutes: [
+ { peerId: 'peer-a', state: 'route_available', expiresAt: Date.now() + 60_000 },
+ { peerId: 'peer-b', state: 'local' },
+ ],
+ pendingInvitationCount: 0,
+ },
+ }),
+ );
+ harness.pty.exit(0);
+
+ assert.equal((await management).kind, 'result');
+ assert.doesNotMatch(JSON.stringify(harness.events), /one-time-mesh-secret/u);
+ await harness.terminal.close();
+});
+
test('rejects a framed service result for a different action', async () => {
const harness = createHarness('pending');
const management = harness.terminal.runServiceManagement({
@@ -856,6 +909,7 @@ class FakePty {
deferKill = false;
exitOnForceKill = false;
readonly killSignals: Array<string | undefined> = [];
+ readonly writes: string[] = [];
readonly #dataListeners = new Set<(data: string) => void>();
readonly #exitListeners = new Set<(event: { exitCode: number; signal: number }) => void>();
#resolveExit!: () => void;
@@ -892,7 +946,9 @@ class FakePty {
this.#resolveExit();
}
- write(): void {}
+ write(data: string): void {
+ this.writes.push(data);
+ }
resize(): void {}
kill(signal?: string): void {
this.killSignals.push(signal);
diff --git a/apps/desktop/src/main/runtime-host-boot.ts b/apps/desktop/src/main/runtime-host-boot.ts
index 0bbce55db..6c0d0ae39 100644
--- a/apps/desktop/src/main/runtime-host-boot.ts
+++ b/apps/desktop/src/main/runtime-host-boot.ts
@@ -48,11 +48,11 @@ import {
createClientRuntimeHostCredentialStore,
createClientRuntimeHostProfileCatalog,
createRuntimeHostCandidateLaunchBarrier,
- createRuntimeHostPeerClientFromEnvironment,
LOCAL_RUNTIME_HOST_PROFILE,
loadOrCreateRuntimeHostClientInstanceId,
listRuntimeHostWslDistributions,
} from "@maka/runtime-host/client";
+import { openRuntimeHostPeerMeshOwner } from '@maka/runtime-host/peer-mesh';
import type { WorkspaceTarget } from "@maka/runtime-host/protocol";
import { runtimeHostProfileUsesHostWorkspace } from "@maka/runtime-host/profile-kind";
import { createCredentialMcpOAuthStorage, McpClientManager } from "@maka/mcp";
@@ -178,6 +178,7 @@ import { createDesktopRuntimeHostLocalOperator } from './runtime-host-local-oper
import { createDesktopLocalRuntimeHostRemoteAccess } from './runtime-host-local-remote-access.js';
import { createDesktopRuntimeHostOnboarding } from "./runtime-host-onboarding.js";
import { createDesktopRuntimeHostManagement } from "./runtime-host-management.js";
+import { createDesktopRuntimeHostPeerMeshManagement } from './runtime-host-peer-mesh-management.js';
import { registerRuntimeHostOAuthIpc } from "./runtime-host-oauth-ipc-main.js";
import { RuntimeHostOAuthPresentation } from "./runtime-host-oauth-presentation.js";
import { registerRuntimeHostPermissionsIpc } from "./runtime-host-permissions-ipc-main.js";
@@ -218,15 +219,20 @@ await resolveShellEnv();
const MANAGED_UPDATE_RECONNECT_TIMEOUT_MS = 10_000;
const buildInfo = resolveBuildInfo(app.isPackaged, app.getAppPath());
const userDataDir = app.getPath("userData");
-const runtimeHostDirectPeerAvailable = await configureDesktopRuntimeHostPeerClient({
+const runtimeHostPeerConfiguration = await configureDesktopRuntimeHostPeerClient({
isPackaged: app.isPackaged,
appPath: app.getAppPath(),
resourcesPath: process.resourcesPath,
clientDataRoot: userDataDir,
});
-const runtimeHostPeerClient = runtimeHostDirectPeerAvailable
- ? createRuntimeHostPeerClientFromEnvironment()
+const runtimeHostPeerOwner = runtimeHostPeerConfiguration
+ ? await openRuntimeHostPeerMeshOwner({
+ ...runtimeHostPeerConfiguration,
+ dataRoot: join(userDataDir, 'peer-mesh'),
+ })
: undefined;
+const runtimeHostPeerClient = runtimeHostPeerOwner?.client;
+const runtimeHostDirectPeerAvailable = runtimeHostPeerOwner !== undefined;
const runtimeHostClientInstanceId = await loadOrCreateRuntimeHostClientInstanceId(
join(userDataDir, "runtime-host-client.json"),
);
@@ -532,6 +538,12 @@ const runtimeHostManagement = createDesktopRuntimeHostManagement({
runAccessManagement: runtimeHostSshTerminal.runAccessManagement,
cleanupManagedDeployment: runtimeHostSshTerminal.cleanupManagedDeployment,
});
+const runtimeHostPeerMeshManagement = createDesktopRuntimeHostPeerMeshManagement({
+ ipcMain,
+ localMesh: runtimeHostPeerOwner?.mesh,
+ profiles: runtimeHostProfileService,
+ runRemote: runtimeHostSshTerminal.runPeerMeshManagement,
+});
const defaultRuntimeHostRecovery = createRuntimeHostDefaultRecovery({
defaultProfileId: () =>
runtimeHostManager?.defaultProfileId() ??
@@ -1636,7 +1648,9 @@ async function closeRuntimeHostDesktop(): Promise<void> {
permissionOverlay.dismiss();
const results = await Promise.allSettled([
Promise.resolve().then(() => runtimeHostManagement.close()),
+ Promise.resolve().then(() => runtimeHostPeerMeshManagement.close()),
runtimeHostManager?.close(),
+ runtimeHostPeerOwner?.close(),
runtimeHostOnboarding.close(),
localRuntimeHostRemoteAccess.close(),
runtimeHostSetupPackage.close(),
diff --git a/apps/desktop/src/main/runtime-host-peer-client.ts b/apps/desktop/src/main/runtime-host-peer-client.ts
index 395e194f9..e67480211 100644
--- a/apps/desktop/src/main/runtime-host-peer-client.ts
+++ b/apps/desktop/src/main/runtime-host-peer-client.ts
@@ -28,11 +28,15 @@ export async function configureDesktopRuntimeHostPeerClient(input: {
readonly resourcesPath: string;
readonly clientDataRoot: string;
readonly environment?: NodeJS.ProcessEnv;
-}): Promise<boolean> {
+}): Promise<{ readonly nativePath: string; readonly keyPath: string } | undefined> {
const environment = input.environment ?? process.env;
const explicitNativePath = environment.MAKA_RUNTIME_HOST_PEER_NATIVE_PATH?.trim();
const explicitKeyPath = environment.MAKA_RUNTIME_HOST_PEER_KEY_PATH?.trim();
- if (explicitNativePath || explicitKeyPath) return Boolean(explicitNativePath && explicitKeyPath);
+ if (explicitNativePath || explicitKeyPath) {
+ return explicitNativePath && explicitKeyPath
+ ? { nativePath: explicitNativePath, keyPath: explicitKeyPath }
+ : undefined;
+ }
const nativePath = input.isPackaged
? join(input.resourcesPath, 'runtime-host-peer', NATIVE_FILE)
: join(
@@ -48,12 +52,10 @@ export async function configureDesktopRuntimeHostPeerClient(input: {
try {
await access(nativePath);
} catch {
- return false;
+ return undefined;
}
environment.MAKA_RUNTIME_HOST_PEER_NATIVE_PATH = nativePath;
- environment.MAKA_RUNTIME_HOST_PEER_KEY_PATH = join(
- input.clientDataRoot,
- 'runtime-host-client.peer.key',
- );
- return true;
+ const keyPath = join(input.clientDataRoot, 'runtime-host-client.peer.key');
+ environment.MAKA_RUNTIME_HOST_PEER_KEY_PATH = keyPath;
+ return { nativePath, keyPath };
}
diff --git a/apps/desktop/src/main/runtime-host-peer-mesh-management.ts b/apps/desktop/src/main/runtime-host-peer-mesh-management.ts
new file mode 100644
index 000000000..904955a2b
--- /dev/null
+++ b/apps/desktop/src/main/runtime-host-peer-mesh-management.ts
@@ -0,0 +1,194 @@
+/*
+ * Licensed to the Apache Software Foundation (ASF) under one
+ * or more contributor license agreements. See the NOTICE file
+ * distributed with this work for additional information
+ * regarding copyright ownership. The ASF licenses this file
+ * to you under the Apache License, Version 2.0 (the
+ * "License"); you may not use this file except in compliance
+ * with the License. You may obtain a copy of the License at
+ *
+ * http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing,
+ * software distributed under the License is distributed on an
+ * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+ * KIND, either express or implied. See the License for the
+ * specific language governing permissions and limitations
+ * under the License.
+ */
+
+import type { IpcMain } from 'electron';
+import { decodePeerMeshInvitation, type PeerMeshNode } from '@maka/runtime-host/peer-mesh';
+import type {
+ PeerMeshInvitationV1,
+ PeerMeshProjection,
+ PeerMeshQueryResult,
+} from '@maka/runtime-host/protocol';
+import { projectPeerMeshStatus } from '@maka/runtime-host/server';
+import type {
+ DesktopRuntimeHostPeerMeshTarget,
+} from '../preload/bridge-contract.js';
+import type { DesktopRuntimeHostProfileService } from './runtime-host-profile-service.js';
+import type {
+ DesktopRuntimeHostSshPeerMeshManagementInput,
+ createDesktopRuntimeHostSshTerminal,
+} from './runtime-host-ssh-terminal.js';
+
+type SshTerminal = ReturnType<typeof createDesktopRuntimeHostSshTerminal>;
+type PeerMeshAction = DesktopRuntimeHostSshPeerMeshManagementInput['action'];
+
+export function createDesktopRuntimeHostPeerMeshManagement(input: {
+ readonly ipcMain: Pick<IpcMain, 'handle' | 'removeHandler'>;
+ readonly localMesh?: PeerMeshNode;
+ readonly profiles: Pick<DesktopRuntimeHostProfileService, 'resolveManagedService'>;
+ readonly runRemote: SshTerminal['runPeerMeshManagement'];
+}): { close(): void } {
+ const execute = async (
+ targetValue: unknown,
+ actionValue: unknown,
+ meshIdValue?: unknown,
+ peerIdValue?: unknown,
+ invitationValue?: unknown,
+ ): Promise<PeerMeshQueryResult | PeerMeshProjection | PeerMeshInvitationV1> => {
+ const target = requireTarget(targetValue);
+ const action = requireAction(actionValue);
+ const meshId = actionNeedsMesh(action) ? requireIdentifier(meshIdValue, 'Mesh ID') : undefined;
+ const peerId = action === 'remove' ? requireIdentifier(peerIdValue, 'Peer ID') : undefined;
+ const invitation = action === 'join' ? requireInvitation(invitationValue) : undefined;
+ if (target.kind === 'desktop') {
+ return executeLocal(input.localMesh, action, meshId, peerId, invitation);
+ }
+ const managed = await input.profiles.resolveManagedService(target.profileId);
+ if (
+ !managed ||
+ managed.state !== 'active' ||
+ managed.profile.transport.kind !== 'ssh' ||
+ !managed.deployment.deploymentId
+ ) {
+ throw new Error('This Runtime Host does not have an active SSH management channel');
+ }
+ const response = await input.runRemote({
+ destination: managed.profile.transport.destination,
+ ...(managed.profile.transport.sshPort === undefined
+ ? {}
+ : { sshPort: managed.profile.transport.sshPort }),
+ operatorPath: managed.control.operatorPath,
+ action,
+ expectedTarget: {
+ serviceId: managed.deployment.id,
+ rootPath: managed.deployment.rootPath,
+ rootId: managed.profile.rootId,
+ deploymentId: managed.deployment.deploymentId,
+ },
+ ...(meshId ? { meshId } : {}),
+ ...(peerId ? { peerId } : {}),
+ ...(invitation ? { invitation: JSON.stringify(invitation) } : {}),
+ });
+ if (response.kind === 'error') throw new Error(response.error.message);
+ if (response.action !== action) throw new Error('Runtime Host returned an unrelated Mesh result');
+ return response.result;
+ };
+
+ const channel = 'runtime-host-peer-mesh:execute';
+ input.ipcMain.handle(
+ channel,
+ (_event, target, action, meshId, peerId, invitation) =>
+ execute(target, action, meshId, peerId, invitation),
+ );
+ return { close: () => input.ipcMain.removeHandler(channel) };
+}
+
+async function executeLocal(
+ mesh: PeerMeshNode | undefined,
+ action: PeerMeshAction,
+ meshId: string | undefined,
+ peerId: string | undefined,
+ invitation: ReturnType<typeof decodePeerMeshInvitation> | undefined,
+): Promise<PeerMeshQueryResult | PeerMeshProjection | PeerMeshInvitationV1> {
+ if (!mesh) {
+ if (action === 'status') return { available: false, meshes: [] };
+ throw new Error('This Desktop build does not include Direct peer support');
+ }
+ const snapshot = (): PeerMeshQueryResult => ({
+ available: true,
+ localPeerId: mesh.localPeerId(),
+ meshes: mesh.status().map(projectPeerMeshStatus),
+ });
+ switch (action) {
+ case 'status':
+ return snapshot();
+ case 'create':
+ return projectPeerMeshStatus(await mesh.create());
+ case 'invite':
+ return mesh.invite(requiredValue(meshId, 'Mesh ID'));
+ case 'join':
+ return projectPeerMeshStatus(
+ await mesh.join(requiredValue(invitation, 'Peer Mesh invitation')),
+ );
+ case 'remove':
+ return projectPeerMeshStatus(
+ await mesh.remove(requiredValue(meshId, 'Mesh ID'), requiredValue(peerId, 'Peer ID')),
+ );
+ case 'leave':
+ await mesh.leave(requiredValue(meshId, 'Mesh ID'));
+ return snapshot();
+ case 'close':
+ return projectPeerMeshStatus(await mesh.closeMesh(requiredValue(meshId, 'Mesh ID')));
+ case 'reconcile':
+ await mesh.reconcile();
+ return snapshot();
+ }
+}
+
+function requiredValue<T>(value: T | undefined, label: string): T {
+ if (value === undefined) throw new Error(`${label} is required`);
+ return value;
+}
+
+function requireTarget(value: unknown): DesktopRuntimeHostPeerMeshTarget {
+ if (!value || typeof value !== 'object' || Array.isArray(value)) {
+ throw new Error('Peer Mesh target is invalid');
+ }
+ const record = value as Record<string, unknown>;
+ if (record.kind === 'desktop' && Object.keys(record).length === 1) return { kind: 'desktop' };
+ if (
+ record.kind === 'managed_host' &&
+ Object.keys(record).length === 2 &&
+ typeof record.profileId === 'string' &&
+ record.profileId.length > 0 &&
+ record.profileId.length <= 128
+ ) {
+ return { kind: 'managed_host', profileId: record.profileId };
+ }
+ throw new Error('Peer Mesh target is invalid');
+}
+
+function requireAction(value: unknown): PeerMeshAction {
+ if (
+ value === 'status' || value === 'create' || value === 'invite' || value === 'join' ||
+ value === 'remove' || value === 'leave' || value === 'close' || value === 'reconcile'
+ ) return value;
+ throw new Error('Peer Mesh action is invalid');
+}
+
+function actionNeedsMesh(action: PeerMeshAction): boolean {
+ return action === 'invite' || action === 'remove' || action === 'leave' || action === 'close';
+}
+
+function requireIdentifier(value: unknown, label: string): string {
+ if (typeof value !== 'string' || value.length === 0 || value.length > 256) {
+ throw new Error(`${label} is invalid`);
+ }
+ return value;
+}
+
+function requireInvitation(value: unknown): ReturnType<typeof decodePeerMeshInvitation> {
+ if (typeof value !== 'string' || Buffer.byteLength(value, 'utf8') > 128 * 1024) {
+ throw new Error('Peer Mesh invitation is invalid');
+ }
+ try {
+ return decodePeerMeshInvitation(JSON.parse(value) as unknown);
+ } catch {
+ throw new Error('Peer Mesh invitation is invalid');
+ }
+}
diff --git a/apps/desktop/src/main/runtime-host-ssh-terminal.ts b/apps/desktop/src/main/runtime-host-ssh-terminal.ts
index 1b2d82e21..bd1481e70 100644
--- a/apps/desktop/src/main/runtime-host-ssh-terminal.ts
+++ b/apps/desktop/src/main/runtime-host-ssh-terminal.ts
@@ -39,6 +39,7 @@ import {
decodeRuntimeHostActivationFrame,
decodeRuntimeHostAccessManagementFrame,
decodeRuntimeHostPeerManagementFrame,
+ decodeRuntimeHostPeerMeshManagementFrame,
decodeRuntimeHostServiceManagementFrame,
decodeRuntimeHostSetupFrame,
RUNTIME_HOST_ACTIVATION_FRAME_MAX_BYTES,
@@ -49,6 +50,8 @@ import {
RUNTIME_HOST_OPERATOR_PROJECT_DIRECTORY_CONFIGURATION_REQUEST_ENV,
RUNTIME_HOST_OPERATOR_UPDATE_SCHEDULER_CAPABILITY,
RUNTIME_HOST_PEER_MANAGEMENT_FRAME_PREFIX,
+ RUNTIME_HOST_PEER_MESH_MANAGEMENT_FRAME_MAX_BYTES,
+ RUNTIME_HOST_PEER_MESH_MANAGEMENT_FRAME_PREFIX,
RUNTIME_HOST_SERVICE_MANAGEMENT_FRAME_PREFIX,
RUNTIME_HOST_SETUP_FRAME_PREFIX,
type RuntimeHostAccessManagementFrame,
@@ -56,6 +59,8 @@ import {
type RuntimeHostManagedUpdatePolicy,
type RuntimeHostPeerManagementAction,
type RuntimeHostPeerManagementFrame,
+ type RuntimeHostPeerMeshManagementAction,
+ type RuntimeHostPeerMeshManagementFrame,
type RuntimeHostOperatorCapability,
type RuntimeHostServiceManagementAction,
type RuntimeHostServiceManagementFrame,
@@ -166,6 +171,19 @@ export interface DesktopRuntimeHostSshPeerManagementInput {
readonly signal?: AbortSignal;
}
+export interface DesktopRuntimeHostSshPeerMeshManagementInput {
+ readonly destination: string;
+ readonly sshPort?: number;
+ readonly operatorPath: string;
+ readonly action: RuntimeHostPeerMeshManagementAction;
+ readonly expectedTarget: DesktopRuntimeHostSshManagementInput['expectedTarget'];
+ readonly meshId?: string;
+ readonly peerId?: string;
+ readonly ttlMs?: number;
+ readonly invitation?: string;
+ readonly signal?: AbortSignal;
+}
+
export interface DesktopRuntimeHostSshCleanupInput {
readonly destination: string;
readonly sshPort?: number;
@@ -261,6 +279,9 @@ export function createDesktopRuntimeHostSshTerminal(input: {
runPeerManagement(
input: DesktopRuntimeHostSshPeerManagementInput,
): Promise<RuntimeHostPeerManagementFrame>;
+ runPeerMeshManagement(
+ input: DesktopRuntimeHostSshPeerMeshManagementInput,
+ ): Promise<Exclude<RuntimeHostPeerMeshManagementFrame, { kind: 'input' }>>;
cleanupManagedDeployment(input: DesktopRuntimeHostSshCleanupInput): Promise<void>;
close(): Promise<void>;
} {
@@ -500,6 +521,7 @@ export function createDesktopRuntimeHostSshTerminal(input: {
readonly frameAction: (frame: Frame) => string;
readonly isTerminalFrame?: (frame: Frame) => boolean;
readonly onProgress?: (frame: Frame) => void;
+ readonly inputLine?: string;
readonly label: string;
readonly timeoutMs?: number;
}): Promise<Frame> => {
@@ -511,6 +533,12 @@ export function createDesktopRuntimeHostSshTerminal(input: {
let failure: Error | undefined;
let activeTerminal: ActiveTerminal | undefined;
let receivedProgress = false;
+ let inputSent = false;
+ const sendInput = () => {
+ if (inputSent || options.inputLine === undefined || !activeTerminal) return;
+ inputSent = true;
+ activeTerminal.pty.write(`${options.inputLine}\r`);
+ };
const filter = createRuntimeHostFramedOutputFilter({
prefix: options.prefix,
pendingMaxBytes: options.pendingMaxBytes,
@@ -526,6 +554,7 @@ export function createDesktopRuntimeHostSshTerminal(input: {
receivedProgress = true;
if (activeTerminal) suppressPresentation(activeTerminal);
options.onProgress?.(next);
+ sendInput();
return;
}
if (frame) {
@@ -546,6 +575,7 @@ export function createDesktopRuntimeHostSshTerminal(input: {
true,
);
activeTerminal = terminal;
+ if (receivedProgress) sendInput();
if (frame) completePresentation(terminal);
else if (receivedProgress) suppressPresentation(terminal);
const wait = await waitForTerminalProcess(process, {
@@ -791,6 +821,24 @@ export function createDesktopRuntimeHostSshTerminal(input: {
frameAction: (frame) => frame.action,
label: 'Remote Runtime Host direct-peer management',
}),
+ runPeerMeshManagement: async (meshInput) => {
+ const frame = await runFramedManagement({
+ ...meshInput,
+ remoteCommand: runtimeHostPeerMeshManagementRemoteCommand(meshInput),
+ prefix: RUNTIME_HOST_PEER_MESH_MANAGEMENT_FRAME_PREFIX,
+ pendingMaxBytes: RUNTIME_HOST_PEER_MESH_MANAGEMENT_FRAME_MAX_BYTES,
+ decode: decodeRuntimeHostPeerMeshManagementFrame,
+ action: meshInput.action,
+ frameAction: (candidate) => candidate.action,
+ isTerminalFrame: (candidate) => candidate.kind !== 'input',
+ ...(meshInput.invitation ? { inputLine: meshInput.invitation } : {}),
+ label: 'Remote Runtime Host Peer Mesh management',
+ });
+ if (frame.kind === 'input') {
+ throw new Error('Remote Runtime Host Peer Mesh management ended before its result');
+ }
+ return frame;
+ },
cleanupManagedDeployment: async (cleanupInput) => {
if (closed) throw new Error('Runtime Host SSH terminal is closed');
cleanupInput.signal?.throwIfAborted();
@@ -1221,6 +1269,22 @@ function runtimeHostPeerManagementRemoteCommand(
return `exec "\${SHELL:-/bin/sh}" -lic ${quotePosix(`exec ${command}`)}`;
}
+function runtimeHostPeerMeshManagementRemoteCommand(
+ input: DesktopRuntimeHostSshPeerMeshManagementInput,
+): string {
+ const command = [
+ input.operatorPath,
+ 'mesh',
+ input.action,
+ '--framed',
+ ...(input.meshId ? ['--mesh', input.meshId] : []),
+ ...(input.peerId ? ['--peer', input.peerId] : []),
+ ...(input.ttlMs === undefined ? [] : ['--ttl-ms', String(input.ttlMs)]),
+ ...managedServiceTargetArgs(input.expectedTarget),
+ ].map(quotePosix).join(' ');
+ return `exec "\${SHELL:-/bin/sh}" -lic ${quotePosix(`exec ${command}`)}`;
+}
+
function runtimeHostManagedDeploymentCleanupRemoteCommand(
input: DesktopRuntimeHostSshCleanupInput,
): string {
diff --git a/apps/desktop/src/preload/bridge-contract.d.ts b/apps/desktop/src/preload/bridge-contract.d.ts
index c7dee0316..5068f72fa 100644
--- a/apps/desktop/src/preload/bridge-contract.d.ts
+++ b/apps/desktop/src/preload/bridge-contract.d.ts
@@ -520,6 +520,18 @@ export interface DesktopRuntimeHostDirectPeerSnapshot {
readonly managementAvailable: boolean;
}
+export type DesktopRuntimeHostPeerMeshTarget =
+ | { readonly kind: 'desktop' }
+ | { readonly kind: 'managed_host'; readonly profileId: string };
+
+export type DesktopRuntimeHostPeerMeshAction =
+ import('@maka/runtime-host/operator').RuntimeHostPeerMeshManagementAction;
+
+export type DesktopRuntimeHostPeerMeshResult =
+ | import('@maka/runtime-host/protocol').PeerMeshQueryResult
+ | import('@maka/runtime-host/protocol').PeerMeshProjection
+ | import('@maka/runtime-host/protocol').PeerMeshInvitationV1;
+
type RuntimeHostUpdatePolicyResult = Extract<
RuntimeHostServiceManagementFrame,
{ kind: 'result'; action: 'update_policy' }
@@ -729,6 +741,14 @@ export interface MakaBridge {
): Promise<DesktopRuntimeHostAccessSnapshot>;
};
+ runtimeHostPeerMesh: {
+ execute(
+ target: DesktopRuntimeHostPeerMeshTarget,
+ action: DesktopRuntimeHostPeerMeshAction,
+ input?: { readonly meshId?: string; readonly peerId?: string; readonly invitation?: string },
+ ): Promise<DesktopRuntimeHostPeerMeshResult>;
+ };
+
newTasks: {
getCatalog(): Promise<DesktopNewTaskCatalog>;
subscribeChanges(handler: () => void): () => void;
diff --git a/apps/desktop/src/preload/preload.ts b/apps/desktop/src/preload/preload.ts
index eec694043..f9076b076 100644
--- a/apps/desktop/src/preload/preload.ts
+++ b/apps/desktop/src/preload/preload.ts
@@ -1374,6 +1374,22 @@ const makaBridge = {
);
},
},
+ runtimeHostPeerMesh: {
+ execute(
+ target: import('./bridge-contract.js').DesktopRuntimeHostPeerMeshTarget,
+ action: import('./bridge-contract.js').DesktopRuntimeHostPeerMeshAction,
+ input: { readonly meshId?: string; readonly peerId?: string; readonly invitation?: string } = {},
+ ) {
+ return ipcRenderer.invoke(
+ 'runtime-host-peer-mesh:execute',
+ target,
+ action,
+ input.meshId,
+ input.peerId,
+ input.invitation,
+ );
+ },
+ },
newTasks: {
getCatalog(): Promise<DesktopNewTaskCatalog> {
return loadNewTaskCatalog();
diff --git a/apps/desktop/src/renderer/locales/settings-projects-copy.ts b/apps/desktop/src/renderer/locales/settings-projects-copy.ts
index 048f63fbc..84ed7af67 100644
--- a/apps/desktop/src/renderer/locales/settings-projects-copy.ts
+++ b/apps/desktop/src/renderer/locales/settings-projects-copy.ts
@@ -138,6 +138,9 @@ export type SettingsProjectsCopy = {
directPeerDisable: string;
directPeerAddProfile: string;
directPeerActionFailed: string;
+ peerMesh: string;
+ peerMeshHelp: string;
+ managePeerMesh: string;
installedVersion: string;
operatingSystem: string;
processId: string;
@@ -424,6 +427,9 @@ const SETTINGS_PROJECTS_COPY_BY_LOCALE = {
directPeerDisable: '停用',
directPeerAddProfile: '添加到 Desktop',
directPeerActionFailed: 'Direct peer 操作失败',
+ peerMesh: 'Peer Mesh',
+ peerMeshHelp: '管理本 Desktop peer 的私有 Mesh membership 和邀请',
+ managePeerMesh: '管理 Peer Mesh',
installedVersion: '版本',
operatingSystem: '系统',
processId: '进程 ID',
@@ -710,6 +716,9 @@ const SETTINGS_PROJECTS_COPY_BY_LOCALE = {
directPeerDisable: 'Disable',
directPeerAddProfile: 'Add to Desktop',
directPeerActionFailed: 'Direct peer action failed',
+ peerMesh: 'Peer Mesh',
+ peerMeshHelp: 'Manage private Mesh memberships and invitations for this Desktop peer',
+ managePeerMesh: 'Manage Peer Mesh',
installedVersion: 'Version',
operatingSystem: 'System',
processId: 'Process ID',
diff --git a/apps/desktop/src/renderer/settings/runtime-host-peer-mesh-dialog.tsx b/apps/desktop/src/renderer/settings/runtime-host-peer-mesh-dialog.tsx
new file mode 100644
index 000000000..da19c6ffc
--- /dev/null
+++ b/apps/desktop/src/renderer/settings/runtime-host-peer-mesh-dialog.tsx
@@ -0,0 +1,363 @@
+/*
+ * Licensed to the Apache Software Foundation (ASF) under one
+ * or more contributor license agreements. See the NOTICE file
+ * distributed with this work for additional information
+ * regarding copyright ownership. The ASF licenses this file
+ * to you under the Apache License, Version 2.0 (the
+ * "License"); you may not use this file except in compliance
+ * with the License. You may obtain a copy of the License at
+ *
+ * http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing,
+ * software distributed under the License is distributed on an
+ * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+ * KIND, either express or implied. See the License for the
+ * specific language governing permissions and limitations
+ * under the License.
+ */
+
+import { useCallback, useEffect, useState } from 'react';
+import { Banner } from '@astryxdesign/core';
+import { Dialog, DialogHeader } from '@astryxdesign/core/Dialog';
+import { Layout, LayoutContent, LayoutFooter } from '@astryxdesign/core/Layout';
+import type { PeerMeshProjection, PeerMeshQueryResult } from '@maka/runtime-host/protocol';
+import { Badge, Button, MoreMenu, Text, TextArea, useToast, useUiLocale } from '@maka/ui';
+import type { DesktopRuntimeHostPeerMeshTarget } from '../../preload/bridge-contract.js';
+import { settingsActionErrorMessage } from './settings-error-copy.js';
+
+export function RuntimeHostPeerMeshDialog(props: {
+ readonly target: DesktopRuntimeHostPeerMeshTarget;
+ readonly targetName: string;
+ readonly onClose: () => void;
+}) {
+ const locale = useUiLocale();
+ const copy = peerMeshCopy(locale);
+ const toast = useToast();
+ const [snapshot, setSnapshot] = useState<PeerMeshQueryResult>();
+ const [joinDraft, setJoinDraft] = useState('');
+ const [invitation, setInvitation] = useState<{
+ readonly meshId: string;
+ readonly code: string;
+ readonly expiresAt: number;
+ }>();
+ const [error, setError] = useState<string>();
+ const [working, setWorking] = useState(false);
+
+ const refresh = useCallback(async () => {
+ const result = await window.maka.runtimeHostPeerMesh.execute(props.target, 'status');
+ if (!isSnapshot(result)) throw new Error(copy.invalidResult);
+ setSnapshot(result);
+ }, [copy.invalidResult, props.target]);
+
+ useEffect(() => {
+ void refresh().catch((failure) => setError(settingsActionErrorMessage(failure, locale)));
+ }, [locale, refresh]);
+
+ async function run(action: 'create' | 'reconcile'): Promise<void> {
+ setWorking(true);
+ setError(undefined);
+ try {
+ await window.maka.runtimeHostPeerMesh.execute(props.target, action);
+ await refresh();
+ } catch (failure) {
+ setError(settingsActionErrorMessage(failure, locale));
+ } finally {
+ setWorking(false);
+ }
+ }
+
+ async function join(): Promise<void> {
+ setWorking(true);
+ setError(undefined);
+ try {
+ await window.maka.runtimeHostPeerMesh.execute(props.target, 'join', {
+ invitation: joinDraft.trim(),
+ });
+ setJoinDraft('');
+ await refresh();
+ } catch (failure) {
+ setError(settingsActionErrorMessage(failure, locale));
+ } finally {
+ setWorking(false);
+ }
+ }
+
+ async function createInvitation(meshId: string): Promise<void> {
+ setWorking(true);
+ setError(undefined);
+ try {
+ const result = await window.maka.runtimeHostPeerMesh.execute(props.target, 'invite', {
+ meshId,
+ });
+ if (!('expiresAt' in result)) throw new Error(copy.invalidResult);
+ setInvitation({ meshId, code: JSON.stringify(result), expiresAt: result.expiresAt });
+ await refresh();
+ } catch (failure) {
+ setError(settingsActionErrorMessage(failure, locale));
+ } finally {
+ setWorking(false);
+ }
+ }
+
+ async function mutate(
+ action: 'remove' | 'leave' | 'close',
+ meshId: string,
+ peerId?: string,
+ ): Promise<void> {
+ const confirmed = await toast.confirm({
+ title: action === 'close' ? copy.closeConfirm : action === 'leave' ? copy.leaveConfirm : copy.removeConfirm,
+ confirmLabel: action === 'close' ? copy.closeMesh : action === 'leave' ? copy.leave : copy.remove,
+ cancelLabel: copy.cancel,
+ destructive: action !== 'leave',
+ });
+ if (!confirmed) return;
+ setWorking(true);
+ setError(undefined);
+ try {
+ await window.maka.runtimeHostPeerMesh.execute(props.target, action, { meshId, peerId });
+ if (action === 'close' && invitation?.meshId === meshId) setInvitation(undefined);
+ await refresh();
+ } catch (failure) {
+ setError(settingsActionErrorMessage(failure, locale));
+ } finally {
+ setWorking(false);
+ }
+ }
+
+ async function copyInvitation(): Promise<void> {
+ if (!invitation) return;
+ try {
+ await navigator.clipboard.writeText(invitation.code);
+ toast.success(copy.invitationCopied);
+ } catch (failure) {
+ setError(settingsActionErrorMessage(failure, locale));
+ }
+ }
+
+ return (
+ <Dialog
+ isOpen
+ onOpenChange={(open) => {
+ if (!open && !working) props.onClose();
+ }}
+ purpose="form"
+ width={680}
+ >
+ <Layout
+ header={(
+ <DialogHeader
+ title={copy.title}
+ subtitle={props.targetName}
+ onOpenChange={(open) => {
+ if (!open && !working) props.onClose();
+ }}
+ />
+ )}
+ content={(
+ <LayoutContent padding={4}>
+ <div className="settingsPeerMesh">
+ {error ? <Banner status="error" title={copy.failed} description={error} /> : null}
+ {snapshot && !snapshot.available ? (
+ <Banner status="warning" title={copy.unavailable} />
+ ) : null}
+ {snapshot?.available ? (
+ <div className="settingsPeerMeshIdentity">
+ <Text type="supporting" color="secondary">{copy.thisPeer}</Text>
+ <code>{snapshot.localPeerId ? abbreviate(snapshot.localPeerId) : '—'}</code>
+ </div>
+ ) : null}
+ {snapshot?.meshes.length === 0 ? (
+ <Text type="supporting" color="secondary">{copy.empty}</Text>
+ ) : null}
+ {snapshot?.meshes.map((mesh) => (
+ <MeshCard
+ key={mesh.meshId}
+ mesh={mesh}
+ copy={copy}
+ working={working}
+ onInvite={() => void createInvitation(mesh.meshId)}
+ onRemove={(peerId) => void mutate('remove', mesh.meshId, peerId)}
+ onLeave={() => void mutate('leave', mesh.meshId)}
+ onClose={() => void mutate('close', mesh.meshId)}
+ />
+ ))}
+ {snapshot?.available ? (
+ <div className="settingsPeerMeshJoin">
+ <TextArea
+ label={copy.joinCode}
+ value={joinDraft}
+ rows={3}
+ hasSpellCheck={false}
+ isDisabled={working}
+ onChange={setJoinDraft}
+ />
+ <Button
+ variant="secondary"
+ size="sm"
+ label={copy.join}
+ isDisabled={working || !joinDraft.trim()}
+ onClick={() => void join()}
+ />
+ </div>
+ ) : null}
+ {invitation ? (
+ <div className="settingsPeerMeshInvitation">
+ <Banner status="warning" title={copy.invitationWarning} />
+ <Text type="supporting" color="secondary">
+ {copy.invitationExpires(new Date(invitation.expiresAt).toLocaleString())}
+ </Text>
+ <TextArea
+ label={copy.invitation}
+ value={invitation.code}
+ rows={4}
+ hasSpellCheck={false}
+ isReadOnly
+ onChange={() => undefined}
+ />
+ <Button
+ variant="secondary"
+ size="sm"
+ label={copy.copyInvitation}
+ onClick={() => void copyInvitation()}
+ />
+ </div>
+ ) : null}
+ </div>
+ </LayoutContent>
+ )}
+ footer={(
+ <LayoutFooter>
+ <Button variant="secondary" label={copy.done} isDisabled={working} onClick={props.onClose} />
+ <Button
+ variant="secondary"
+ label={copy.refresh}
+ isDisabled={working || !snapshot?.available}
+ onClick={() => void run('reconcile')}
+ />
+ <Button
+ variant="primary"
+ label={copy.create}
+ isDisabled={working || !snapshot?.available}
+ onClick={() => void run('create')}
+ />
+ </LayoutFooter>
+ )}
+ />
+ </Dialog>
+ );
+}
+
+function MeshCard(props: {
+ readonly mesh: PeerMeshProjection;
+ readonly copy: ReturnType<typeof peerMeshCopy>;
+ readonly working: boolean;
+ readonly onInvite: () => void;
+ readonly onRemove: (peerId: string) => void;
+ readonly onLeave: () => void;
+ readonly onClose: () => void;
+}) {
+ const { mesh, copy } = props;
+ return (
+ <section className="settingsPeerMeshCard">
+ <div className="settingsPeerMeshCardHeading">
+ <div>
+ <Text type="body" weight="semibold">{copy.mesh} {fingerprint(mesh.meshId)}</Text>
+ <Text type="supporting" color="secondary">
+ {copy.revision(mesh.revision)} · {copy.memberCount(mesh.members.length)}
+ {mesh.pendingInvitationCount > 0 ? ` · ${copy.pending(mesh.pendingInvitationCount)}` : ''}
+ </Text>
+ </div>
+ <Badge
+ variant={mesh.closed ? 'neutral' : mesh.role === 'authority' ? 'success' : 'info'}
+ label={mesh.closed ? copy.closed : mesh.role === 'authority' ? copy.authority : copy.member}
+ />
+ </div>
+ <div className="settingsPeerMeshMembers">
+ {mesh.members.map((peerId) => (
+ <div className="settingsPeerMeshMember" key={peerId}>
+ <code title={peerId}>{abbreviate(peerId)}</code>
+ <div className="settingsPeerMeshMemberActions">
+ <Badge
+ variant="neutral"
+ label={copy.routeState[
+ mesh.memberRoutes.find((route) => route.peerId === peerId)?.state ?? 'unknown'
+ ]}
+ />
+ {peerId === mesh.localPeerId ? <Badge variant="neutral" label={copy.you} /> : null}
+ {peerId === mesh.authorityPeerId ? <Badge variant="neutral" label={copy.authority} /> : null}
+ {mesh.role === 'authority' && peerId !== mesh.localPeerId && !mesh.closed ? (
+ <MoreMenu
+ label={copy.memberActions(peerId)}
+ size="sm"
+ items={[{ label: copy.remove, isDisabled: props.working, onClick: () => props.onRemove(peerId) }]}
+ />
+ ) : null}
+ </div>
+ </div>
+ ))}
+ </div>
+ {!mesh.closed ? (
+ <div className="settingsPeerMeshActions">
+ {mesh.role === 'authority' ? (
+ <>
+ <Button variant="secondary" size="sm" label={copy.invite} isDisabled={props.working} onClick={props.onInvite} />
+ <MoreMenu
+ label={copy.meshActions}
+ size="sm"
+ items={[{ label: copy.closeMesh, isDisabled: props.working, onClick: props.onClose }]}
+ />
+ </>
+ ) : (
+ <Button variant="secondary" size="sm" label={copy.leave} isDisabled={props.working} onClick={props.onLeave} />
+ )}
+ </div>
+ ) : null}
+ </section>
+ );
+}
+
+function isSnapshot(value: unknown): value is PeerMeshQueryResult {
+ return Boolean(value && typeof value === 'object' && 'available' in value && 'meshes' in value);
+}
+
+function fingerprint(meshId: string): string {
+ return meshId.length <= 16 ? meshId : `${meshId.slice(0, 8)}…${meshId.slice(-6)}`;
+}
+
+function abbreviate(peerId: string): string {
+ return peerId.length <= 22 ? peerId : `${peerId.slice(0, 11)}…${peerId.slice(-7)}`;
+}
+
+function peerMeshCopy(locale: string) {
+ const zh = locale.startsWith('zh');
+ return zh ? {
+ title: 'Peer Mesh(实验性)', failed: 'Peer Mesh 操作失败', invalidResult: 'Peer Mesh 返回了无效结果',
+ unavailable: '当前 endpoint 不支持 Peer Mesh', thisPeer: '当前 Peer', empty: '尚未加入任何 Mesh',
+ mesh: 'Mesh', authority: '管理者', member: '成员', closed: '已关闭', you: '本机',
+ revision: (value: number) => `版本 ${value}`, memberCount: (value: number) => `${value} 个成员`,
+ pending: (value: number) => `${value} 个待使用邀请`,
+ routeState: { local: '本机', route_available: '路径可用', coordination_only: '仅协调路径', stale: '路径已过期', unknown: '路径未知' },
+ joinCode: '邀请代码', join: '加入', invitation: '邀请代码', invite: '邀请成员',
+ invitationWarning: '该代码只能使用一次;获得代码的人可以让一个 peer 加入此 Mesh。',
+ invitationExpires: (value: string) => `有效期至 ${value}`,
+ invitationCopied: '邀请代码已复制', copyInvitation: '复制', create: '创建 Mesh', refresh: '同步', done: '完成',
+ leave: '退出 Mesh', closeMesh: '关闭 Mesh', remove: '移除成员', cancel: '取消',
+ closeConfirm: '关闭这个 Mesh?', leaveConfirm: '退出这个 Mesh?', removeConfirm: '移除这个成员?',
+ meshActions: 'Mesh 操作', memberActions: (peerId: string) => `${peerId} 的操作`,
+ } : {
+ title: 'Peer Mesh (experimental)', failed: 'Peer Mesh operation failed', invalidResult: 'Peer Mesh returned an invalid result',
+ unavailable: 'Peer Mesh is unavailable for this endpoint', thisPeer: 'This peer', empty: 'Not a member of any Mesh yet',
+ mesh: 'Mesh', authority: 'Authority', member: 'Member', closed: 'Closed', you: 'This peer',
+ revision: (value: number) => `Revision ${value}`, memberCount: (value: number) => `${value} members`,
+ pending: (value: number) => `${value} pending invites`,
+ routeState: { local: 'Local', route_available: 'Route known', coordination_only: 'Coordination only', stale: 'Stale route', unknown: 'Route unknown' },
+ joinCode: 'Invitation code', join: 'Join', invitation: 'Invitation code', invite: 'Invite member',
+ invitationWarning: 'This code works once. Anyone holding it can admit one peer to this Mesh.',
+ invitationExpires: (value: string) => `Expires ${value}`,
+ invitationCopied: 'Invitation code copied', copyInvitation: 'Copy', create: 'Create Mesh', refresh: 'Sync', done: 'Done',
+ leave: 'Leave Mesh', closeMesh: 'Close Mesh', remove: 'Remove member', cancel: 'Cancel',
+ closeConfirm: 'Close this Mesh?', leaveConfirm: 'Leave this Mesh?', removeConfirm: 'Remove this member?',
+ meshActions: 'Mesh actions', memberActions: (peerId: string) => `Actions for ${peerId}`,
+ };
+}
diff --git a/apps/desktop/src/renderer/settings/runtime-host-profiles-section.tsx b/apps/desktop/src/renderer/settings/runtime-host-profiles-section.tsx
index 903f10c63..7fe872cc7 100644
--- a/apps/desktop/src/renderer/settings/runtime-host-profiles-section.tsx
+++ b/apps/desktop/src/renderer/settings/runtime-host-profiles-section.tsx
@@ -29,6 +29,7 @@ import {
} from "@astryxdesign/core";
import type {
DesktopLocalRuntimeHostRemoteAccessSnapshot,
+ DesktopRuntimeHostPeerMeshTarget,
} from '../../preload/bridge-contract.js';
import type {
RemoteRuntimeHostProfile,
@@ -53,6 +54,7 @@ import { SettingsField, SettingsRow, SettingsSection } from "./settings-section.
import { RuntimeHostOnboardingDialog } from './runtime-host-onboarding-dialog.js';
import { RuntimeHostManagementDialog } from './runtime-host-management-dialog.js';
import { RuntimeHostConnectionCodeDialog } from './runtime-host-connection-code-dialog.js';
+import { RuntimeHostPeerMeshDialog } from './runtime-host-peer-mesh-dialog.js';
type RemoteTransportKind = RuntimeHostRemoteTransport["kind"];
@@ -89,6 +91,10 @@ export function RuntimeHostProfilesSection(props: {
const [connectionCodeDialog, setConnectionCodeDialog] = useState<
{ readonly mode: 'import' } | { readonly mode: 'share'; readonly connectionCode: string }
>();
+ const [peerMeshTarget, setPeerMeshTarget] = useState<{
+ readonly target: DesktopRuntimeHostPeerMeshTarget;
+ readonly name: string;
+ }>();
const [switching, setSwitching] = useState(false);
const [draft, setDraft] = useState(createRemoteHostDraft);
@@ -483,6 +489,22 @@ export function RuntimeHostProfilesSection(props: {
</HStack>
)}
/>
+ <SettingsRow
+ label={copy.peerMesh}
+ description={copy.peerMeshHelp}
+ end={(
+ <Button
+ variant="secondary"
+ size="sm"
+ label={copy.managePeerMesh}
+ isDisabled={switching}
+ onClick={() => setPeerMeshTarget({
+ target: { kind: 'desktop' },
+ name: copy.thisComputerRemoteAccess,
+ })}
+ />
+ )}
+ />
</SettingsSection>
<SettingsSection
@@ -668,6 +690,13 @@ export function RuntimeHostProfilesSection(props: {
label: copy.manage,
isDisabled: switching,
onClick: () => setManagedProfile(profile),
+ }, {
+ label: copy.managePeerMesh,
+ isDisabled: switching,
+ onClick: () => setPeerMeshTarget({
+ target: { kind: 'managed_host', profileId: profile.id },
+ name: profile.name,
+ }),
}]
: []),
{
@@ -704,6 +733,13 @@ export function RuntimeHostProfilesSection(props: {
void reload();
}}
/>
+ {peerMeshTarget ? (
+ <RuntimeHostPeerMeshDialog
+ target={peerMeshTarget.target}
+ targetName={peerMeshTarget.name}
+ onClose={() => setPeerMeshTarget(undefined)}
+ />
+ ) : null}
{connectionCodeDialog?.mode === 'import' ? (
<RuntimeHostConnectionCodeDialog
mode="import"
diff --git a/apps/desktop/src/renderer/styles/settings/runtime-host.css b/apps/desktop/src/renderer/styles/settings/runtime-host.css
index a05e7b8d0..1b8d7896c 100644
--- a/apps/desktop/src/renderer/styles/settings/runtime-host.css
+++ b/apps/desktop/src/renderer/styles/settings/runtime-host.css
@@ -253,6 +253,52 @@
gap: var(--space-2);
}
+.settingsPeerMesh {
+ display: flex;
+ flex-direction: column;
+ gap: var(--space-4);
+}
+
+.settingsPeerMeshIdentity,
+.settingsPeerMeshCardHeading,
+.settingsPeerMeshMember,
+.settingsPeerMeshMemberActions,
+.settingsPeerMeshActions {
+ display: flex;
+ align-items: center;
+ justify-content: space-between;
+ gap: var(--space-2);
+}
+
+.settingsPeerMeshCard {
+ display: flex;
+ flex-direction: column;
+ gap: var(--space-3);
+ padding: var(--space-3);
+ border: var(--border-width-hairline) solid var(--border-soft);
+ border-radius: var(--radius-container);
+}
+
+.settingsPeerMeshMembers {
+ display: flex;
+ flex-direction: column;
+ gap: var(--space-2);
+}
+
+.settingsPeerMeshMember {
+ min-height: 32px;
+ padding-block: var(--space-1);
+ border-top: var(--border-width-hairline) solid var(--border-soft);
+}
+
+.settingsPeerMeshJoin,
+.settingsPeerMeshInvitation {
+ display: flex;
+ flex-direction: column;
+ align-items: flex-start;
+ gap: var(--space-2);
+}
+
@media (max-height: 620px) {
.settingsRuntimeHostSshTerminal {
height: 220px;
diff --git a/docs/astryx-surface-file-inventory.md b/docs/astryx-surface-file-inventory.md
index 095ad3276..9eabcf137 100644
--- a/docs/astryx-surface-file-inventory.md
+++ b/docs/astryx-surface-file-inventory.md
@@ -5,7 +5,7 @@ Each row is one on-disk product surface file. Regenerated inventory must stay in
Wiki bar: Design Conventions · API Use-the-System · Theming · Container Padding.
-**Totals:** 218 files — blocker 0, polish 1, aligned 217.
+**Totals:** 219 files — blocker 0, polish 1, aligned 218.
## Exclusions (explicit)
@@ -104,6 +104,7 @@ Wiki bar: Design Conventions · API Use-the-System · Theming · Container Paddi
| `apps/desktop/src/renderer/settings/runtime-host-interaction-boundary.tsx` | settings-module | none | aligned — no raw controls; no Astryx JSX usage | aligned |
| `apps/desktop/src/renderer/settings/runtime-host-management-dialog.tsx` | settings-module | Badge, Banner, Button, Dialog, DialogHeader, Layout, LayoutContent, Selector, Spinner, Text | aligned — uses Astryx (Badge, Banner, Button, Dialog, DialogHeader, Layout, LayoutContent, Selector) | aligned |
| `apps/desktop/src/renderer/settings/runtime-host-onboarding-dialog.tsx` | settings-module | Banner, Button, Dialog, DialogHeader, Layout, LayoutContent, SegmentedControl, SegmentedControlItem, Selector, Spinner, Text | aligned — uses Astryx (Banner, Button, Dialog, DialogHeader, Layout, LayoutContent, SegmentedControl, SegmentedControlItem) | aligned |
+| `apps/desktop/src/renderer/settings/runtime-host-peer-mesh-dialog.tsx` | settings-module | Badge, Banner, Button, Dialog, DialogHeader, Layout, LayoutContent | aligned — uses Astryx (Badge, Banner, Button, Dialog, DialogHeader, Layout, LayoutContent) | aligned |
| `apps/desktop/src/renderer/settings/runtime-host-profiles-section.tsx` | settings-module | Badge, Banner, Button, HStack, List, ListItem, SegmentedControl, SegmentedControlItem, Selector, Switch | aligned — uses Astryx (Badge, Banner, Button, HStack, List, ListItem, SegmentedControl, SegmentedControlItem) | aligned |
| `apps/desktop/src/renderer/settings/runtime-host-project-directory-editor.tsx` | settings-module | Button | aligned — uses Astryx (Button) | aligned |
| `apps/desktop/src/renderer/settings/runtime-host-settings-target.tsx` | settings-module | none | aligned — no raw controls; no Astryx JSX usage | aligned |
diff --git a/docs/astryx-surface-file-inventory.paths b/docs/astryx-surface-file-inventory.paths
index 60e42249b..67daab153 100644
--- a/docs/astryx-surface-file-inventory.paths
+++ b/docs/astryx-surface-file-inventory.paths
@@ -76,6 +76,7 @@ apps/desktop/src/renderer/settings/runtime-host-connection-code-dialog.tsx
apps/desktop/src/renderer/settings/runtime-host-interaction-boundary.tsx
apps/desktop/src/renderer/settings/runtime-host-management-dialog.tsx
apps/desktop/src/renderer/settings/runtime-host-onboarding-dialog.tsx
+apps/desktop/src/renderer/settings/runtime-host-peer-mesh-dialog.tsx
apps/desktop/src/renderer/settings/runtime-host-profiles-section.tsx
apps/desktop/src/renderer/settings/runtime-host-project-directory-editor.tsx
apps/desktop/src/renderer/settings/runtime-host-settings-target.tsx
diff --git a/packages/cli/src/__tests__/runtime-host-operator-command.test.ts b/packages/cli/src/__tests__/runtime-host-operator-command.test.ts
index e2236ddad..e014f1219 100644
--- a/packages/cli/src/__tests__/runtime-host-operator-command.test.ts
+++ b/packages/cli/src/__tests__/runtime-host-operator-command.test.ts
@@ -41,6 +41,42 @@ const projectRootA = process.platform === 'win32' ? 'C:\\srv\\projects' : '/srv/
const projectRootB = process.platform === 'win32' ? 'D:\\data' : '/mnt/data';
describe('Runtime Host operator commands', () => {
+ test('parses resident Peer Mesh management without accepting invitations in argv', () => {
+ const target = {
+ serviceId: 'b'.repeat(64),
+ rootPath: '/srv/maka',
+ rootId: 'a'.repeat(64),
+ deploymentId: '00000000-0000-4000-8000-000000000001',
+ };
+ const base = [
+ '--managed-root-id',
+ target.rootId,
+ '--operator-deployment-id',
+ target.deploymentId,
+ '--expected-service-id',
+ target.serviceId,
+ '--expected-root-path',
+ target.rootPath,
+ '--expected-root-id',
+ target.rootId,
+ '--expected-deployment-id',
+ target.deploymentId,
+ ];
+ assert.deepEqual(parseRuntimeHostCommand(['service', 'mesh', 'join', '--framed', ...base]), {
+ kind: 'runtime-host-service-peer-mesh',
+ action: 'join',
+ json: false,
+ framed: true,
+ managedRootId: target.rootId,
+ operatorDeploymentId: target.deploymentId,
+ expectedTarget: target,
+ });
+ assert.equal(
+ parseRuntimeHostCommand(['service', 'mesh', 'join', '--invitation', 'secret', ...base]).kind,
+ 'error',
+ );
+ });
+
test('parses and emits the stable framed managed activation contract', async () => {
const rootId = 'a'.repeat(64);
assert.deepEqual(parseRuntimeHostCommand(['activate', '--framed', '--root-id', rootId]), {
@@ -336,6 +372,14 @@ describe('Runtime Host operator commands', () => {
'host.upgrade.prepare',
'hosted.execution.cancel',
'hosted.execution.start',
+ 'peer.mesh.close',
+ 'peer.mesh.create',
+ 'peer.mesh.invite',
+ 'peer.mesh.join',
+ 'peer.mesh.leave',
+ 'peer.mesh.query',
+ 'peer.mesh.reconcile',
+ 'peer.mesh.remove',
],
);
});
diff --git a/packages/cli/src/cli-core.ts b/packages/cli/src/cli-core.ts
index 8ee356dd7..e0b9dbaef 100644
--- a/packages/cli/src/cli-core.ts
+++ b/packages/cli/src/cli-core.ts
@@ -147,6 +147,7 @@ function helpText(cliCommand: string): string {
` ${cliCommand} runtime-host service status|start|stop|restart|logs [--json]`,
` ${cliCommand} runtime-host service uninstall --expected-service-id <id> --expected-root-path <path> --expected-root-id <id> [--allow-interrupt-active-tasks]`,
` ${cliCommand} runtime-host service peer enable|disable|status|rotate|descriptor [options]`,
+ ` ${cliCommand} runtime-host service mesh status|create|invite|join|remove|leave|close|reconcile [options]`,
` ${cliCommand} runtime-host service retire --expected-service-id <id> --expected-root-path <path> --expected-root-id <id> [--allow-interrupt-active-tasks]`,
` ${cliCommand} runtime-host service check-update --target <latest|next|version> [--json]`,
` ${cliCommand} runtime-host service update [--target <latest|next|version>] --expected-service-id <id> --expected-root-path <path> --expected-root-id <id> [--allow-interrupt-active-tasks]`,
@@ -316,6 +317,7 @@ export async function runMakaCli(
expectedPeerId: peer.peerId,
listenAddresses: peer.listenAddresses,
coordinationRelays: peer.coordinationRelays,
+ meshDataRoot: join(config.deploymentRoot, 'peer-mesh'),
},
}
: {}),
@@ -476,6 +478,23 @@ export async function runMakaCli(
...(command.allowInterruptActiveTasks ? { allowInterruptActiveTasks: true } : {}),
});
}
+ case 'runtime-host-service-peer-mesh': {
+ const { runRuntimeHostPeerMeshManagementCli } = await import(
+ './runtime-host-peer-mesh-management-command.js'
+ );
+ return runRuntimeHostPeerMeshManagementCli({
+ action: command.action,
+ json: command.json,
+ framed: command.framed ?? false,
+ managedRootId: command.managedRootId,
+ operatorDeploymentId: command.operatorDeploymentId,
+ cliPath: process.argv[1] ?? '',
+ expectedTarget: command.expectedTarget,
+ ...(command.meshId ? { meshId: command.meshId } : {}),
+ ...(command.peerId ? { peerId: command.peerId } : {}),
+ ...(command.ttlMs === undefined ? {} : { ttlMs: command.ttlMs }),
+ });
+ }
case 'runtime-host-service-update': {
const { runManagedRuntimeHostSelectedUpdateCli, runManagedRuntimeHostUpdateCli } =
await import('./runtime-host-update-command.js');
diff --git a/packages/cli/src/runtime-host-cli.ts b/packages/cli/src/runtime-host-cli.ts
index cf2f884e1..653fd1cc1 100644
--- a/packages/cli/src/runtime-host-cli.ts
+++ b/packages/cli/src/runtime-host-cli.ts
@@ -167,6 +167,18 @@ export type RuntimeHostCliCommand =
expectedTarget?: RuntimeHostManagedServiceTarget;
allowInterruptActiveTasks?: true;
}
+ | {
+ kind: 'runtime-host-service-peer-mesh';
+ action: 'status' | 'create' | 'invite' | 'join' | 'remove' | 'leave' | 'close' | 'reconcile';
+ json: boolean;
+ framed?: true;
+ managedRootId: string;
+ operatorDeploymentId: string;
+ expectedTarget: RuntimeHostManagedServiceTarget;
+ meshId?: string;
+ peerId?: string;
+ ttlMs?: number;
+ }
| {
kind: 'runtime-host-service-check-update';
json: boolean;
@@ -633,6 +645,7 @@ function parseSetupCommand(argv: string[]): RuntimeHostCliCommand {
function parseServiceManagementCommand(argv: string[]): RuntimeHostCliCommand {
const action = argv[0];
if (action === 'peer') return parseServicePeerCommand(argv.slice(1));
+ if (action === 'mesh') return parseServicePeerMeshCommand(argv.slice(1));
if (action === 'cleanup-deployment') {
let clientDataRoot: string | undefined;
let finalize = false;
@@ -687,7 +700,7 @@ function parseServiceManagementCommand(argv: string[]): RuntimeHostCliCommand {
return error(
action
? `Unexpected runtime-host service command: ${action}`
- : 'runtime-host service requires install, configure, status, start, stop, restart, retire, check-update, update, update-policy, reconcile-update, logs, or uninstall',
+ : 'runtime-host service requires install, configure, status, start, stop, restart, retire, peer, mesh, check-update, update, update-policy, reconcile-update, logs, or uninstall',
);
}
@@ -955,6 +968,90 @@ function parseServicePeerCommand(argv: string[]): RuntimeHostCliCommand {
};
}
+function parseServicePeerMeshCommand(argv: string[]): RuntimeHostCliCommand {
+ const action = argv[0];
+ if (
+ action !== 'status' &&
+ action !== 'create' &&
+ action !== 'invite' &&
+ action !== 'join' &&
+ action !== 'remove' &&
+ action !== 'leave' &&
+ action !== 'close' &&
+ action !== 'reconcile'
+ ) {
+ return error(
+ action
+ ? `Unexpected runtime-host service mesh command: ${action}`
+ : 'runtime-host service mesh requires status, create, invite, join, remove, leave, close, or reconcile',
+ );
+ }
+ let meshId: string | undefined;
+ let peerId: string | undefined;
+ let ttlMs: number | undefined;
+ const options = parseManagedServiceOptions(argv.slice(1), {
+ allowConfiguration: false,
+ allowFramed: true,
+ valueOptions: {
+ '--mesh': (value) => {
+ if (meshId !== undefined) return error('Duplicate --mesh');
+ if (!value || value.length > 128) return error('--mesh requires a valid Mesh ID');
+ meshId = value;
+ },
+ '--peer': (value) => {
+ if (peerId !== undefined) return error('Duplicate --peer');
+ if (!value || value.length > 256) return error('--peer requires a valid Peer ID');
+ peerId = value;
+ },
+ '--ttl-ms': (value) => {
+ if (ttlMs !== undefined) return error('Duplicate --ttl-ms');
+ const parsed = Number(value);
+ if (!Number.isSafeInteger(parsed) || parsed < 1_000 || parsed > 86_400_000) {
+ return error('--ttl-ms must be between 1000 and 86400000');
+ }
+ ttlMs = parsed;
+ },
+ },
+ });
+ if ('kind' in options) return options;
+ if (!options.managedRootId || !options.operatorDeploymentId || !options.expectedTarget) {
+ return error(
+ 'runtime-host service mesh requires --managed-root-id, --operator-deployment-id, and an expected target',
+ );
+ }
+ const needsMesh =
+ action === 'invite' || action === 'remove' || action === 'leave' || action === 'close';
+ if (needsMesh !== (meshId !== undefined)) {
+ return error(
+ needsMesh
+ ? `runtime-host service mesh ${action} requires --mesh`
+ : '--mesh is only valid with mesh invite, remove, leave, or close',
+ );
+ }
+ if ((action === 'remove') !== (peerId !== undefined)) {
+ return error(
+ action === 'remove'
+ ? 'runtime-host service mesh remove requires --peer'
+ : '--peer is only valid with mesh remove',
+ );
+ }
+ if (ttlMs !== undefined && action !== 'invite') {
+ return error('--ttl-ms is only valid with mesh invite');
+ }
+ return {
+ kind: 'runtime-host-service-peer-mesh',
+ action,
+ json: options.json,
+ ...(options.framed ? { framed: true as const } : {}),
+ managedRootId: options.managedRootId,
+ operatorDeploymentId: options.operatorDeploymentId,
+ expectedTarget: options.expectedTarget,
+ ...(meshId ? { meshId } : {}),
+ ...(peerId ? { peerId } : {}),
+ ...(ttlMs === undefined ? {} : { ttlMs }),
+ };
+}
+
function parseUpdatePolicy(value: string): RuntimeHostManagedUpdatePolicy | RuntimeHostCliError {
if (value === 'manual') return { kind: 'manual' };
const selector = parseUpdateSelector(value, 'update-policy');
diff --git a/packages/cli/src/runtime-host-peer-mesh-management-command.ts b/packages/cli/src/runtime-host-peer-mesh-management-command.ts
new file mode 100644
index 000000000..bf2ffc553
--- /dev/null
+++ b/packages/cli/src/runtime-host-peer-mesh-management-command.ts
@@ -0,0 +1,309 @@
+/*
+ * Licensed to the Apache Software Foundation (ASF) under one
+ * or more contributor license agreements. See the NOTICE file
+ * distributed with this work for additional information
+ * regarding copyright ownership. The ASF licenses this file
+ * to you under the Apache License, Version 2.0 (the
+ * "License"); you may not use this file except in compliance
+ * with the License. You may obtain a copy of the License at
+ *
+ * http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing,
+ * software distributed under the License is distributed on an
+ * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+ * KIND, either express or implied. See the License for the
+ * specific language governing permissions and limitations
+ * under the License.
+ */
+
+import { connectExistingRuntimeHost, type RuntimeHostConnection } from '@maka/runtime-host/client';
+import { decodePeerMeshInvitation } from '@maka/runtime-host/peer-mesh';
+import {
+ encodeRuntimeHostPeerMeshManagementFrame,
+ type RuntimeHostPeerMeshManagementAction,
+ type RuntimeHostPeerMeshManagementFrame,
+} from '@maka/runtime-host/operator';
+import {
+ RUNTIME_HOST_PROTOCOL_VERSION,
+ type OperationInput,
+ type OperationOutput,
+} from '@maka/runtime-host/protocol';
+import {
+ RuntimeHostServiceManagerError,
+ withRuntimeHostManagedServiceDeploymentLock,
+ withRuntimeHostManagedServiceLifecycleLock,
+ type RuntimeHostManagedServiceTarget,
+} from './runtime-host-service-manager.js';
+import { resolveRuntimeHostLifecycleProvider } from './runtime-host-service-management-command.js';
+import { resolveRecoverableRuntimeHostManagedDeployment } from './runtime-host-lifecycle-transaction.js';
+import {
+ assertRuntimeHostManagedOperatorConfig,
+ assertRuntimeHostManagedOperatorDeployment,
+ convergeRuntimeHostManagedOperator,
+ resolveRuntimeHostManagedControlRoot,
+ verifyRuntimeHostManagedOperator,
+} from './runtime-host-managed-deployment.js';
+
+const INPUT_MAX_BYTES = 128 * 1024;
+const PROTOCOL = {
+ min: RUNTIME_HOST_PROTOCOL_VERSION,
+ max: RUNTIME_HOST_PROTOCOL_VERSION,
+} as const;
+
+export interface RuntimeHostPeerMeshManagementCliOptions {
+ readonly action: RuntimeHostPeerMeshManagementAction;
+ readonly json: boolean;
+ readonly framed: boolean;
+ readonly managedRootId: string;
+ readonly operatorDeploymentId: string;
+ readonly cliPath: string;
+ readonly expectedTarget: RuntimeHostManagedServiceTarget;
+ readonly meshId?: string;
+ readonly peerId?: string;
+ readonly ttlMs?: number;
+}
+
+interface RuntimeHostPeerMeshManagementCliDeps {
+ readonly writeStdout: (text: string) => void;
+ readonly writeStderr: (text: string) => void;
+ readonly readInvitation: () => Promise<unknown>;
+ readonly connect: (rootPath: string) => Promise<RuntimeHostConnection>;
+}
+
+export async function runRuntimeHostPeerMeshManagementCli(
+ options: RuntimeHostPeerMeshManagementCliOptions,
+ overrides: Partial<RuntimeHostPeerMeshManagementCliDeps> = {},
+): Promise<number> {
+ const deps: RuntimeHostPeerMeshManagementCliDeps = {
+ writeStdout: (text) => process.stdout.write(text),
+ writeStderr: (text) => process.stderr.write(text),
+ readInvitation: readInvitationFromStdin,
+ connect: connectLocalOwner,
+ ...overrides,
+ };
+ try {
+ const invitation =
+ options.action === 'join' ? await readJoinInvitation(options, deps) : undefined;
+ const controlRoot = resolveRuntimeHostManagedControlRoot(options.managedRootId);
+ const result = await withRuntimeHostManagedServiceDeploymentLock(controlRoot, () =>
+ withRuntimeHostManagedServiceLifecycleLock(controlRoot, async () => {
+ await assertRuntimeHostManagedOperatorDeployment(
+ options.managedRootId,
+ options.operatorDeploymentId,
+ options.cliPath,
+ );
+ const resolved = await resolveRecoverableRuntimeHostManagedDeployment(
+ options.managedRootId,
+ {
+ convergeOperator: convergeRuntimeHostManagedOperator,
+ verifyOperator: verifyRuntimeHostManagedOperator,
+ resolveProvider: (requested) =>
+ resolveRuntimeHostLifecycleProvider(options.managedRootId, requested),
+ },
+ { expectedTarget: options.expectedTarget },
+ );
+ if (resolved.kind === 'absent') {
+ throw new RuntimeHostServiceManagerError(
+ 'not_installed',
+ 'The managed Runtime Host deployment is not installed',
+ );
+ }
+ assertRuntimeHostManagedOperatorConfig(
+ resolved.config,
+ options.operatorDeploymentId,
+ options.cliPath,
+ );
+ if (!resolved.config.listeners.directPeer?.enabled) {
+ throw new Error('Direct peer is not enabled for this Runtime Host');
+ }
+ const connection = await deps.connect(resolved.config.root.path);
+ try {
+ if (connection.rootId !== options.managedRootId) {
+ throw new Error('Runtime Host service is bound to a different State Root');
+ }
+ return await executePeerMeshAction(connection, options, invitation);
+ } finally {
+ await connection.close();
+ }
+ }),
+ );
+ writeResult(options, result, deps);
+ return 0;
+ } catch (error) {
+ writeError(options, error, deps);
+ return 1;
+ }
+}
+
+async function executePeerMeshAction(
+ connection: RuntimeHostConnection,
+ options: RuntimeHostPeerMeshManagementCliOptions,
+ invitation: ReturnType<typeof decodePeerMeshInvitation> | undefined,
+): Promise<PeerMeshResultFrame> {
+ const request = async <K extends PeerMeshOperation>(
+ operation: K,
+ input: OperationInput<K>,
+ ): Promise<OperationOutput<K>> => connection.request(operation, input);
+ switch (options.action) {
+ case 'status':
+ return { kind: 'result', action: 'status', result: await request('peer.mesh.query', {}) };
+ case 'create':
+ return { kind: 'result', action: 'create', result: await request('peer.mesh.create', {}) };
+ case 'invite':
+ return {
+ kind: 'result',
+ action: 'invite',
+ result: (
+ await request('peer.mesh.invite', {
+ meshId: requiredOption(options.meshId, 'Mesh ID'),
+ ...(options.ttlMs === undefined ? {} : { ttlMs: options.ttlMs }),
+ })
+ ).invitation,
+ };
+ case 'join':
+ return {
+ kind: 'result',
+ action: 'join',
+ result: await request('peer.mesh.join', {
+ invitation: requiredOption(invitation, 'Peer Mesh invitation'),
+ }),
+ };
+ case 'remove':
+ return {
+ kind: 'result',
+ action: 'remove',
+ result: await request('peer.mesh.remove', {
+ meshId: requiredOption(options.meshId, 'Mesh ID'),
+ peerId: requiredOption(options.peerId, 'Peer ID'),
+ }),
+ };
+ case 'leave':
+ return {
+ kind: 'result',
+ action: 'leave',
+ result: await request('peer.mesh.leave', {
+ meshId: requiredOption(options.meshId, 'Mesh ID'),
+ }),
+ };
+ case 'close':
+ return {
+ kind: 'result',
+ action: 'close',
+ result: await request('peer.mesh.close', {
+ meshId: requiredOption(options.meshId, 'Mesh ID'),
+ }),
+ };
+ case 'reconcile':
+ return {
+ kind: 'result',
+ action: 'reconcile',
+ result: await request('peer.mesh.reconcile', {}),
+ };
+ }
+}
+
+function requiredOption<T>(value: T | undefined, label: string): T {
+ if (value === undefined) throw new Error(`${label} is required`);
+ return value;
+}
+
+async function readJoinInvitation(
+ options: RuntimeHostPeerMeshManagementCliOptions,
+ deps: RuntimeHostPeerMeshManagementCliDeps,
+): Promise<ReturnType<typeof decodePeerMeshInvitation>> {
+ if (options.framed) {
+ deps.writeStdout(encodeRuntimeHostPeerMeshManagementFrame({ kind: 'input', action: 'join' }));
+ } else if (!options.json) {
+ deps.writeStderr('Paste the Peer Mesh invitation and press Enter:\n');
+ }
+ return decodePeerMeshInvitation(await deps.readInvitation());
+}
+
+type PeerMeshOperation = Extract<
+ Parameters<RuntimeHostConnection['request']>[0],
+ `peer.mesh.${string}`
+>;
+
+async function connectLocalOwner(rootPath: string): Promise<RuntimeHostConnection> {
+ const result = await connectExistingRuntimeHost({ rootPath, protocol: PROTOCOL });
+ if (result.kind !== 'connected') {
+ throw new Error(`Runtime Host service is not available (${result.kind})`);
+ }
+ return result.connection;
+}
+
+async function readInvitationFromStdin(): Promise<unknown> {
+ const stdin = process.stdin;
+ const canSetRawMode = stdin.isTTY && typeof stdin.setRawMode === 'function';
+ const wasRaw = stdin.isRaw;
+ if (canSetRawMode) stdin.setRawMode(true);
+ try {
+ let text = '';
+ for await (const chunk of stdin) {
+ text += Buffer.isBuffer(chunk) ? chunk.toString('utf8') : String(chunk);
+ if (text.includes('\u0003')) throw new Error('Peer Mesh invitation input was cancelled');
+ if (Buffer.byteLength(text, 'utf8') > INPUT_MAX_BYTES) {
+ throw new Error('Peer Mesh invitation exceeds the input size limit');
+ }
+ const carriageReturn = text.indexOf('\r');
+ const lineFeed = text.indexOf('\n');
+ const newline = [carriageReturn, lineFeed]
+ .filter((index) => index >= 0)
+ .sort((left, right) => left - right)[0];
+ if (newline !== undefined) {
+ if (
+ text
+ .slice(newline + 1)
+ .replace(/^\n/u, '')
+ .trim().length > 0
+ ) {
+ throw new Error('Peer Mesh invitation input contains trailing data');
+ }
+ text = text.slice(0, newline);
+ break;
+ }
+ }
+ if (!text.trim()) throw new Error('Peer Mesh invitation input is empty');
+ return JSON.parse(text.trim()) as unknown;
+ } finally {
+ if (canSetRawMode) stdin.setRawMode(wasRaw);
+ }
+}
+
+function writeResult(
+ options: RuntimeHostPeerMeshManagementCliOptions,
+ result: PeerMeshResultFrame,
+ deps: RuntimeHostPeerMeshManagementCliDeps,
+): void {
+ if (options.framed) {
+ deps.writeStdout(encodeRuntimeHostPeerMeshManagementFrame(result));
+ return;
+ }
+ deps.writeStdout(`${JSON.stringify(result.result, null, options.json ? undefined : 2)}\n`);
+}
+
+type PeerMeshResultFrame = Extract<RuntimeHostPeerMeshManagementFrame, { readonly kind: 'result' }>;
+
+function writeError(
+ options: RuntimeHostPeerMeshManagementCliOptions,
+ error: unknown,
+ deps: RuntimeHostPeerMeshManagementCliDeps,
+): void {
+ const message = error instanceof Error ? error.message : String(error);
+ if (options.framed) {
+ deps.writeStdout(
+ encodeRuntimeHostPeerMeshManagementFrame({
+ kind: 'error',
+ action: options.action,
+ error: { code: 'peer_mesh_management_failed', message },
+ }),
+ );
+ return;
+ }
+ if (options.json) {
+ deps.writeStdout(`${JSON.stringify({ ok: false, error: { message } })}\n`);
+ } else {
+ deps.writeStderr(`${message}\n`);
+ }
+}
diff --git a/packages/cli/src/runtime-host-service-command.ts b/packages/cli/src/runtime-host-service-command.ts
index 2fb88edee..a84e335b8 100644
--- a/packages/cli/src/runtime-host-service-command.ts
+++ b/packages/cli/src/runtime-host-service-command.ts
@@ -49,6 +49,7 @@ export interface RuntimeHostServiceCliOptions {
readonly expectedPeerId?: string;
readonly listenAddresses?: readonly string[];
readonly coordinationRelays?: readonly string[];
+ readonly meshDataRoot?: string;
};
}
diff --git a/packages/cli/src/runtime-host-service-management-command.ts b/packages/cli/src/runtime-host-service-management-command.ts
index 99dde97f0..808db6e59 100644
--- a/packages/cli/src/runtime-host-service-management-command.ts
+++ b/packages/cli/src/runtime-host-service-management-command.ts
@@ -25,6 +25,7 @@ import {
RUNTIME_HOST_OPERATOR_ACCESS_MANAGEMENT_CAPABILITY,
RUNTIME_HOST_OPERATOR_CAPABILITY_REQUEST_ENV,
RUNTIME_HOST_OPERATOR_PEER_MANAGEMENT_CAPABILITY,
+ RUNTIME_HOST_OPERATOR_PEER_MESH_MANAGEMENT_CAPABILITY,
RUNTIME_HOST_OPERATOR_PROJECT_DIRECTORY_CONFIGURATION_REQUEST_ENV,
RUNTIME_HOST_OPERATOR_PROCESS_LIFETIME_LOCK_CAPABILITY,
RUNTIME_HOST_SERVICE_ERROR_CODE_MAX_BYTES,
@@ -423,6 +424,7 @@ function requestedOperatorCapabilities(): {
if (
requested === RUNTIME_HOST_OPERATOR_ACCESS_MANAGEMENT_CAPABILITY ||
requested === RUNTIME_HOST_OPERATOR_PEER_MANAGEMENT_CAPABILITY ||
+ requested === RUNTIME_HOST_OPERATOR_PEER_MESH_MANAGEMENT_CAPABILITY ||
requested === RUNTIME_HOST_OPERATOR_PROCESS_LIFETIME_LOCK_CAPABILITY
) {
capabilities.push(requested);
diff --git a/packages/runtime-host/src/__tests__/connection-session.test.ts b/packages/runtime-host/src/__tests__/connection-session.test.ts
index 4f2c4c399..c749055c1 100644
--- a/packages/runtime-host/src/__tests__/connection-session.test.ts
+++ b/packages/runtime-host/src/__tests__/connection-session.test.ts
@@ -57,7 +57,7 @@ import type {
import { RuntimeHostConnectionSession } from '../server/connection-session.js';
import type { SessionContinuityService } from '../server/session-continuity-service.js';
import {
- createUnavailableAccessAuthorityOperationHandlers,
+ createUnavailableHostCoreOperationHandlers,
createUnavailableDomainOperationHandlers,
type OperationHandlerMap,
} from '../server/operation-dispatcher.js';
@@ -155,7 +155,7 @@ test('transcript pages are serialized per connection before their responses are
},
}),
...UNUSED_HOST_DIAGNOSTICS_HANDLER,
- ...createUnavailableAccessAuthorityOperationHandlers(),
+ ...createUnavailableHostCoreOperationHandlers(),
...createHandlers(async (input) => ({
ok: true,
result: runningSnapshot(input.sessionId, input.turnId),
@@ -493,7 +493,7 @@ test('flushes concurrent subscription opens before activating their live frame s
},
}),
...UNUSED_HOST_DIAGNOSTICS_HANDLER,
- ...createUnavailableAccessAuthorityOperationHandlers(),
+ ...createUnavailableHostCoreOperationHandlers(),
...createHandlers(async (input) => ({
ok: true,
result: runningSnapshot(input.sessionId, input.turnId),
@@ -679,7 +679,7 @@ test('connection reset while operation admission is pending does not execute the
},
}),
...UNUSED_HOST_DIAGNOSTICS_HANDLER,
- ...createUnavailableAccessAuthorityOperationHandlers(),
+ ...createUnavailableHostCoreOperationHandlers(),
...createHandlers(async (input) => {
handlerCalls += 1;
return {
@@ -768,7 +768,7 @@ test('a ready composition attaches the authenticated Client identity once', asyn
},
}),
...UNUSED_HOST_DIAGNOSTICS_HANDLER,
- ...createUnavailableAccessAuthorityOperationHandlers(),
+ ...createUnavailableHostCoreOperationHandlers(),
...createUnavailableDomainOperationHandlers(),
}),
resolveContinuity: () => undefined,
@@ -1066,7 +1066,7 @@ test('an in-flight status does not consume the final domain request slot', async
};
},
...UNUSED_HOST_DIAGNOSTICS_HANDLER,
- ...createUnavailableAccessAuthorityOperationHandlers(),
+ ...createUnavailableHostCoreOperationHandlers(),
...createHandlers(async (input) => {
const index = Number(input.turnId.slice('turn-'.length));
domainEntered[index]?.resolve();
@@ -1164,7 +1164,7 @@ test('evicting one slow subscription keeps sibling subscriptions and requests us
},
}),
...UNUSED_HOST_DIAGNOSTICS_HANDLER,
- ...createUnavailableAccessAuthorityOperationHandlers(),
+ ...createUnavailableHostCoreOperationHandlers(),
...createHandlers(async (input) => ({
ok: true,
result: runningSnapshot(input.sessionId, input.turnId),
@@ -1402,7 +1402,7 @@ async function openHalfClosedDispatchedSession(
},
}),
...UNUSED_HOST_DIAGNOSTICS_HANDLER,
- ...createUnavailableAccessAuthorityOperationHandlers(),
+ ...createUnavailableHostCoreOperationHandlers(),
...createHandlers(async (input) => {
handlerEntered.resolve();
await releaseHandler.promise;
diff --git a/packages/runtime-host/src/__tests__/operation-dispatcher.test.ts b/packages/runtime-host/src/__tests__/operation-dispatcher.test.ts
index a11d6758f..6271d9390 100644
--- a/packages/runtime-host/src/__tests__/operation-dispatcher.test.ts
+++ b/packages/runtime-host/src/__tests__/operation-dispatcher.test.ts
@@ -22,7 +22,7 @@ import { describe, test } from 'node:test';
import type { OperationKey, OperationOutcome, RequestFrame } from '../protocol/index.js';
import {
composeOperationHandlers,
- createUnavailableAccessAuthorityOperationHandlers,
+ createUnavailableHostCoreOperationHandlers,
createUnavailableDomainOperationHandlers,
dispatchOperation,
type ConnectionContext,
@@ -192,7 +192,7 @@ function validHandlers(): OperationHandlerMap {
'host.status': unavailable,
'host.diagnostics.query': unavailable,
'host.upgrade.prepare': unavailable,
- ...createUnavailableAccessAuthorityOperationHandlers(),
+ ...createUnavailableHostCoreOperationHandlers(),
...createUnavailableDomainOperationHandlers(),
};
}
diff --git a/packages/runtime-host/src/__tests__/peer-mesh.test.ts b/packages/runtime-host/src/__tests__/peer-mesh.test.ts
index 8ba334ed5..ace0e8bcc 100644
--- a/packages/runtime-host/src/__tests__/peer-mesh.test.ts
+++ b/packages/runtime-host/src/__tests__/peer-mesh.test.ts
@@ -62,6 +62,10 @@ test('authenticates three peers, consumes invitations once, and keeps authority
await authority.remove(mesh.roster.roster.meshId, 'peer-b');
assert.deepEqual(authority.status()[0]?.roster.roster.members, ['peer-a', 'peer-c']);
+ await memberC.leave(mesh.roster.roster.meshId);
+ assert.deepEqual(memberC.status(), []);
+ assert.deepEqual(authority.status()[0]?.roster.roster.members, ['peer-a']);
+
const closing = authority.close();
await assert.rejects(authority.invite(mesh.roster.roster.meshId), /closed/u);
await closing;
diff --git a/packages/runtime-host/src/operator/index.ts b/packages/runtime-host/src/operator/index.ts
index 7e5da3bc1..2517b5c28 100644
--- a/packages/runtime-host/src/operator/index.ts
+++ b/packages/runtime-host/src/operator/index.ts
@@ -38,6 +38,14 @@ export {
type RuntimeHostAccessManagementFrame,
} from './access-management-frame.js';
export { runtimeHostAccessCredentialFingerprint } from '../access-credential-identity.js';
+export {
+ RUNTIME_HOST_PEER_MESH_MANAGEMENT_FRAME_MAX_BYTES,
+ RUNTIME_HOST_PEER_MESH_MANAGEMENT_FRAME_PREFIX,
+ decodeRuntimeHostPeerMeshManagementFrame,
+ encodeRuntimeHostPeerMeshManagementFrame,
+ type RuntimeHostPeerMeshManagementAction,
+ type RuntimeHostPeerMeshManagementFrame,
+} from './peer-mesh-management-frame.js';
export { resolveRuntimeHostManagedServiceId } from './managed-service-target.js';
export {
RUNTIME_HOST_PEER_MANAGEMENT_FRAME_PREFIX,
@@ -51,6 +59,7 @@ export {
RUNTIME_HOST_OPERATOR_ACCESS_MANAGEMENT_CAPABILITY,
RUNTIME_HOST_OPERATOR_CAPABILITY_REQUEST_ENV,
RUNTIME_HOST_OPERATOR_PEER_MANAGEMENT_CAPABILITY,
+ RUNTIME_HOST_OPERATOR_PEER_MESH_MANAGEMENT_CAPABILITY,
RUNTIME_HOST_OPERATOR_PROJECT_DIRECTORY_CONFIGURATION_REQUEST_ENV,
RUNTIME_HOST_OPERATOR_PROCESS_LIFETIME_LOCK_CAPABILITY,
RUNTIME_HOST_OPERATOR_UPDATE_SCHEDULER_CAPABILITY,
diff --git a/packages/runtime-host/src/operator/peer-mesh-management-frame.ts b/packages/runtime-host/src/operator/peer-mesh-management-frame.ts
new file mode 100644
index 000000000..4b6e67de7
--- /dev/null
+++ b/packages/runtime-host/src/operator/peer-mesh-management-frame.ts
@@ -0,0 +1,150 @@
+/*
+ * Licensed to the Apache Software Foundation (ASF) under one
+ * or more contributor license agreements. See the NOTICE file
+ * distributed with this work for additional information
+ * regarding copyright ownership. The ASF licenses this file
+ * to you under the Apache License, Version 2.0 (the
+ * "License"); you may not use this file except in compliance
+ * with the License. You may obtain a copy of the License at
+ *
+ * http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing,
+ * software distributed under the License is distributed on an
+ * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+ * KIND, either express or implied. See the License for the
+ * specific language governing permissions and limitations
+ * under the License.
+ */
+
+import { z } from 'zod';
+import {
+ decodePeerMeshInvitation,
+ decodePeerMeshProjection,
+ decodePeerMeshQueryResult,
+ type PeerMeshInvitationV1,
+ type PeerMeshProjection,
+ type PeerMeshQueryResult,
+} from '../protocol/peer-mesh.js';
+
+export const RUNTIME_HOST_PEER_MESH_MANAGEMENT_FRAME_PREFIX =
+ 'MAKA_RUNTIME_HOST_PEER_MESH_MANAGEMENT_V1 ';
+export const RUNTIME_HOST_PEER_MESH_MANAGEMENT_FRAME_MAX_BYTES = 1024 * 1024;
+
+const ACTION_SCHEMA = z.enum([
+ 'status',
+ 'create',
+ 'invite',
+ 'join',
+ 'remove',
+ 'leave',
+ 'close',
+ 'reconcile',
+]);
+const FRAME_SCHEMA = z.union([
+ z.object({ kind: z.literal('input'), action: z.literal('join') }).strict(),
+ z.object({ kind: z.literal('result'), action: ACTION_SCHEMA, result: z.unknown() }).strict(),
+ z
+ .object({
+ kind: z.literal('error'),
+ action: ACTION_SCHEMA,
+ error: z
+ .object({
+ code: z.string().max(128),
+ message: z.string().max(2 * 1024),
+ })
+ .strict(),
+ })
+ .strict(),
+]);
+
+export type RuntimeHostPeerMeshManagementAction =
+ | 'status'
+ | 'create'
+ | 'invite'
+ | 'join'
+ | 'remove'
+ | 'leave'
+ | 'close'
+ | 'reconcile';
+export type RuntimeHostPeerMeshManagementFrame =
+ | { readonly kind: 'input'; readonly action: 'join' }
+ | {
+ readonly kind: 'result';
+ readonly action: 'status' | 'leave' | 'reconcile';
+ readonly result: PeerMeshQueryResult;
+ }
+ | {
+ readonly kind: 'result';
+ readonly action: 'create' | 'join' | 'remove' | 'close';
+ readonly result: PeerMeshProjection;
+ }
+ | {
+ readonly kind: 'result';
+ readonly action: 'invite';
+ readonly result: PeerMeshInvitationV1;
+ }
+ | {
+ readonly kind: 'error';
+ readonly action: RuntimeHostPeerMeshManagementAction;
+ readonly error: { readonly code: string; readonly message: string };
+ };
+
+export function encodeRuntimeHostPeerMeshManagementFrame(
+ frame: RuntimeHostPeerMeshManagementFrame,
+): string {
+ const encoded = Buffer.from(JSON.stringify(decodeFrame(frame)), 'utf8').toString('base64url');
+ if (Buffer.byteLength(encoded, 'utf8') > RUNTIME_HOST_PEER_MESH_MANAGEMENT_FRAME_MAX_BYTES) {
+ throw new RangeError('Runtime Host Peer Mesh management frame exceeds the size limit');
+ }
+ return `${RUNTIME_HOST_PEER_MESH_MANAGEMENT_FRAME_PREFIX}${encoded}\n`;
+}
+
+export function decodeRuntimeHostPeerMeshManagementFrame(
+ line: string,
+): RuntimeHostPeerMeshManagementFrame | undefined {
+ const marker = line.indexOf(RUNTIME_HOST_PEER_MESH_MANAGEMENT_FRAME_PREFIX);
+ if (marker < 0) return undefined;
+ try {
+ const encoded = line
+ .slice(marker + RUNTIME_HOST_PEER_MESH_MANAGEMENT_FRAME_PREFIX.length)
+ .trim();
+ if (
+ encoded.length === 0 ||
+ Buffer.byteLength(encoded, 'utf8') > RUNTIME_HOST_PEER_MESH_MANAGEMENT_FRAME_MAX_BYTES
+ ) {
+ return undefined;
+ }
+ return decodeFrame(JSON.parse(Buffer.from(encoded, 'base64url').toString('utf8')));
+ } catch {
+ return undefined;
+ }
+}
+
+function decodeFrame(value: unknown): RuntimeHostPeerMeshManagementFrame {
+ const frame = FRAME_SCHEMA.parse(value);
+ if (frame.kind !== 'result') return frame;
+
+ switch (frame.action) {
+ case 'status':
+ return { kind: 'result', action: 'status', result: decodePeerMeshQueryResult(frame.result) };
+ case 'leave':
+ return { kind: 'result', action: 'leave', result: decodePeerMeshQueryResult(frame.result) };
+ case 'reconcile':
+ return {
+ kind: 'result',
+ action: 'reconcile',
+ result: decodePeerMeshQueryResult(frame.result),
+ };
+ case 'invite':
+ return { kind: 'result', action: 'invite', result: decodePeerMeshInvitation(frame.result) };
+ case 'create':
+ return { kind: 'result', action: 'create', result: decodePeerMeshProjection(frame.result) };
+ case 'join':
+ return { kind: 'result', action: 'join', result: decodePeerMeshProjection(frame.result) };
+ case 'remove':
+ return { kind: 'result', action: 'remove', result: decodePeerMeshProjection(frame.result) };
+ case 'close':
+ return { kind: 'result', action: 'close', result: decodePeerMeshProjection(frame.result) };
+ }
+}
diff --git a/packages/runtime-host/src/operator/service-management-frame.ts b/packages/runtime-host/src/operator/service-management-frame.ts
index f8d431e11..27d143368 100644
--- a/packages/runtime-host/src/operator/service-management-frame.ts
+++ b/packages/runtime-host/src/operator/service-management-frame.ts
@@ -35,6 +35,7 @@ export const RUNTIME_HOST_OPERATOR_PROJECT_DIRECTORY_CONFIGURATION_REQUEST_ENV =
'MAKA_RUNTIME_HOST_OPERATOR_PROJECT_DIRECTORY_CONFIGURATION_REQUEST';
export const RUNTIME_HOST_OPERATOR_PROCESS_LIFETIME_LOCK_CAPABILITY = 'process-lifetime-lock-v1';
export const RUNTIME_HOST_OPERATOR_PEER_MANAGEMENT_CAPABILITY = 'peer-management-v1';
+export const RUNTIME_HOST_OPERATOR_PEER_MESH_MANAGEMENT_CAPABILITY = 'peer-mesh-management-v1';
export const RUNTIME_HOST_OPERATOR_UPDATE_SCHEDULER_CAPABILITY = 'update-scheduler-v1';
export const RUNTIME_HOST_OPERATOR_CAPABILITY_REQUEST_ENV =
'MAKA_RUNTIME_HOST_OPERATOR_CAPABILITY_REQUEST';
@@ -91,6 +92,7 @@ const SERVICE_STATES = ['not_installed', ...INSTALLED_SERVICE_STATES] as const;
const OPERATOR_CAPABILITIES = [
RUNTIME_HOST_OPERATOR_ACCESS_MANAGEMENT_CAPABILITY,
RUNTIME_HOST_OPERATOR_PEER_MANAGEMENT_CAPABILITY,
+ RUNTIME_HOST_OPERATOR_PEER_MESH_MANAGEMENT_CAPABILITY,
RUNTIME_HOST_OPERATOR_PROCESS_LIFETIME_LOCK_CAPABILITY,
RUNTIME_HOST_OPERATOR_UPDATE_SCHEDULER_CAPABILITY,
] as const;
diff --git a/packages/runtime-host/src/server/index.ts b/packages/runtime-host/src/peer-mesh/limits.ts
similarity index 56%
copy from packages/runtime-host/src/server/index.ts
copy to packages/runtime-host/src/peer-mesh/limits.ts
index 1621c78c6..a15f3bc75 100644
--- a/packages/runtime-host/src/server/index.ts
+++ b/packages/runtime-host/src/peer-mesh/limits.ts
@@ -17,16 +17,9 @@
* under the License.
*/
-export {
- RuntimeHostKernel,
- type RuntimeHostComposition,
-} from './host-kernel.js';
-export { defineInteractiveRuntimeHostComposition } from './host-composition.js';
-export { createUnavailableDomainOperationHandlers } from './operation-dispatcher.js';
-export { startExecutionRuntimeHostService } from './execution-service.js';
-export { runRuntimeHostProcessLifecycle } from './process-lifecycle.js';
-export { installRuntimeHostLogCapture } from '../process-diagnostics.js';
-export {
- readRuntimeHostAccessCredentialMetadata,
- type RuntimeHostAccessCredentialMetadata,
-} from './access-credential-metadata.js';
+export const PEER_MESH_MAX_MEMBERS = 64;
+export const PEER_MESH_MAX_MESHES = 16;
+export const PEER_MESH_MAX_PENDING_INVITATIONS = 32;
+export const PEER_MESH_MAX_INVITATION_RECORDS = PEER_MESH_MAX_PENDING_INVITATIONS * 3;
+export const PEER_MESH_MAX_ROUTE_HINTS = 16;
+export const PEER_MESH_ROUTE_RECORD_MAX_BYTES = 4 * 1024;
diff --git a/packages/runtime-host/src/peer-mesh/model.ts b/packages/runtime-host/src/peer-mesh/model.ts
index 1ffba804d..7e4013743 100644
--- a/packages/runtime-host/src/peer-mesh/model.ts
+++ b/packages/runtime-host/src/peer-mesh/model.ts
@@ -27,13 +27,20 @@ import {
timingSafeEqual,
verify,
} from 'node:crypto';
-
-export const PEER_MESH_MAX_MEMBERS = 64;
-export const PEER_MESH_MAX_MESHES = 16;
-export const PEER_MESH_MAX_PENDING_INVITATIONS = 32;
-export const PEER_MESH_MAX_INVITATION_RECORDS = PEER_MESH_MAX_PENDING_INVITATIONS * 3;
-export const PEER_MESH_MAX_ROUTE_HINTS = 16;
-export const PEER_MESH_ROUTE_RECORD_MAX_BYTES = 4 * 1024;
+import {
+ PEER_MESH_MAX_MEMBERS,
+ PEER_MESH_MAX_ROUTE_HINTS,
+ PEER_MESH_ROUTE_RECORD_MAX_BYTES,
+} from './limits.js';
+
+export {
+ PEER_MESH_MAX_INVITATION_RECORDS,
+ PEER_MESH_MAX_MEMBERS,
+ PEER_MESH_MAX_MESHES,
+ PEER_MESH_MAX_PENDING_INVITATIONS,
+ PEER_MESH_MAX_ROUTE_HINTS,
+ PEER_MESH_ROUTE_RECORD_MAX_BYTES,
+} from './limits.js';
export interface PeerMeshRosterV1 {
readonly version: 1;
@@ -60,6 +67,7 @@ export interface PeerMeshInvitationV1 extends PeerMeshAuthorityTarget {
readonly meshId: string;
readonly authorityPublicKey: string;
readonly secret: string;
+ readonly expiresAt: number;
}
export interface PeerMeshAuthorityKeyPair {
@@ -179,6 +187,7 @@ export function decodePeerMeshInvitation(value: unknown): PeerMeshInvitationV1 {
'meshId',
'authorityPublicKey',
'secret',
+ 'expiresAt',
'peerId',
'routeHints',
'coordinationRelays',
@@ -194,6 +203,7 @@ export function decodePeerMeshInvitation(value: unknown): PeerMeshInvitationV1 {
meshId,
authorityPublicKey,
secret: validateSecret(record.secret),
+ expiresAt: integer(record.expiresAt, 'expiresAt', 1),
...decodeAuthorityTarget({
peerId: record.peerId,
routeHints: record.routeHints,
diff --git a/packages/runtime-host/src/peer-mesh/node.ts b/packages/runtime-host/src/peer-mesh/node.ts
index 42f87ca0b..d522c278c 100644
--- a/packages/runtime-host/src/peer-mesh/node.ts
+++ b/packages/runtime-host/src/peer-mesh/node.ts
@@ -107,14 +107,25 @@ type SyncPeerMeshResponse =
}
| { readonly kind: 'sync-rejected'; readonly reason: 'unknown' };
-type PeerMeshControlRequest = RedeemInvitationRequest | SyncPeerMeshRequest;
+interface LeavePeerMeshRequest {
+ readonly kind: 'leave';
+ readonly meshId: string;
+}
+
+type LeavePeerMeshResponse =
+ | { readonly kind: 'left'; readonly roster: SignedPeerMeshRosterV1 }
+ | { readonly kind: 'leave-rejected'; readonly reason: 'unknown' };
+
+type PeerMeshControlRequest = RedeemInvitationRequest | SyncPeerMeshRequest | LeavePeerMeshRequest;
export interface PeerMeshNode {
+ localPeerId(): string;
status(): readonly PeerMeshStatus[];
create(): Promise<PeerMeshStatus>;
invite(meshId: string, input?: { readonly ttlMs?: number }): Promise<PeerMeshInvitationV1>;
join(invitation: PeerMeshInvitationV1, signal?: AbortSignal): Promise<PeerMeshStatus>;
remove(meshId: string, peerId: string): Promise<PeerMeshStatus>;
+ leave(meshId: string, signal?: AbortSignal): Promise<void>;
closeMesh(meshId: string): Promise<PeerMeshStatus>;
resolveRoutes(peerId: string):
| {
@@ -133,6 +144,13 @@ export interface PeerMeshStatus {
readonly authority: PeerMeshAuthorityTarget;
readonly roster: SignedPeerMeshRosterV1;
readonly pendingInvitationCount: number;
+ readonly memberRoutes: readonly PeerMeshMemberRouteStatus[];
+}
+
+export interface PeerMeshMemberRouteStatus {
+ readonly peerId: string;
+ readonly state: 'local' | 'route_available' | 'coordination_only' | 'stale' | 'unknown';
+ readonly expiresAt?: number;
}
export interface PeerMeshTransport {
@@ -200,6 +218,11 @@ class PeerMeshNodeImpl implements PeerMeshNode {
for (const route of this.#store.read().routes) this.#assertRouteSignature(route);
}
+ localPeerId(): string {
+ this.#assertOpen();
+ return this.#peer.identity().peerId;
+ }
+
status(): readonly PeerMeshStatus[] {
this.#assertOpen();
const identity = this.#peer.identity();
@@ -210,7 +233,7 @@ class PeerMeshNodeImpl implements PeerMeshNode {
(state) =>
state.role === 'authority' || state.roster.roster.members.includes(identity.peerId),
)
- .map((state) => peerMeshStatus(state, identity)),
+ .map((state) => peerMeshStatus(state, identity, this.#store.read().routes, this.#now())),
);
}
@@ -237,7 +260,10 @@ class PeerMeshNodeImpl implements PeerMeshNode {
invitations: [],
};
return {
- state: { ...current, meshes: appendMesh(current.meshes, state, identity.peerId) },
+ state: {
+ ...current,
+ meshes: appendMesh(current.meshes, state, identity.peerId),
+ },
result: state,
};
});
@@ -280,6 +306,7 @@ class PeerMeshNodeImpl implements PeerMeshNode {
meshId: state.roster.roster.meshId,
authorityPublicKey: state.roster.authorityPublicKey,
secret,
+ expiresAt,
...target,
};
return {
@@ -305,6 +332,9 @@ class PeerMeshNodeImpl implements PeerMeshNode {
join(invitationValue: PeerMeshInvitationV1, signal?: AbortSignal): Promise<PeerMeshStatus> {
return this.#admitMesh(async () => {
const invitation = decodePeerMeshInvitation(invitationValue);
+ if (invitation.expiresAt <= this.#now()) {
+ throw new Error('Peer Mesh invitation has expired');
+ }
const current = this.#store.read();
const existing = findMesh(current.meshes, invitation.meshId);
const localPeerId = this.#peer.identity().peerId;
@@ -405,6 +435,45 @@ class PeerMeshNodeImpl implements PeerMeshNode {
});
}
+ leave(meshId: string, signal?: AbortSignal): Promise<void> {
+ return this.#admitMesh(async () => {
+ const state = findMesh(this.#store.read().meshes, meshId);
+ const localPeerId = this.#peer.identity().peerId;
+ if (!state || !isActiveMembership(state, localPeerId)) {
+ throw new Error('This peer does not belong to that Peer Mesh');
+ }
+ if (state.role === 'authority') {
+ throw new Error('Close a Peer Mesh instead of leaving its authority');
+ }
+ const operationSignal = signal
+ ? AbortSignal.any([signal, this.#lifetime.signal])
+ : this.#lifetime.signal;
+ const stream = await this.#peer.connectMeshControl(
+ {
+ peerId: state.authority.peerId,
+ routeHints: state.authority.routeHints,
+ coordinationRelays: state.authority.coordinationRelays,
+ directDeadlineMs: CONNECT_DEADLINE_MS,
+ },
+ operationSignal,
+ );
+ try {
+ const response = await exchangeControl(
+ stream,
+ { kind: 'leave', meshId },
+ decodeLeaveResponse,
+ operationSignal,
+ );
+ if (response.kind === 'leave-rejected') {
+ throw new Error('Peer Mesh authority rejected the leave request');
+ }
+ await this.#applySync(meshId, response.roster, []);
+ } finally {
+ await stream.close().catch(() => undefined);
+ }
+ });
+ }
+
closeMesh(meshId: string): Promise<PeerMeshStatus> {
if (this.#lifetime.signal.aborted) return Promise.reject(new Error('Peer Mesh node is closed'));
return this.#updateAuthorityRoster(meshId, true, (state) => ({
@@ -735,7 +804,10 @@ class PeerMeshNodeImpl implements PeerMeshNode {
const state = requireAuthority(current.meshes, meshId);
if (state.roster.roster.closed) {
if (closedIsSuccess) {
- return { state: current, result: peerMeshStatus(state, this.#peer.identity()) };
+ return {
+ state: current,
+ result: peerMeshStatus(state, this.#peer.identity()),
+ };
}
throw new Error('Peer Mesh is closed');
}
@@ -803,7 +875,7 @@ class PeerMeshNodeImpl implements PeerMeshNode {
const deadline = setTimeout(() => stream.abort(), CONTROL_REQUEST_DEADLINE_MS);
try {
const request = decodeControlRequest(await readFrame(stream));
- let response: RedeemInvitationResponse | SyncPeerMeshResponse;
+ let response: RedeemInvitationResponse | SyncPeerMeshResponse | LeavePeerMeshResponse;
if (request.kind === 'redeem-invitation') {
await this.#refreshLocalRoute();
response = await this.#redeem(
@@ -811,8 +883,10 @@ class PeerMeshNodeImpl implements PeerMeshNode {
stream.peerId,
this.#validateRemoteRoute(request.route, stream.peerId),
);
- } else {
+ } else if (request.kind === 'sync') {
response = await this.#sync(request, stream.peerId);
+ } else {
+ response = await this.#leave(request.meshId, stream.peerId);
}
await writeFrame(stream, response);
await stream.close();
@@ -872,7 +946,10 @@ class PeerMeshNodeImpl implements PeerMeshNode {
return {
state: {
...current,
- meshes: replaceMesh(current.meshes, { ...state, invitations: remaining }),
+ meshes: replaceMesh(current.meshes, {
+ ...state,
+ invitations: remaining,
+ }),
},
result: rejected('expired'),
};
@@ -881,7 +958,10 @@ class PeerMeshNodeImpl implements PeerMeshNode {
return {
state: {
...current,
- meshes: replaceMesh(current.meshes, { ...state, invitations: remaining }),
+ meshes: replaceMesh(current.meshes, {
+ ...state,
+ invitations: remaining,
+ }),
},
result: rejected('closed'),
};
@@ -893,7 +973,10 @@ class PeerMeshNodeImpl implements PeerMeshNode {
return {
state: {
...current,
- meshes: replaceMesh(current.meshes, { ...state, invitations: remaining }),
+ meshes: replaceMesh(current.meshes, {
+ ...state,
+ invitations: remaining,
+ }),
},
result: rejected('full'),
};
@@ -959,6 +1042,48 @@ class PeerMeshNodeImpl implements PeerMeshNode {
});
}
+ #leave(meshId: string, remotePeerId: string): Promise<LeavePeerMeshResponse> {
+ return this.#store.mutate<LeavePeerMeshResponse>((current) => {
+ const state = findMesh(current.meshes, meshId);
+ if (
+ !state ||
+ state.role !== 'authority' ||
+ state.roster.roster.closed ||
+ (!state.roster.roster.members.includes(remotePeerId) &&
+ !state.invitations.some(
+ (invitation) => invitation.status === 'redeemed' && invitation.peerId === remotePeerId,
+ ))
+ ) {
+ return {
+ state: current,
+ result: { kind: 'leave-rejected', reason: 'unknown' },
+ };
+ }
+ if (!state.roster.roster.members.includes(remotePeerId)) {
+ return {
+ state: current,
+ result: { kind: 'left', roster: state.roster },
+ };
+ }
+ const roster = signPeerMeshRoster(
+ {
+ ...state.roster.roster,
+ revision: state.roster.roster.revision + 1,
+ members: state.roster.roster.members.filter((peerId) => peerId !== remotePeerId),
+ },
+ authorityKeys(state),
+ );
+ const updated = {
+ ...state,
+ roster,
+ };
+ return {
+ state: { ...current, meshes: replaceMesh(current.meshes, updated) },
+ result: { kind: 'left', roster },
+ };
+ });
+ }
+
async #sync(request: SyncPeerMeshRequest, remotePeerId: string): Promise<SyncPeerMeshResponse> {
const remoteRoute = this.#validateRemoteRoute(request.route, remotePeerId);
await this.#refreshLocalRoute();
@@ -966,7 +1091,10 @@ class PeerMeshNodeImpl implements PeerMeshNode {
return this.#store.mutate<SyncPeerMeshResponse>((current) => {
const state = findMesh(current.meshes, request.meshId);
if (!state || state.roster.authorityPublicKey !== incomingRoster.authorityPublicKey) {
- return { state: current, result: { kind: 'sync-rejected', reason: 'unknown' } as const };
+ return {
+ state: current,
+ result: { kind: 'sync-rejected', reason: 'unknown' } as const,
+ };
}
const roster = selectRoster(state.roster, incomingRoster);
const localPeerId = this.#peer.identity().peerId;
@@ -1008,6 +1136,8 @@ class PeerMeshNodeImpl implements PeerMeshNode {
function peerMeshStatus(
state: PeerMeshStateV1,
identity: ReturnType<PeerMeshTransport['identity']>,
+ routes: readonly SignedPeerMeshRouteRecordV1[] = [],
+ now = Date.now(),
): PeerMeshStatus {
return Object.freeze({
role: state.role === 'authority' ? 'authority' : 'member',
@@ -1016,8 +1146,28 @@ function peerMeshStatus(
roster: state.roster,
pendingInvitationCount:
state.role === 'authority'
- ? state.invitations.filter(({ status }) => status === 'pending').length
+ ? state.invitations.filter(
+ (invitation) => invitation.status === 'pending' && invitation.expiresAt > now,
+ ).length
: 0,
+ memberRoutes: Object.freeze(
+ state.roster.roster.members.map((peerId) => {
+ if (peerId === identity.peerId) return Object.freeze({ peerId, state: 'local' as const });
+ const route = routes.find((candidate) => candidate.route.peerId === peerId)?.route;
+ if (!route) return Object.freeze({ peerId, state: 'unknown' as const });
+ if (route.expiresAt <= now) {
+ return Object.freeze({ peerId, state: 'stale' as const, expiresAt: route.expiresAt });
+ }
+ return Object.freeze({
+ peerId,
+ state:
+ route.routeHints.length > 0
+ ? ('route_available' as const)
+ : ('coordination_only' as const),
+ expiresAt: route.expiresAt,
+ });
+ }),
+ ),
});
}
@@ -1176,7 +1326,10 @@ function responseRoutes(
routes: readonly SignedPeerMeshRouteRecordV1[],
knownRoutes: readonly PeerMeshRouteSequence[],
now: number,
-): { readonly routes: readonly SignedPeerMeshRouteRecordV1[]; readonly more: boolean } {
+): {
+ readonly routes: readonly SignedPeerMeshRouteRecordV1[];
+ readonly more: boolean;
+} {
const known = new Map(knownRoutes.map(({ peerId, sequence }) => [peerId, sequence]));
const missing = routes.filter(
({ route }) =>
@@ -1257,6 +1410,9 @@ function decodeControlRequest(value: unknown): PeerMeshControlRequest {
knownRoutes: decodeRouteSequences(record.knownRoutes),
};
}
+ if (record.kind === 'leave' && hasExactKeys(record, ['kind', 'meshId'])) {
+ return { kind: 'leave', meshId: requiredString(record.meshId, 128) };
+ }
throw new Error('Unsupported Peer Mesh control request');
}
@@ -1306,6 +1462,21 @@ function decodeSyncResponse(value: unknown): SyncPeerMeshResponse {
throw new Error('Invalid Peer Mesh synchronization response');
}
+function decodeLeaveResponse(value: unknown): LeavePeerMeshResponse {
+ const record = recordValue(value);
+ if (record.kind === 'left' && hasExactKeys(record, ['kind', 'roster'])) {
+ return { kind: 'left', roster: decodeSignedPeerMeshRoster(record.roster) };
+ }
+ if (
+ record.kind === 'leave-rejected' &&
+ hasExactKeys(record, ['kind', 'reason']) &&
+ record.reason === 'unknown'
+ ) {
+ return { kind: 'leave-rejected', reason: 'unknown' };
+ }
+ throw new Error('Invalid Peer Mesh leave response');
+}
+
function decodeRoutePage(value: unknown): readonly SignedPeerMeshRouteRecordV1[] {
if (!Array.isArray(value) || value.length > ROUTE_PAGE_SIZE) {
throw new Error('Invalid Peer Mesh route page');
diff --git a/packages/runtime-host/src/peer-mesh/owner.ts b/packages/runtime-host/src/peer-mesh/owner.ts
index dc6df4949..985472ef2 100644
--- a/packages/runtime-host/src/peer-mesh/owner.ts
+++ b/packages/runtime-host/src/peer-mesh/owner.ts
@@ -18,12 +18,12 @@
*/
import { createRuntimeHostPeerClient, type RuntimeHostPeerClient } from '../client/peer-client.js';
+import { join } from 'node:path';
import { openPeerMeshNode, type PeerMeshNode } from './node.js';
export interface RuntimeHostPeerMeshOwner {
readonly client: RuntimeHostPeerClient;
readonly mesh: PeerMeshNode;
- readonly closed: Promise<void>;
close(): Promise<void>;
}
@@ -45,7 +45,10 @@ export async function openRuntimeHostPeerMeshOwner(input: {
routeResolver: { resolveRoutes: (peerId) => mesh?.resolveRoutes(peerId) },
});
try {
- mesh = await openPeerMeshNode({ dataRoot: input.dataRoot, peer: client });
+ mesh = await openPeerMeshNode({
+ dataRoot: join(input.dataRoot, client.identity().peerId),
+ peer: client,
+ });
} catch (error) {
await client.close().catch(() => undefined);
throw error;
@@ -56,12 +59,10 @@ export async function openRuntimeHostPeerMeshOwner(input: {
closeTask ??= closeOwner(mesh!, client, serving);
return closeTask;
};
- const closed = serving.then(close, close);
- void closed.catch(() => undefined);
+ void serving.then(close, close).catch(() => undefined);
return Object.freeze({
client,
mesh,
- closed,
close,
});
}
diff --git a/packages/runtime-host/src/peer-mesh/store.ts b/packages/runtime-host/src/peer-mesh/store.ts
index 3a7594a77..60bbd0319 100644
--- a/packages/runtime-host/src/peer-mesh/store.ts
+++ b/packages/runtime-host/src/peer-mesh/store.ts
@@ -149,8 +149,9 @@ class PeerMeshStateStoreImpl implements PeerMeshStateStore {
if (error instanceof PeerMeshPostCommitError) {
this.#state = canonical;
this.#failure = error;
+ throw error;
}
- throw error;
+ throw new PeerMeshPersistenceError(error);
}
return updated.result;
});
@@ -320,7 +321,10 @@ async function readState(
);
} catch (error) {
if (isNodeError(error, 'ENOENT')) {
- return Object.freeze({ meshes: Object.freeze([]), routes: Object.freeze([]) });
+ return Object.freeze({
+ meshes: Object.freeze([]),
+ routes: Object.freeze([]),
+ });
}
throw error;
}
@@ -360,7 +364,13 @@ async function writeState(
}
}
-class PeerMeshPostCommitError extends Error {
+export class PeerMeshPersistenceError extends Error {
+ constructor(cause: unknown) {
+ super('Peer Mesh state could not be persisted', { cause });
+ }
+}
+
+export class PeerMeshPostCommitError extends Error {
constructor(cause: unknown) {
super('Peer Mesh state was replaced but its durability could not be confirmed; reopen it', {
cause,
@@ -387,7 +397,11 @@ function decodeInvitations(value: unknown): PeerMeshInvitationRecord[] {
if (!Number.isSafeInteger(expiresAt) || (expiresAt as number) < 1) {
throw new Error('Invalid Peer Mesh invitation expiry');
}
- return Object.freeze({ status: 'pending' as const, ...base, expiresAt: expiresAt as number });
+ return Object.freeze({
+ status: 'pending' as const,
+ ...base,
+ expiresAt: expiresAt as number,
+ });
}
if (
record.status === 'redeemed' &&
diff --git a/packages/runtime-host/src/protocol/index.ts b/packages/runtime-host/src/protocol/index.ts
index 999988634..1d7de7f3e 100644
--- a/packages/runtime-host/src/protocol/index.ts
+++ b/packages/runtime-host/src/protocol/index.ts
@@ -71,6 +71,7 @@ export * from './configuration-change.js';
export * from './goal.js';
export * from './hosted-execution.js';
export * from './plan.js';
+export * from './peer-mesh.js';
export * from './project-catalog.js';
export * from './project-catalog-change.js';
export * from './execution-inspect.js';
@@ -93,7 +94,9 @@ export const RUNTIME_HOST_REGISTRATION_SCHEMA_VERSION = 1 as const;
export const RUNTIME_HOST_PROTOCOL_VERSION = 0 as const;
// Increment when the same protocol version no longer guarantees safe Client-Host
// interoperability. Mismatches are rejected before domain commands are admitted.
-export const RUNTIME_HOST_COMPATIBILITY_EPOCH = 60 as const;
+export const RUNTIME_HOST_COMPATIBILITY_EPOCH = 61 as const;
+// 61: A Direct peer listener can expose owner-only Peer Mesh management
+// operations. Older peers do not have this closed operation vocabulary.
// 60: WorkHub stores a canonical delegation assignment record. Older peers
// cannot decode this message during transcript recovery.
// 59: Scheduled Turn provider-retry frames may carry an optional host-clock
@@ -409,7 +412,9 @@ export function decodeHostRegistration(value: unknown): HostRegistration {
compositionRevision: decodeCompositionRevision(registration.compositionRevision),
...(registration.lifecycleMode === undefined
? {}
- : { lifecycleMode: requireHostLifecycleMode(registration.lifecycleMode) }),
+ : {
+ lifecycleMode: requireHostLifecycleMode(registration.lifecycleMode),
+ }),
...(registration.generation === undefined
? {}
: { generation: requireHostGeneration(registration.generation) }),
@@ -460,7 +465,9 @@ function requireHostLifecycleMode(value: unknown): 'ephemeral' | 'service' {
function decodeTakeover(value: unknown): ClientHello['takeover'] {
if (value === undefined) return undefined;
const takeover = requireRecord(value, 'Runtime Host takeover');
- return { expectedHostEpoch: requireId(takeover.expectedHostEpoch, 'expectedHostEpoch') };
+ return {
+ expectedHostEpoch: requireId(takeover.expectedHostEpoch, 'expectedHostEpoch'),
+ };
}
export function encodeProtocolMessage(value: ClientFrame | HostFrame): EncodedProtocolMessage {
diff --git a/packages/runtime-host/src/protocol/operations.ts b/packages/runtime-host/src/protocol/operations.ts
index 84595571b..638f4aa4d 100644
--- a/packages/runtime-host/src/protocol/operations.ts
+++ b/packages/runtime-host/src/protocol/operations.ts
@@ -39,6 +39,7 @@ import { MEMORY_OPERATION_SPECS } from './memory.js';
import { NETWORK_PROXY_OPERATION_SPECS } from './network-proxy.js';
import { OAUTH_OPERATION_SPECS } from './oauth.js';
import { PLAN_OPERATION_SPECS } from './plan.js';
+import { PEER_MESH_OPERATION_SPECS } from './peer-mesh.js';
import { PROJECT_CATALOG_OPERATION_SPECS } from './project-catalog.js';
import {
composeOperationSpecMaps,
@@ -177,6 +178,7 @@ export * from './workspace.js';
export const HOST_OPERATION_SPECS = composeOperationSpecMaps(
HOST_BOOTSTRAP_OPERATION_SPECS,
+ PEER_MESH_OPERATION_SPECS,
HOSTED_EXECUTION_OPERATION_SPECS,
ACCESS_AUTHORITY_OPERATION_SPECS,
AGENT_GRAPH_OPERATION_SPECS,
diff --git a/packages/runtime-host/src/protocol/peer-mesh.ts b/packages/runtime-host/src/protocol/peer-mesh.ts
new file mode 100644
index 000000000..de995ab82
--- /dev/null
+++ b/packages/runtime-host/src/protocol/peer-mesh.ts
@@ -0,0 +1,364 @@
+/*
+ * Licensed to the Apache Software Foundation (ASF) under one
+ * or more contributor license agreements. See the NOTICE file
+ * distributed with this work for additional information
+ * regarding copyright ownership. The ASF licenses this file
+ * to you under the Apache License, Version 2.0 (the
+ * "License"); you may not use this file except in compliance
+ * with the License. You may obtain a copy of the License at
+ *
+ * http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing,
+ * software distributed under the License is distributed on an
+ * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+ * KIND, either express or implied. See the License for the
+ * specific language governing permissions and limitations
+ * under the License.
+ */
+
+import {
+ assertExactKeys,
+ requireCount,
+ requireExactRecord,
+ requireRecord,
+ requireString,
+} from './codec.js';
+import { defineOperation } from './operation-spec.js';
+import {
+ PEER_MESH_MAX_MEMBERS,
+ PEER_MESH_MAX_MESHES,
+ PEER_MESH_MAX_ROUTE_HINTS,
+} from '../peer-mesh/limits.js';
+
+const PEER_ID_MAX_BYTES = 256;
+const MESH_ID_MAX_BYTES = 128;
+const MESH_ADDRESS_MAX_LENGTH = 1024;
+
+export interface PeerMeshInvitationV1 {
+ readonly version: 1;
+ readonly meshId: string;
+ readonly authorityPublicKey: string;
+ readonly secret: string;
+ readonly expiresAt: number;
+ readonly peerId: string;
+ readonly routeHints: readonly string[];
+ readonly coordinationRelays: readonly string[];
+}
+
+export interface PeerMeshProjection {
+ readonly meshId: string;
+ readonly role: 'authority' | 'member';
+ readonly localPeerId: string;
+ readonly authorityPeerId: string;
+ readonly revision: number;
+ readonly closed: boolean;
+ readonly members: readonly string[];
+ readonly memberRoutes: readonly PeerMeshMemberRouteProjection[];
+ readonly pendingInvitationCount: number;
+}
+
+export interface PeerMeshMemberRouteProjection {
+ readonly peerId: string;
+ readonly state: 'local' | 'route_available' | 'coordination_only' | 'stale' | 'unknown';
+ readonly expiresAt?: number;
+}
+
+export interface PeerMeshQueryResult {
+ readonly available: boolean;
+ readonly localPeerId?: string;
+ readonly meshes: readonly PeerMeshProjection[];
+}
+
+export interface PeerMeshTargetInput {
+ readonly meshId: string;
+}
+
+export interface PeerMeshInviteInput extends PeerMeshTargetInput {
+ readonly ttlMs?: number;
+}
+
+export interface PeerMeshJoinInput {
+ readonly invitation: PeerMeshInvitationV1;
+}
+
+export interface PeerMeshRemoveInput extends PeerMeshTargetInput {
+ readonly peerId: string;
+}
+
+export interface PeerMeshInvitationResult {
+ readonly invitation: PeerMeshInvitationV1;
+}
+
+const MUTATION_ERRORS = [
+ 'invalid_request',
+ 'operation_unavailable',
+ 'persistence_failed',
+ 'commit_outcome_unknown',
+ 'internal_failure',
+] as const;
+
+export const PEER_MESH_OPERATION_SPECS = {
+ 'peer.mesh.query': defineOperation({
+ mode: 'query',
+ availability: 'ready',
+ errors: ['operation_unavailable', 'internal_failure'] as const,
+ decodeInput: decodeEmptyInput,
+ decodeOutput: decodePeerMeshQueryResult,
+ }),
+ 'peer.mesh.create': defineOperation({
+ mode: 'command',
+ availability: 'ready',
+ errors: MUTATION_ERRORS,
+ decodeInput: decodeEmptyInput,
+ decodeOutput: decodePeerMeshProjection,
+ }),
+ 'peer.mesh.invite': defineOperation({
+ mode: 'command',
+ availability: 'ready',
+ errors: MUTATION_ERRORS,
+ decodeInput: decodePeerMeshInviteInput,
+ decodeOutput: decodePeerMeshInvitationResult,
+ }),
+ 'peer.mesh.join': defineOperation({
+ mode: 'command',
+ availability: 'ready',
+ errors: MUTATION_ERRORS,
+ decodeInput: decodePeerMeshJoinInput,
+ decodeOutput: decodePeerMeshProjection,
+ }),
+ 'peer.mesh.remove': defineOperation({
+ mode: 'command',
+ availability: 'ready',
+ errors: MUTATION_ERRORS,
+ decodeInput: decodePeerMeshRemoveInput,
+ decodeOutput: decodePeerMeshProjection,
+ }),
+ 'peer.mesh.leave': defineOperation({
+ mode: 'command',
+ availability: 'ready',
+ errors: MUTATION_ERRORS,
+ decodeInput: decodePeerMeshTargetInput,
+ decodeOutput: decodePeerMeshQueryResult,
+ }),
+ 'peer.mesh.close': defineOperation({
+ mode: 'command',
+ availability: 'ready',
+ errors: MUTATION_ERRORS,
+ decodeInput: decodePeerMeshTargetInput,
+ decodeOutput: decodePeerMeshProjection,
+ }),
+ 'peer.mesh.reconcile': defineOperation({
+ mode: 'command',
+ availability: 'ready',
+ errors: ['operation_unavailable', 'internal_failure'] as const,
+ decodeInput: decodeEmptyInput,
+ decodeOutput: decodePeerMeshQueryResult,
+ }),
+} as const;
+
+function decodeEmptyInput(value: unknown): Record<string, never> {
+ requireExactRecord(value, 'Peer Mesh operation input', []);
+ return {};
+}
+
+function decodePeerMeshTargetInput(value: unknown): PeerMeshTargetInput {
+ const record = requireExactRecord(value, 'Peer Mesh target input', ['meshId']);
+ return {
+ meshId: requireString(record.meshId, 'Peer Mesh meshId', MESH_ID_MAX_BYTES),
+ };
+}
+
+function decodePeerMeshInviteInput(value: unknown): PeerMeshInviteInput {
+ const record = requireRecord(value, 'Peer Mesh invitation input');
+ assertExactKeys(
+ record,
+ 'Peer Mesh invitation input',
+ record.ttlMs === undefined ? ['meshId'] : ['meshId', 'ttlMs'],
+ );
+ const ttlMs = record.ttlMs;
+ return {
+ meshId: requireString(record.meshId, 'Peer Mesh meshId', MESH_ID_MAX_BYTES),
+ ...(ttlMs === undefined ? {} : { ttlMs: requireCount(ttlMs, 'Peer Mesh invitation ttlMs') }),
+ };
+}
+
+function decodePeerMeshJoinInput(value: unknown): PeerMeshJoinInput {
+ const record = requireExactRecord(value, 'Peer Mesh join input', ['invitation']);
+ return { invitation: decodePeerMeshInvitation(record.invitation) };
+}
+
+export function decodePeerMeshInvitation(value: unknown): PeerMeshInvitationV1 {
+ const record = requireExactRecord(value, 'Peer Mesh invitation', [
+ 'version',
+ 'meshId',
+ 'authorityPublicKey',
+ 'secret',
+ 'expiresAt',
+ 'peerId',
+ 'routeHints',
+ 'coordinationRelays',
+ ]);
+ if (record.version !== 1) throw new Error('Unsupported Peer Mesh invitation version');
+ return {
+ version: 1,
+ meshId: requireString(record.meshId, 'Peer Mesh meshId', MESH_ID_MAX_BYTES),
+ authorityPublicKey: requireString(
+ record.authorityPublicKey,
+ 'Peer Mesh authority public key',
+ PEER_ID_MAX_BYTES,
+ ),
+ secret: requireString(record.secret, 'Peer Mesh invitation secret', 64),
+ expiresAt: requireCount(record.expiresAt, 'Peer Mesh invitation expiry'),
+ peerId: requireMeshToken(record.peerId, 'Peer Mesh authority peerId'),
+ routeHints: requireMeshAddresses(record.routeHints, 'Peer Mesh route hints'),
+ coordinationRelays: requireMeshAddresses(
+ record.coordinationRelays,
+ 'Peer Mesh coordination relays',
+ ),
+ };
+}
+
+function requireMeshToken(value: unknown, label: string): string {
+ const result = requireString(value, label, PEER_ID_MAX_BYTES);
+ if (/\s|[\u0000-\u001f\u007f]/u.test(result)) throw new Error(`Invalid ${label}`);
+ return result;
+}
+
+function requireMeshAddresses(value: unknown, label: string): readonly string[] {
+ if (!Array.isArray(value) || value.length > PEER_MESH_MAX_ROUTE_HINTS) {
+ throw new Error(`Invalid ${label}`);
+ }
+ const addresses = value.map((address) => requireString(address, label, MESH_ADDRESS_MAX_LENGTH));
+ if (
+ addresses.some(
+ (address) => !address.startsWith('/') || /\s|[\u0000-\u001f\u007f]/u.test(address),
+ ) ||
+ new Set(addresses).size !== addresses.length
+ ) {
+ throw new Error(`Invalid ${label}`);
+ }
+ return Object.freeze(addresses);
+}
+
+function decodePeerMeshRemoveInput(value: unknown): PeerMeshRemoveInput {
+ const record = requireExactRecord(value, 'Peer Mesh remove input', ['meshId', 'peerId']);
+ return {
+ meshId: requireString(record.meshId, 'Peer Mesh meshId', MESH_ID_MAX_BYTES),
+ peerId: requireString(record.peerId, 'Peer Mesh peerId', PEER_ID_MAX_BYTES),
+ };
+}
+
+export function decodePeerMeshQueryResult(value: unknown): PeerMeshQueryResult {
+ const record = requireRecord(value, 'Peer Mesh query result');
+ assertExactKeys(
+ record,
+ 'Peer Mesh query result',
+ record.localPeerId === undefined
+ ? ['available', 'meshes']
+ : ['available', 'localPeerId', 'meshes'],
+ );
+ if (
+ typeof record.available !== 'boolean' ||
+ !Array.isArray(record.meshes) ||
+ record.meshes.length > PEER_MESH_MAX_MESHES
+ ) {
+ throw new Error('Invalid Peer Mesh query result');
+ }
+ const localPeerId = record.localPeerId;
+ if (record.available !== (localPeerId !== undefined)) {
+ throw new Error('Invalid Peer Mesh availability result');
+ }
+ return {
+ available: record.available,
+ ...(localPeerId === undefined
+ ? {}
+ : {
+ localPeerId: requireString(localPeerId, 'Peer Mesh localPeerId', PEER_ID_MAX_BYTES),
+ }),
+ meshes: Object.freeze(record.meshes.map(decodePeerMeshProjection)),
+ };
+}
+
+export function decodePeerMeshProjection(value: unknown): PeerMeshProjection {
+ const record = requireExactRecord(value, 'Peer Mesh projection', [
+ 'meshId',
+ 'role',
+ 'localPeerId',
+ 'authorityPeerId',
+ 'revision',
+ 'closed',
+ 'members',
+ 'memberRoutes',
+ 'pendingInvitationCount',
+ ]);
+ if (
+ (record.role !== 'authority' && record.role !== 'member') ||
+ typeof record.closed !== 'boolean' ||
+ !Array.isArray(record.members) ||
+ record.members.length > PEER_MESH_MAX_MEMBERS ||
+ !Array.isArray(record.memberRoutes) ||
+ record.memberRoutes.length > PEER_MESH_MAX_MEMBERS
+ ) {
+ throw new Error('Invalid Peer Mesh projection');
+ }
+ const members = record.members.map((member) =>
+ requireString(member, 'Peer Mesh member peerId', PEER_ID_MAX_BYTES),
+ );
+ if (new Set(members).size !== members.length) throw new Error('Duplicate Peer Mesh member');
+ const memberRoutes = record.memberRoutes.map(decodePeerMeshMemberRouteProjection);
+ if (
+ memberRoutes.length !== members.length ||
+ memberRoutes.some((route, index) => route.peerId !== members[index])
+ ) {
+ throw new Error('Peer Mesh member routes do not match the roster');
+ }
+ return {
+ meshId: requireString(record.meshId, 'Peer Mesh meshId', MESH_ID_MAX_BYTES),
+ role: record.role,
+ localPeerId: requireString(record.localPeerId, 'Peer Mesh localPeerId', PEER_ID_MAX_BYTES),
+ authorityPeerId: requireString(
+ record.authorityPeerId,
+ 'Peer Mesh authorityPeerId',
+ PEER_ID_MAX_BYTES,
+ ),
+ revision: requireCount(record.revision, 'Peer Mesh revision'),
+ closed: record.closed,
+ members: Object.freeze(members),
+ memberRoutes: Object.freeze(memberRoutes),
+ pendingInvitationCount: requireCount(
+ record.pendingInvitationCount,
+ 'Peer Mesh pendingInvitationCount',
+ ),
+ };
+}
+
+function decodePeerMeshMemberRouteProjection(value: unknown): PeerMeshMemberRouteProjection {
+ const record = requireRecord(value, 'Peer Mesh member route');
+ assertExactKeys(
+ record,
+ 'Peer Mesh member route',
+ record.expiresAt === undefined ? ['peerId', 'state'] : ['peerId', 'state', 'expiresAt'],
+ );
+ if (
+ record.state !== 'local' &&
+ record.state !== 'route_available' &&
+ record.state !== 'coordination_only' &&
+ record.state !== 'stale' &&
+ record.state !== 'unknown'
+ ) {
+ throw new Error('Invalid Peer Mesh member route state');
+ }
+ return {
+ peerId: requireString(record.peerId, 'Peer Mesh member route peerId', PEER_ID_MAX_BYTES),
+ state: record.state,
+ ...(record.expiresAt === undefined
+ ? {}
+ : { expiresAt: requireCount(record.expiresAt, 'Peer Mesh member route expiry') }),
+ };
+}
+
+function decodePeerMeshInvitationResult(value: unknown): PeerMeshInvitationResult {
+ const record = requireExactRecord(value, 'Peer Mesh invitation result', ['invitation']);
+ return { invitation: decodePeerMeshInvitation(record.invitation) };
+}
diff --git a/packages/runtime-host/src/server/execution-service.ts b/packages/runtime-host/src/server/execution-service.ts
index 9a15c41ee..2dc7d6cca 100644
--- a/packages/runtime-host/src/server/execution-service.ts
+++ b/packages/runtime-host/src/server/execution-service.ts
@@ -31,10 +31,14 @@ import {
} from '../operator/managed-deployment.js';
import { RuntimeHostKernel } from './host-kernel.js';
import { openRuntimeHostAccessAuthority } from './access-authority.js';
-import { startRuntimeHostAuthenticatedListenerSet } from './listener-set.js';
+import {
+ startRuntimeHostAuthenticatedListenerSet,
+ type RuntimeHostListenerSet,
+} from './listener-set.js';
import type { StartRuntimeHostWebSocketListenerOptions } from './websocket-listener.js';
import type { PublishedProjectDirectoryRoot } from './project-directory-authority.js';
-import type { RuntimeHostPeerListenerEndpointOptions } from './peer-listener.js';
+import type { RuntimeHostPeerListenerConfiguration } from './peer-listener.js';
+import { openRuntimeHostPeerMeshOwner, type RuntimeHostPeerMeshOwner } from '../peer-mesh/owner.js';
export interface ExecutionRuntimeHostServiceOptions {
readonly rootPath: string;
@@ -46,7 +50,7 @@ export interface ExecutionRuntimeHostServiceOptions {
StartRuntimeHostWebSocketListenerOptions,
'accessAuthority' | 'accept' | 'isReady'
>;
- readonly peer?: RuntimeHostPeerListenerEndpointOptions;
+ readonly peer?: RuntimeHostPeerListenerConfiguration & { readonly meshDataRoot?: string };
}
export interface ExecutionRuntimeHostServiceDependencies
@@ -71,7 +75,10 @@ export async function startExecutionRuntimeHostService(
dependencies: ExecutionRuntimeHostServiceDependencies = {},
): Promise<RuntimeHostKernel> {
const composition = await createExecutionRuntimeHostCompositionSource(options, dependencies);
- const capability = await resolveStorageRoot({ path: options.rootPath, kind: 'interactive' });
+ const capability = await resolveStorageRoot({
+ path: options.rootPath,
+ kind: 'interactive',
+ });
const ownership = await tryAcquireRuntimeHostLaunch(
capability,
{
@@ -83,7 +90,14 @@ export async function startExecutionRuntimeHostService(
);
if (!ownership) throw new RuntimeHostRootAlreadyOwnedError(capability.canonicalPath);
const { owner } = ownership;
+ let peerOwner: RuntimeHostPeerMeshOwner | undefined;
try {
+ peerOwner = options.peer?.meshDataRoot
+ ? await openRuntimeHostPeerMeshOwner({
+ ...options.peer,
+ dataRoot: options.peer.meshDataRoot,
+ })
+ : undefined;
const accessAuthority = await openRuntimeHostAccessAuthority(owner.controlDirectory);
return await RuntimeHostKernel.start({
owner,
@@ -92,6 +106,7 @@ export async function startExecutionRuntimeHostService(
shutdownGraceMs: options.shutdownGraceMs,
composition,
accessAuthority,
+ ...(peerOwner ? { peerMesh: peerOwner.mesh } : {}),
...(options.websocket || options.peer
? {
listenerSetFactory: (input) =>
@@ -99,13 +114,40 @@ export async function startExecutionRuntimeHostService(
...(options.websocket
? { websocket: { ...options.websocket, accessAuthority } }
: {}),
- ...(options.peer ? { peer: { ...options.peer, accessAuthority } } : {}),
- }),
+ ...(options.peer
+ ? {
+ peer: peerOwner
+ ? { client: peerOwner.client, accessAuthority }
+ : { ...options.peer, accessAuthority },
+ }
+ : {}),
+ }).then((listeners) =>
+ peerOwner ? attachPeerOwnerCleanup(listeners, peerOwner) : listeners,
+ ),
}
: {}),
});
} catch (error) {
+ await peerOwner?.close().catch(() => undefined);
if (!owner.closed) await owner.close();
throw error;
}
}
+
+function attachPeerOwnerCleanup(
+ listeners: RuntimeHostListenerSet,
+ owner: RuntimeHostPeerMeshOwner,
+): RuntimeHostListenerSet {
+ return {
+ ...listeners,
+ cleanup: async () => {
+ const errors: unknown[] = [];
+ await listeners.cleanup().catch((error: unknown) => errors.push(error));
+ await owner.close().catch((error: unknown) => errors.push(error));
+ if (errors.length === 1) throw errors[0];
+ if (errors.length > 1) {
+ throw new AggregateError(errors, 'Unable to close Runtime Host Direct peer resources');
+ }
+ },
+ };
+}
diff --git a/packages/runtime-host/src/server/host-kernel.ts b/packages/runtime-host/src/server/host-kernel.ts
index 4c22c1dee..0ac731e4d 100644
--- a/packages/runtime-host/src/server/host-kernel.ts
+++ b/packages/runtime-host/src/server/host-kernel.ts
@@ -84,6 +84,8 @@ import {
type RuntimeHostListenerSetFactory,
} from './listener-set.js';
import { HostResidencyRegistry } from './host-residency-registry.js';
+import type { PeerMeshNode } from '../peer-mesh/node.js';
+import { createPeerMeshOperationHandlers } from './peer-mesh-authority.js';
const DEFAULT_IDLE_GRACE_MS = 30_000;
const DEFAULT_HANDSHAKE_TIMEOUT_MS = 5_000;
@@ -141,6 +143,7 @@ interface RuntimeHostKernelCommonOptions {
composition: RuntimeHostCompositionSource;
listenerSetFactory?: RuntimeHostListenerSetFactory;
accessAuthority?: RuntimeHostAccessAuthority;
+ peerMesh?: PeerMeshNode;
}
export type RuntimeHostLifecycleMode = 'ephemeral' | 'service';
@@ -689,6 +692,7 @@ export class RuntimeHostKernel {
),
),
},
+ createPeerMeshOperationHandlers(this.#options.peerMesh),
domainHandlers,
);
}
diff --git a/packages/runtime-host/src/server/index.ts b/packages/runtime-host/src/server/index.ts
index 1621c78c6..8a058addf 100644
--- a/packages/runtime-host/src/server/index.ts
+++ b/packages/runtime-host/src/server/index.ts
@@ -25,6 +25,10 @@ export { defineInteractiveRuntimeHostComposition } from './host-composition.js';
export { createUnavailableDomainOperationHandlers } from './operation-dispatcher.js';
export { startExecutionRuntimeHostService } from './execution-service.js';
export { runRuntimeHostProcessLifecycle } from './process-lifecycle.js';
+export {
+ createPeerMeshOperationHandlers,
+ projectPeerMeshStatus,
+} from './peer-mesh-authority.js';
export { installRuntimeHostLogCapture } from '../process-diagnostics.js';
export {
readRuntimeHostAccessCredentialMetadata,
diff --git a/packages/runtime-host/src/server/operation-dispatcher.ts b/packages/runtime-host/src/server/operation-dispatcher.ts
index 91ab79f88..8208c5ad0 100644
--- a/packages/runtime-host/src/server/operation-dispatcher.ts
+++ b/packages/runtime-host/src/server/operation-dispatcher.ts
@@ -33,6 +33,8 @@ import {
} from '../protocol/index.js';
import { HOST_BOOTSTRAP_OPERATION_SPECS } from '../protocol/host-status.js';
import { ACCESS_AUTHORITY_OPERATION_SPECS } from '../protocol/access-authority.js';
+import { PEER_MESH_OPERATION_SPECS } from '../protocol/peer-mesh.js';
+import { createPeerMeshOperationHandlers } from './peer-mesh-authority.js';
export interface ConnectionContext {
hostEpoch: string;
@@ -58,7 +60,8 @@ export type OperationHandlerMap = {
export type HostCoreOperationKey =
| keyof typeof HOST_BOOTSTRAP_OPERATION_SPECS
- | keyof typeof ACCESS_AUTHORITY_OPERATION_SPECS;
+ | keyof typeof ACCESS_AUTHORITY_OPERATION_SPECS
+ | keyof typeof PEER_MESH_OPERATION_SPECS;
export type DomainOperationKey = Exclude<OperationKey, HostCoreOperationKey>;
export type TurnOperationKey = Extract<
OperationKey,
@@ -215,6 +218,8 @@ export type AccessAuthorityOperationHandlerMap = Pick<
OperationHandlerMap,
keyof typeof ACCESS_AUTHORITY_OPERATION_SPECS
>;
+export type HostCoreUnavailableOperationHandlerMap = AccessAuthorityOperationHandlerMap &
+ Pick<OperationHandlerMap, keyof typeof PEER_MESH_OPERATION_SPECS>;
export function composeOperationHandlers(
...handlerMaps: readonly Partial<OperationHandlerMap>[]
@@ -247,7 +252,8 @@ export function createUnavailableDomainOperationHandlers(): DomainOperationHandl
for (const operation of Object.keys(HOST_OPERATION_SPECS) as OperationKey[]) {
if (
Object.hasOwn(HOST_BOOTSTRAP_OPERATION_SPECS, operation) ||
- Object.hasOwn(ACCESS_AUTHORITY_OPERATION_SPECS, operation)
+ Object.hasOwn(ACCESS_AUTHORITY_OPERATION_SPECS, operation) ||
+ Object.hasOwn(PEER_MESH_OPERATION_SPECS, operation)
) {
continue;
}
@@ -329,6 +335,13 @@ export function createUnavailableAccessAuthorityOperationHandlers(): AccessAutho
};
}
+export function createUnavailableHostCoreOperationHandlers(): HostCoreUnavailableOperationHandlerMap {
+ return {
+ ...createUnavailableAccessAuthorityOperationHandlers(),
+ ...createPeerMeshOperationHandlers(undefined),
+ };
+}
+
export async function dispatchOperation(
request: RequestFrame,
handlers: OperationHandlerMap,
diff --git a/packages/runtime-host/src/server/peer-mesh-authority.ts b/packages/runtime-host/src/server/peer-mesh-authority.ts
new file mode 100644
index 000000000..fd2f0d649
--- /dev/null
+++ b/packages/runtime-host/src/server/peer-mesh-authority.ts
@@ -0,0 +1,169 @@
+/*
+ * Licensed to the Apache Software Foundation (ASF) under one
+ * or more contributor license agreements. See the NOTICE file
+ * distributed with this work for additional information
+ * regarding copyright ownership. The ASF licenses this file
+ * to you under the Apache License, Version 2.0 (the
+ * "License"); you may not use this file except in compliance
+ * with the License. You may obtain a copy of the License at
+ *
+ * http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing,
+ * software distributed under the License is distributed on an
+ * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+ * KIND, either express or implied. See the License for the
+ * specific language governing permissions and limitations
+ * under the License.
+ */
+
+import type { PeerMeshNode, PeerMeshStatus } from '../peer-mesh/node.js';
+import { PeerMeshPersistenceError, PeerMeshPostCommitError } from '../peer-mesh/store.js';
+import type { PeerMeshProjection, PeerMeshQueryResult } from '../protocol/peer-mesh.js';
+import type { OperationOutcome } from '../protocol/operations.js';
+import type { OperationHandlerMap } from './operation-dispatcher.js';
+
+export type PeerMeshOperationHandlers = Pick<
+ OperationHandlerMap,
+ | 'peer.mesh.query'
+ | 'peer.mesh.create'
+ | 'peer.mesh.invite'
+ | 'peer.mesh.join'
+ | 'peer.mesh.remove'
+ | 'peer.mesh.leave'
+ | 'peer.mesh.close'
+ | 'peer.mesh.reconcile'
+>;
+
+export function createPeerMeshOperationHandlers(
+ mesh: PeerMeshNode | undefined,
+): PeerMeshOperationHandlers {
+ const query = (): PeerMeshQueryResult =>
+ mesh
+ ? {
+ available: true,
+ localPeerId: mesh.localPeerId(),
+ meshes: mesh.status().map(projectPeerMeshStatus),
+ }
+ : { available: false, meshes: [] };
+ const unavailable = <K extends keyof PeerMeshOperationHandlers>(): OperationOutcome<K> =>
+ ({
+ ok: false,
+ error: {
+ code: 'operation_unavailable',
+ message: 'Direct peer is not enabled for this Runtime Host',
+ },
+ }) as OperationOutcome<K>;
+ const mutate = async <K extends keyof PeerMeshOperationHandlers>(
+ operation: () => Promise<OperationOutcome<K>>,
+ ): Promise<OperationOutcome<K>> => {
+ try {
+ return await operation();
+ } catch (error) {
+ if (error instanceof PeerMeshPostCommitError) {
+ return {
+ ok: false,
+ error: {
+ code: 'commit_outcome_unknown',
+ message: 'Peer Mesh changed, but its durable commit could not be confirmed',
+ },
+ } as OperationOutcome<K>;
+ }
+ if (error instanceof PeerMeshPersistenceError) {
+ return {
+ ok: false,
+ error: {
+ code: 'persistence_failed',
+ message: 'Peer Mesh state could not be saved',
+ },
+ } as OperationOutcome<K>;
+ }
+ return {
+ ok: false,
+ error: {
+ code: 'invalid_request',
+ message: error instanceof Error ? error.message : 'Peer Mesh operation failed',
+ },
+ } as OperationOutcome<K>;
+ }
+ };
+
+ return {
+ 'peer.mesh.query': async () => ({ ok: true, result: query() }),
+ 'peer.mesh.create': async () => {
+ if (!mesh) return unavailable();
+ return mutate(async () => ({
+ ok: true,
+ result: projectPeerMeshStatus(await mesh.create()),
+ }));
+ },
+ 'peer.mesh.invite': async (input) => {
+ if (!mesh) return unavailable();
+ return mutate(async () => ({
+ ok: true,
+ result: {
+ invitation: await mesh.invite(input.meshId, {
+ ...(input.ttlMs ? { ttlMs: input.ttlMs } : {}),
+ }),
+ },
+ }));
+ },
+ 'peer.mesh.join': async (input) => {
+ if (!mesh) return unavailable();
+ return mutate(async () => ({
+ ok: true,
+ result: projectPeerMeshStatus(await mesh.join(input.invitation)),
+ }));
+ },
+ 'peer.mesh.remove': async (input) => {
+ if (!mesh) return unavailable();
+ return mutate(async () => ({
+ ok: true,
+ result: projectPeerMeshStatus(await mesh.remove(input.meshId, input.peerId)),
+ }));
+ },
+ 'peer.mesh.leave': async (input) => {
+ if (!mesh) return unavailable();
+ return mutate(async () => {
+ await mesh.leave(input.meshId);
+ return { ok: true, result: query() };
+ });
+ },
+ 'peer.mesh.close': async (input) => {
+ if (!mesh) return unavailable();
+ return mutate(async () => ({
+ ok: true,
+ result: projectPeerMeshStatus(await mesh.closeMesh(input.meshId)),
+ }));
+ },
+ 'peer.mesh.reconcile': async () => {
+ if (!mesh) return unavailable();
+ try {
+ await mesh.reconcile();
+ return { ok: true, result: query() };
+ } catch {
+ return {
+ ok: false,
+ error: {
+ code: 'operation_unavailable',
+ message: 'Peer Mesh could not reach any current route',
+ },
+ };
+ }
+ },
+ };
+}
+
+export function projectPeerMeshStatus(status: PeerMeshStatus): PeerMeshProjection {
+ return Object.freeze({
+ meshId: status.roster.roster.meshId,
+ role: status.role,
+ localPeerId: status.localPeerId,
+ authorityPeerId: status.authority.peerId,
+ revision: status.roster.roster.revision,
+ closed: status.roster.roster.closed,
+ members: Object.freeze([...status.roster.roster.members]),
+ memberRoutes: Object.freeze(status.memberRoutes.map((route) => Object.freeze({ ...route }))),
+ pendingInvitationCount: status.pendingInvitationCount,
+ });
+}
---------------------------------------------------------------------
To unsubscribe, e-mail: commits-unsubscribe@maka.apache.org
For additional commands, e-mail: commits-help@maka.apache.org