feat(studio): integrate memcard persistence and headless controls
Persist cartridge identity and slot configuration, add MemcardBoot and the MemcardBuffer SDK, and consume the runtime's negotiated memcard host controls with protected teardown. Qualify save/reopen and version upgrades through distinct configured runtime processes. Include specs, examples, regression evidence and the consolidated discussion lesson.
This commit is contained in:
@@ -23,6 +23,9 @@ final class HeadlessProcessSession implements HeadlessGateway.Session {
|
||||
private volatile String sessionId;
|
||||
private volatile JsonNode hello;
|
||||
private Path cartridge;
|
||||
private Path projectRoot;
|
||||
private Path selectedImage;
|
||||
private boolean memcardEnabled;
|
||||
private final CompletableFuture<JsonNode> greeting = new CompletableFuture<>();
|
||||
private final Map<String, Pending> pending = new ConcurrentHashMap<>();
|
||||
private final Set<ProcessHandle> descendants = ConcurrentHashMap.newKeySet();
|
||||
@@ -34,7 +37,7 @@ final class HeadlessProcessSession implements HeadlessGateway.Session {
|
||||
private final AtomicReference<Pending> advance = new AtomicReference<>();
|
||||
private final Deque<String> stderr = new ArrayDeque<>();
|
||||
private volatile boolean closing;
|
||||
private CompletableFuture<Void> shutdown;
|
||||
private CompletableFuture<TaskTools.HeadlessReply> shutdown;
|
||||
|
||||
HeadlessProcessSession(Process process, ObjectMapper source, HeadlessLimits limits, String buildId) {
|
||||
this.process = process; this.limits = limits; this.buildId = buildId;
|
||||
@@ -46,21 +49,57 @@ final class HeadlessProcessSession implements HeadlessGateway.Session {
|
||||
}
|
||||
|
||||
void initializeAndBoot(Path cartridge) throws Exception {
|
||||
initializeAndBoot(cartridge, cartridge, false, Map.of());
|
||||
}
|
||||
void initializeAndBoot(Path cartridge, Path projectRoot, boolean memcard, Map<String, Object> options) throws Exception {
|
||||
initializeAndBoot(cartridge, projectRoot, memcard, options, projectRoot.resolve(".studio/memcard.pmc"));
|
||||
}
|
||||
void initializeAndBoot(Path cartridge, Path projectRoot, boolean memcard, Map<String, Object> options, Path selectedImage) throws Exception {
|
||||
this.cartridge = cartridge;
|
||||
this.projectRoot = projectRoot;
|
||||
this.selectedImage = selectedImage;
|
||||
JsonNode bootOptions = mapper.valueToTree(options);
|
||||
HeadlessMemcard.boot(mapper, cartridge, bootOptions);
|
||||
long deadline = System.nanoTime() + TimeUnit.MILLISECONDS.toNanos(limits.handshakeTimeoutMs());
|
||||
hello = await(greeting, limits.handshakeTimeoutMs());
|
||||
version(hello.path("protocolVersion")); text(hello, "runtimeVersion"); capabilities(hello.path("capabilities"));
|
||||
var required = new HashSet<>(CAPABILITIES);
|
||||
if (memcard) {
|
||||
if (count(hello.path("protocolVersion"), "minor") < 1) throw incompatibleMemcard();
|
||||
boolean available = false;
|
||||
for (var capability : hello.path("capabilities")) if (capability.asText().equals("memcard")) available = true;
|
||||
if (!available) throw incompatibleMemcard();
|
||||
required.add("memcard");
|
||||
}
|
||||
var expected = mapper.valueToTree(limits);
|
||||
for (var fields = expected.fieldNames(); fields.hasNext();) {
|
||||
String field = fields.next();
|
||||
if (count(hello.path("limits"), field) != expected.path(field).longValue())
|
||||
throw new AutomationException(AutomationFailure.Code.RUNTIME_INCOMPATIBLE, "Runtime limits do not match launch configuration");
|
||||
}
|
||||
var init = mapper.createObjectNode(); init.putObject("protocolVersion").put("major", 1).put("minor", 0);
|
||||
init.set("requiredCapabilities", mapper.valueToTree(CAPABILITIES));
|
||||
var init = mapper.createObjectNode(); init.putObject("protocolVersion").put("major", 1).put("minor", memcard ? 1 : 0);
|
||||
init.set("requiredCapabilities", mapper.valueToTree(required));
|
||||
var negotiated = request("initialize", init, null, remaining(deadline));
|
||||
version(negotiated.path("protocolVersion")); capabilities(negotiated.path("capabilities"));
|
||||
state(request("boot", mapper.createObjectNode().put("path", cartridge.toString()), null, limits.callTimeoutMs()));
|
||||
if (memcard) {
|
||||
boolean available = false;
|
||||
for (var capability : negotiated.path("capabilities")) if (capability.asText().equals("memcard")) available = true;
|
||||
if (count(negotiated.path("protocolVersion"), "minor") < 1 || !available) throw incompatibleMemcard();
|
||||
}
|
||||
memcardEnabled = memcard;
|
||||
state(boot(bootOptions));
|
||||
}
|
||||
private static AutomationException incompatibleMemcard() {
|
||||
return new AutomationException(AutomationFailure.Code.RUNTIME_INCOMPATIBLE, "Configured runtime requires protocol 1.1 and memcard capability");
|
||||
}
|
||||
private JsonNode boot(JsonNode options) throws Exception {
|
||||
var params = HeadlessMemcard.boot(mapper, cartridge, options);
|
||||
if (options.has("memcard")) {
|
||||
if (!memcardEnabled) throw incompatibleMemcard();
|
||||
HeadlessMemcard.state(request("memcard_mount", HeadlessMemcard.mount(mapper, projectRoot, options.path("memcard"), selectedImage), null, limits.callTimeoutMs()));
|
||||
}
|
||||
if (options.has("memcardChoice") && !memcardEnabled) throw incompatibleMemcard();
|
||||
return request("boot", params, null, limits.callTimeoutMs());
|
||||
}
|
||||
@Override public String sessionId() { return sessionId; }
|
||||
@Override public long maxFramesPerAdvance() { return limits.maxFrames(); }
|
||||
@@ -68,16 +107,28 @@ final class HeadlessProcessSession implements HeadlessGateway.Session {
|
||||
boolean alive() { return process.isAlive() || descendants.stream().anyMatch(ProcessHandle::isAlive); }
|
||||
|
||||
@Override public TaskTools.HeadlessReply call(TaskTools.HeadlessAction action, Map<String, Object> input) throws Exception {
|
||||
if (action == TaskTools.HeadlessAction.SHUTDOWN) return await(stop(input).toCompletableFuture(), limits.shutdownTimeoutMs() + 1000);
|
||||
if (!work.tryLock()) throw new AutomationException(AutomationFailure.Code.BUSY, "Headless operation active");
|
||||
try {
|
||||
if (closing) throw new AutomationException(AutomationFailure.Code.BUSY, "Headless shutdown active");
|
||||
String command = switch (action) {
|
||||
case BOOT -> "boot";
|
||||
case RESET -> "reset"; case SET_INPUT -> "set_input"; case CLEAR_INPUT -> "clear_input";
|
||||
case CAPTURE -> "capture"; case STATE -> "get_state"; case FAULT -> "get_fault";
|
||||
case MEMCARD_STATE -> "get_memcard_state"; case MEMCARD_MOUNT -> "memcard_mount";
|
||||
case MEMCARD_UNMOUNT -> "memcard_unmount"; case MEMCARD_RECONCILE -> "memcard_reconcile";
|
||||
case MEMCARD_CONTINUE_IN_MEMORY -> "memcard_continue_in_memory";
|
||||
default -> throw new IllegalArgumentException("Use lifecycle methods for boot/shutdown");
|
||||
};
|
||||
var params = action == TaskTools.HeadlessAction.BOOT ? mapper.createObjectNode().put("path", cartridge.toString()) : mapper.valueToTree(input);
|
||||
var result = request(command, params, null, limits.callTimeoutMs());
|
||||
boolean memcardAction = action.name().startsWith("MEMCARD_");
|
||||
if (memcardAction && !memcardEnabled) throw incompatibleMemcard();
|
||||
JsonNode params = mapper.valueToTree(input);
|
||||
if (action == TaskTools.HeadlessAction.MEMCARD_MOUNT) params = HeadlessMemcard.mount(mapper, projectRoot, params, selectedImage);
|
||||
if (action == TaskTools.HeadlessAction.RESET) {
|
||||
params = HeadlessMemcard.teardown(mapper, input);
|
||||
if (!input.isEmpty() && !memcardEnabled) throw incompatibleMemcard();
|
||||
}
|
||||
var result = action == TaskTools.HeadlessAction.BOOT ? boot(params) : request(command, params, null, limits.callTimeoutMs());
|
||||
var values = new LinkedHashMap<String, Object>(); values.put("sessionId", sessionId); values.put("buildId", buildId);
|
||||
CanonicalCapture capture = null;
|
||||
switch (action) {
|
||||
@@ -87,8 +138,12 @@ final class HeadlessProcessSession implements HeadlessGateway.Session {
|
||||
values.put("runtimeVersion", text(hello, "runtimeVersion"));
|
||||
values.put("limits", mapper.convertValue(hello.path("limits"), Object.class));
|
||||
values.put("capabilities", mapper.convertValue(hello.path("capabilities"), Object.class));
|
||||
if (memcardEnabled && action == TaskTools.HeadlessAction.RESET) HeadlessMemcard.state(result.path("memcard"));
|
||||
}
|
||||
case FAULT -> { fault(result); values.put("fault", mapper.convertValue(result, Object.class)); }
|
||||
case MEMCARD_STATE, MEMCARD_MOUNT, MEMCARD_UNMOUNT, MEMCARD_RECONCILE, MEMCARD_CONTINUE_IN_MEMORY -> {
|
||||
HeadlessMemcard.state(result); values.put("memcard", mapper.convertValue(result, Object.class));
|
||||
}
|
||||
default -> { if (!result.isObject()) throw invalid("Invalid acknowledgement"); }
|
||||
}
|
||||
return new TaskTools.HeadlessReply(values, capture);
|
||||
@@ -101,6 +156,7 @@ final class HeadlessProcessSession implements HeadlessGateway.Session {
|
||||
if (!work.tryLock()) throw new AutomationException(AutomationFailure.Code.BUSY, "Headless operation active");
|
||||
boolean interrupted = false;
|
||||
try {
|
||||
if (closing) throw new AutomationException(AutomationFailure.Code.BUSY, "Headless shutdown active");
|
||||
var item = new Pending("advance", frames, progress); advance.set(item);
|
||||
send(item, mapper.createObjectNode().put("frames", frames));
|
||||
JsonNode result;
|
||||
@@ -121,6 +177,12 @@ final class HeadlessProcessSession implements HeadlessGateway.Session {
|
||||
case "completed" -> { if (completed != frames) throw invalid("Incomplete completed result"); yield AutomationOutcome.Kind.SUCCEEDED; }
|
||||
case "canceled" -> AutomationOutcome.Kind.CANCELLED;
|
||||
case "terminated" -> AutomationOutcome.Kind.TERMINATED;
|
||||
case "action_required" -> {
|
||||
if (!memcardEnabled) throw invalid("Unnegotiated memcard outcome");
|
||||
var nativeState = request("get_memcard_state", mapper.createObjectNode(), null, limits.callTimeoutMs());
|
||||
HeadlessMemcard.state(nativeState); diagnostics.add(nativeState.toString());
|
||||
yield AutomationOutcome.Kind.ACTION_REQUIRED;
|
||||
}
|
||||
case "faulted" -> { fault(result.path("fault")); if (result.path("fault").isNull()) throw invalid("Missing fault"); diagnostics.add(result.path("fault").toString()); yield AutomationOutcome.Kind.GUEST_FAULT; }
|
||||
case "host_error" -> { error(result.path("error")); diagnostics.add(result.path("error").toString()); yield AutomationOutcome.Kind.INFRASTRUCTURE_FAILURE; }
|
||||
default -> throw invalid("Unknown advance stop");
|
||||
@@ -150,26 +212,47 @@ final class HeadlessProcessSession implements HeadlessGateway.Session {
|
||||
abort("Headless session lost during cancellation");
|
||||
}
|
||||
}
|
||||
@Override public synchronized CompletionStage<Void> shutdown() {
|
||||
@Override public CompletionStage<Void> shutdown() { return stop(Map.of()).thenApply(ignored -> null); }
|
||||
@Override public CompletionStage<Void> shutdown(boolean discardUnsaved) {
|
||||
return stop(discardUnsaved ? Map.of("discardUnsaved", true, "pendingWrites", "cancel") : Map.of()).thenApply(ignored -> null);
|
||||
}
|
||||
@Override public synchronized CompletionStage<TaskTools.HeadlessReply> stop(Map<String, Object> policy) {
|
||||
var params = HeadlessMemcard.teardown(mapper, policy);
|
||||
if (!policy.isEmpty() && !memcardEnabled) return CompletableFuture.failedFuture(incompatibleMemcard());
|
||||
if (shutdown != null) {
|
||||
// The first forced shutdown reports infrastructure failure. An explicit human
|
||||
// retry may acknowledge completed cleanup, but never releases a living process.
|
||||
if (shutdown.isCompletedExceptionally() && dead.get() && !alive())
|
||||
shutdown = CompletableFuture.completedFuture(null);
|
||||
return shutdown;
|
||||
if (!shutdown.isCompletedExceptionally()) return shutdown;
|
||||
if (dead.get() && !alive()) return CompletableFuture.completedFuture(new TaskTools.HeadlessReply(Map.of("sessionId", sessionId), null));
|
||||
// A native refusal leaves this channel usable for an explicit retry.
|
||||
if (closing) return shutdown;
|
||||
}
|
||||
closing = true;
|
||||
shutdown = CompletableFuture.runAsync(() -> {
|
||||
shutdown = CompletableFuture.supplyAsync(() -> {
|
||||
long deadline = System.nanoTime() + TimeUnit.MILLISECONDS.toNanos(limits.shutdownTimeoutMs());
|
||||
try {
|
||||
if (!dead.get()) {
|
||||
var response = request("shutdown", mapper.createObjectNode(), null, remaining(deadline));
|
||||
var response = request("shutdown", params, null, remaining(deadline));
|
||||
if (!response.path("closed").isBoolean() || !response.path("closed").booleanValue()) throw invalid("Missing shutdown acknowledgement");
|
||||
if (memcardEnabled) HeadlessMemcard.state(response.path("memcard"));
|
||||
if (!process.waitFor(remaining(deadline), TimeUnit.MILLISECONDS)) throw new TimeoutException();
|
||||
terminate();
|
||||
if (alive()) throw infrastructure("Owned runtime process tree did not terminate");
|
||||
var values = new LinkedHashMap<String, Object>(); values.put("sessionId", sessionId);
|
||||
values.putAll(mapper.convertValue(response, new com.fasterxml.jackson.core.type.TypeReference<Map<String, Object>>() {}));
|
||||
return new TaskTools.HeadlessReply(values, null);
|
||||
}
|
||||
terminate();
|
||||
if (alive()) throw infrastructure("Owned runtime process tree did not terminate");
|
||||
return new TaskTools.HeadlessReply(Map.of("sessionId", sessionId), null);
|
||||
} catch (AutomationException refusal) {
|
||||
if (refusal.failure().code() == AutomationFailure.Code.MEMCARD_ERROR) {
|
||||
closing = false; throw new CompletionException(refusal);
|
||||
}
|
||||
abort("Headless shutdown failed"); throw infrastructure("Headless shutdown failed; owned process tree terminated; save publication outcome unknown");
|
||||
} catch (Exception failure) {
|
||||
abort("Headless shutdown failed"); throw infrastructure("Headless shutdown failed; owned process tree terminated");
|
||||
} finally { terminate(); if (alive()) throw infrastructure("Owned runtime process tree did not terminate"); }
|
||||
abort("Headless shutdown failed"); throw infrastructure("Headless shutdown failed; owned process tree terminated; save publication outcome unknown");
|
||||
}
|
||||
});
|
||||
return shutdown;
|
||||
}
|
||||
@@ -242,6 +325,12 @@ final class HeadlessProcessSession implements HeadlessGateway.Session {
|
||||
case "not_cancelable" -> AutomationFailure.Code.NOT_CANCELABLE;
|
||||
case "incompatible_version", "unsupported_capability" -> AutomationFailure.Code.RUNTIME_INCOMPATIBLE;
|
||||
case "limit_exceeded", "response_too_large" -> AutomationFailure.Code.LIMIT_EXCEEDED;
|
||||
case "memcard_error" -> {
|
||||
if (!memcardEnabled) throw invalid("Unnegotiated memcard error");
|
||||
text(error.path("details"), "operation"); text(error.path("details"), "reason");
|
||||
HeadlessMemcard.state(error.path("details").path("state"));
|
||||
yield AutomationFailure.Code.MEMCARD_ERROR;
|
||||
}
|
||||
default -> AutomationFailure.Code.INFRASTRUCTURE_FAILURE;
|
||||
};
|
||||
pending.remove(item.id);
|
||||
|
||||
Reference in New Issue
Block a user