feat(session): a terminal session says why it ended

`ended` and `failed` say how a run finished but not why: a stop its owner
asked for, a free weekend running out, an idle box and a game quitting on
its own all left the same row behind. A session now carries `end_reason`,
one word from a fixed list, written by whoever ends the run, and
`time_claimed`, stamped when a host takes the run, so bring-up can be
measured from the claim rather than from the request.

The control plane writes the two endings it decides itself: `user` when
the owner stops a run nobody had claimed yet, and `left_queue` when a
waiting run is abandoned. The write keeps a reason only on a terminal
state, the same way an error message is kept only for a failure, so no
row can say it ended while it is still going. Both fields are returned
wherever a session is.

The column is text rather than a database enum so a reason added later
is a code change and not a migration.
This commit is contained in:
Wanjohi
2026-10-15 23:25:44 +03:00
parent d565e6d445
commit c467dc082d
9 changed files with 4036 additions and 14 deletions
+5 -1
View File
@@ -146,7 +146,11 @@ describe('the line for a full host', () => {
await Session.setState({ id: playing.run.id, state: 'ended' });
expect((await h.jobs()).map((j) => j.sessionId)).toEqual([here.run.id]);
const left = await Session.fromID(gone.run.id);
expect(left).toMatchObject({ state: 'ended', errorMessage: 'Left the queue' });
expect(left).toMatchObject({
state: 'ended',
errorMessage: 'Left the queue',
endReason: 'left_queue'
});
});
test('a run with a slot is not in line', async () => {
+13 -2
View File
@@ -160,11 +160,13 @@ describe('POST /session', () => {
state: 'requested',
tier: null,
ticket: null,
timeClaimed: null,
timeStarted: null,
timeStopped: null,
timeStopRequested: null,
trial: false,
errorMessage: null
errorMessage: null,
endReason: null
});
expect(body.data.id.startsWith('ses_')).toBe(true);
});
@@ -478,7 +480,11 @@ describe('POST /session/:id/state', () => {
body: JSON.stringify({ state: 'starting', claimToken: HOLDER })
});
expect(res.status).toBe(200);
expect(((await res.json()) as any).data.state).toBe('starting');
const claimed = ((await res.json()) as any).data;
expect(claimed.state).toBe('starting');
// The time it was taken is what bring-up is measured from.
expect(body.data.timeClaimed).toBeNull();
expect(claimed.timeClaimed).not.toBeNull();
const jobs = await app.request('/machine/jobs', { headers: s.host });
expect(((await jobs.json()) as any).data).toEqual([]);
@@ -721,6 +727,7 @@ describe('POST /session/:id/ticket', () => {
const data = ((await read.json()) as any).data;
expect(Object.keys(data).sort()).toEqual([
'boxId',
'endReason',
'errorMessage',
'gameId',
'id',
@@ -729,6 +736,7 @@ describe('POST /session/:id/ticket', () => {
'state',
'ticket',
'tier',
'timeClaimed',
'timeStarted',
'timeStopRequested',
'timeStopped',
@@ -901,6 +909,9 @@ describe('POST /session/:id/stop', () => {
const out = (await res.json()) as any;
expect(out.data.state).toBe('ended');
expect(out.data.timeStopped).not.toBeNull();
// Ended here rather than by a host, so the reason is written here too.
expect(out.data.endReason).toBe('user');
expect(out.data.timeClaimed).toBeNull();
const res2 = await app.request('/machine/jobs', { headers: s.host });
expect(((await res2.json()) as any).data).toEqual([]);
});