mirror of
https://github.com/nestriness/nestri.git
synced 2026-11-19 13:39:48 +02:00
feat(session): a finished session says why it ended (#412)
Until now every finished run said only `ended` or `failed`. A user stop, a trial window running out, an idle timeout, a host restart and a game quitting were indistinguishable afterwards. **Schema.** Migration `0026_session_end_reason` adds two nullable columns to `session`: - `end_reason`: one of `user`, `window`, `hours`, `idle`, `left_queue`, `game_exited`, `launch_failed`, `host_stopped`, `host_restart`. - `time_claimed`: when a host took the run, set on `requested → starting`. **API.** - `POST /session/:id/state` takes an optional `endReason`. With `ended` or `failed` it is stored. With `starting` or `live` it is a 400 and the run does not move. - Leaving it out of a terminal report stores null, so host agents that predate this keep working. - `endReason` and `timeClaimed` are returned on every session response. - The API writes the reasons it decides itself: `user` when a run nobody has claimed is stopped, and `left_queue` when a waiting run is abandoned (the `Left the queue` message is kept). **New transition, `starting → ended`.** A run stopped while its game is still downloading has failed at nothing, and never reached `live`, which is where billing starts. Until now the only way out of `starting` was `failed`. **Release order: this goes first.** The host agent that sends `endReason` is a separate change. This route's body schema is strict, so without this deployed the current API answers that agent with a 400. **Tests.** - API: 185 pass, 5 of them new. - Core: 41 session tests pass, 3 of them new. - The new tests fail when the implementation is broken on purpose. - No new type errors.
This commit is contained in:
@@ -88,10 +88,18 @@ export namespace SessionApi {
|
||||
errorMessage: z.string().max(1024).nullable().optional().meta({
|
||||
description: 'Why it failed. Kept only for a run that did',
|
||||
example: Examples.Session.errorMessage
|
||||
}),
|
||||
endReason: Session.EndReason.nullable().optional().meta({
|
||||
description:
|
||||
'Why the run is over. Only with `ended` or `failed`; leave it out and the run records no reason',
|
||||
example: 'game_exited'
|
||||
})
|
||||
})
|
||||
.strict();
|
||||
|
||||
/** The states a run is over in, and so the only ones a reason goes with. */
|
||||
const TERMINAL: readonly Session.ReportableState[] = ['ended', 'failed'];
|
||||
|
||||
export const route = new Hono()
|
||||
.get(
|
||||
'/',
|
||||
@@ -385,7 +393,7 @@ export namespace SessionApi {
|
||||
tags: ['Session'],
|
||||
summary: 'Report where a run has got to',
|
||||
description:
|
||||
'For the host the run’s box is placed on, and no other. Moving a run out of `requested` is the claim, and it is a compare-and-set: exactly one caller can take a given run, and one that loses gets 409. Re-reporting a state already reported is fine and changes nothing, including the timestamps a run is billed on. A transition that does not exist is 409 and the run does not move.',
|
||||
'For the host the run’s box is placed on, and no other. Moving a run out of `requested` is the claim, and it is a compare-and-set: exactly one caller can take a given run, and one that loses gets 409. Re-reporting a state already reported is fine and changes nothing, including the timestamps a run is billed on. A transition that does not exist is 409 and the run does not move. Say why a run ended with `endReason` on the report that ends it; sending one with any other state is 400.',
|
||||
responses: {
|
||||
200: {
|
||||
content: { 'application/json': { schema: Result(Session.Info) } },
|
||||
@@ -400,12 +408,24 @@ export namespace SessionApi {
|
||||
validator('json', StateReport),
|
||||
async (c) => {
|
||||
const body = c.req.valid('json');
|
||||
// Refused rather than dropped. A reason on a run that is still
|
||||
// going is a host agent that has its states and its reasons out
|
||||
// of step, and storing nothing would hide that from it.
|
||||
if (body.endReason && !TERMINAL.includes(body.state)) {
|
||||
throw new VisibleError(
|
||||
'validation',
|
||||
ErrorCodes.Validation.INVALID_PARAMETER,
|
||||
`A run that is ${body.state} is not over, so it has no reason to have ended`,
|
||||
'endReason'
|
||||
);
|
||||
}
|
||||
const result = await Session.transition({
|
||||
id: c.req.valid('param').id,
|
||||
machineId: Actor.machineID,
|
||||
state: body.state,
|
||||
claimToken: body.claimToken,
|
||||
errorMessage: body.errorMessage ?? null
|
||||
errorMessage: body.errorMessage ?? null,
|
||||
endReason: body.endReason ?? null
|
||||
});
|
||||
|
||||
switch (result.outcome) {
|
||||
|
||||
Reference in New Issue
Block a user