feat(box): create a box, on your own host or on rented GPUs

POST /box places a box once, at creation. On your own host it keeps the
existing rule (exactly one host, or refuse). On the fleet it picks an
online machine owned by the fleet organisation, the one holding the
fewest boxes. Each person holds at most one fleet box. Which organisation
is the fleet is deploy configuration, so no deployment rents hardware it
was not told to.

No machine online is a 429, since the same request succeeds once one is
back.
This commit is contained in:
Wanjohi
2026-10-07 09:23:12 +03:00
parent 9d7239a280
commit f82666254e
6 changed files with 326 additions and 27 deletions
+78 -25
View File
@@ -1,39 +1,92 @@
import { Actor } from '@nestri/core/actor';
import { BoxTier } from '@nestri/core/box/box.sql';
import { Box } from '@nestri/core/box/index';
import { Placement } from '@nestri/core/box/placement';
import { Env } from '@nestri/core/env';
import { ErrorCodes, VisibleError } from '@nestri/core/error';
import { Examples } from '@nestri/core/examples';
import { Identifier } from '@nestri/core/id';
import { Hono } from 'hono';
import { describeRoute } from 'hono-openapi';
import { z } from 'zod';
import { ErrorResponses, notPublic, Result } from '../utils';
import { ErrorResponses, notPublic, Result, validator } from '../utils';
/**
* The caller's boxes. Read-only: a box is created by placement and its state
* is whatever its host last reported, so the list is the whole of what a
* person can ask here for now.
* The caller's boxes. A box is created here and placed once — on your own
* host, or on the fleet — and its state is whatever its host last reported.
*/
export namespace BoxApi {
export const route = new Hono().use(notPublic).get(
'/',
describeRoute({
tags: ['Box'],
summary: 'Your boxes',
description:
'Every box you own, oldest first, with its state and — for one that stopped — why, as its host reported it.',
responses: {
200: {
content: {
'application/json': {
schema: Result(
z.array(Box.Info).meta({ description: 'Your boxes', example: [Examples.Box] })
)
}
export const route = new Hono()
.use(notPublic)
.post(
'/',
describeRoute({
tags: ['Box'],
summary: 'Create a box',
description:
'A box on your own host (`on: "own"`, the default; refused unless you have exactly one) or on a Nestri GPU (`on: "fleet"`). You hold at most one box on Nestri GPUs; asking again is a 409.',
responses: {
201: {
content: { 'application/json': { schema: Result(Box.Info) } },
description: 'The box, placed'
},
description: 'Your boxes'
},
401: ErrorResponses[401]
400: ErrorResponses[400],
401: ErrorResponses[401],
404: ErrorResponses[404],
409: ErrorResponses[409]
}
}),
validator(
'json',
z.object({
label: z.string().trim().min(1).max(64).default('box'),
tier: z.enum(BoxTier.enumValues).default('sm'),
on: z.enum(['own', 'fleet']).default('own')
})
),
async (c) => {
const { label, tier, on } = c.req.valid('json');
const userId = Actor.userID;
if (on === 'fleet') {
const organisationId = Env.get().FLEET_ORGANISATION_ID;
const held = organisationId ? await Box.onFleet({ userId, organisationId }) : null;
if (held) {
throw new VisibleError(
'already_exists',
ErrorCodes.Validation.ALREADY_EXISTS,
`You already have a box on Nestri GPUs: ${held.id}`
);
}
}
const box = await Box.createPlaced(
{ id: Identifier.ascending('box'), userId, label, tier },
on === 'fleet' ? Placement.fleet : Placement.onlyHost
);
return c.json({ data: box }, 201);
}
}),
async (c) => c.json({ data: await Box.listByUser(Actor.userID) })
);
)
.get(
'/',
describeRoute({
tags: ['Box'],
summary: 'Your boxes',
description:
'Every box you own, oldest first, with its state and — for one that stopped — why, as its host reported it.',
responses: {
200: {
content: {
'application/json': {
schema: Result(
z.array(Box.Info).meta({ description: 'Your boxes', example: [Examples.Box] })
)
}
},
description: 'Your boxes'
},
401: ErrorResponses[401]
}
}),
async (c) => c.json({ data: await Box.listByUser(Actor.userID) })
);
}
+127
View File
@@ -0,0 +1,127 @@
import { afterAll, describe, expect, test } from 'bun:test';
import { AccessToken } from '@nestri/core/access-token/index';
import { Box } from '@nestri/core/box/index';
import { Fixtures } from '@nestri/core/db/fixtures';
import { testDb } from '@nestri/core/db/test';
import { Env } from '@nestri/core/env';
import { Identifier } from '@nestri/core/id';
import { app } from '../app/index';
import { TEST_FRONTEND_URL } from './setup';
const sql = testDb();
const createdUserIds: string[] = [];
const createdOrgIds: string[] = [];
function useFleet(organisationId?: string) {
Env.init({
NODE_ENV: 'test',
FRONTEND_URL: TEST_FRONTEND_URL,
...(organisationId ? { FLEET_ORGANISATION_ID: organisationId } : {})
});
}
async function person(label: string) {
const owner = await Fixtures.owner(label);
createdUserIds.push(owner.userId);
const pat = await AccessToken.create({
id: Identifier.ascending('accessToken'),
ownerUserId: owner.userId,
teamId: null,
name: label
});
return {
owner,
headers: {
authorization: `Bearer ${pat.token}`,
'content-type': 'application/json'
} as Record<string, string>
};
}
async function fleet(hosts: number) {
const operator = await Fixtures.owner('operator');
createdUserIds.push(operator.userId);
const f = await Fixtures.fleet(operator, hosts);
createdOrgIds.push(f.organisationId);
return f;
}
function createBox(headers: Record<string, string>, body: object) {
return app.request('/box', { method: 'POST', headers, body: JSON.stringify(body) });
}
afterAll(async () => {
await sql`delete from box where user_id = any(${createdUserIds})`;
await sql`delete from machine where owner_user_id = any(${createdUserIds})`;
await sql`delete from organisation where id = any(${createdOrgIds})`;
await sql`delete from "user" where id = any(${createdUserIds})`;
});
describe('POST /box on the fleet', () => {
test('places on the online fleet machine holding the fewest boxes', async () => {
const f = await fleet(2);
useFleet(f.organisationId);
const [first, second] = f.machines;
const a = await person('fleet-a');
const resA = await createBox(a.headers, { on: 'fleet' });
expect(resA.status).toBe(201);
const boxA = ((await resA.json()) as any).data;
expect(boxA.machineId).toBe(first!.id);
const b = await person('fleet-b');
const boxB = ((await (await createBox(b.headers, { on: 'fleet' })).json()) as any).data;
expect(boxB.machineId).toBe(second!.id);
});
test('skips a fleet machine that is offline', async () => {
const f = await fleet(2);
useFleet(f.organisationId);
await sql`update machine set last_seen = now() - interval '1 hour' where id = ${f.machines[0]!.id}`;
const p = await person('fleet-offline');
const box = ((await (await createBox(p.headers, { on: 'fleet' })).json()) as any).data;
expect(box.machineId).toBe(f.machines[1]!.id);
});
test('no fleet machine online is a 429 that says so', async () => {
const f = await fleet(1);
useFleet(f.organisationId);
await sql`update machine set last_seen = null where id = ${f.machines[0]!.id}`;
const p = await person('fleet-none');
const res = await createBox(p.headers, { on: 'fleet' });
expect(res.status).toBe(429);
expect(((await res.json()) as any).message).toContain('No Nestri GPU is free');
});
test('a deployment with no fleet configured refuses fleet boxes', async () => {
useFleet();
const p = await person('fleet-unset');
const res = await createBox(p.headers, { on: 'fleet' });
expect(res.status).toBe(500);
expect(((await res.json()) as any).message).toContain('not available');
});
test('one fleet box each: asking again is a 409', async () => {
const f = await fleet(1);
useFleet(f.organisationId);
const p = await person('fleet-twice');
expect((await createBox(p.headers, { on: 'fleet' })).status).toBe(201);
const again = await createBox(p.headers, { on: 'fleet' });
expect(again.status).toBe(409);
expect((await Box.listByUser(p.owner.userId)).length).toBe(1);
});
test('`on` defaults to your own host', async () => {
const f = await fleet(1);
useFleet(f.organisationId);
const p = await person('own-default');
const machineId = await Fixtures.machine(p.owner);
const res = await createBox(p.headers, { label: 'mine' });
expect(res.status).toBe(201);
expect(((await res.json()) as any).data.machineId).toBe(machineId);
});
});
+28
View File
@@ -4,6 +4,7 @@ import z from 'zod';
import { Database } from '../db/index.js';
import { Examples } from '../examples.js';
import { fn } from '../fn.js';
import { MachineTable } from '../machine/machine.sql.js';
import { BoxState, BoxTable, BoxTier } from './box.sql.js';
import { Placement } from './placement.js';
@@ -125,6 +126,33 @@ export namespace Box {
});
});
/**
* The box a person already holds on the fleet's hardware, if any.
*
* One each: a rented GPU is the scarce thing, and a second box would be a
* second claim on it that nothing yet prices.
*/
export const onFleet = fn(
z.object({ userId: Info.shape.userId, organisationId: z.string() }),
async (input) => {
return Database.use(async (tx) => {
return tx
.select({ box: BoxTable })
.from(BoxTable)
.innerJoin(MachineTable, eq(BoxTable.machineId, MachineTable.id))
.where(
and(
eq(BoxTable.userId, input.userId),
eq(MachineTable.organisationId, input.organisationId),
isNull(BoxTable.timeDeleted),
isNull(MachineTable.timeDeleted)
)
)
.then((rows) => (rows[0] ? serialize(rows[0].box) : null));
});
}
);
export const listByMachine = fn(Info.shape.machineId, async (machineId) => {
return Database.use(async (tx) => {
return tx
+55 -1
View File
@@ -1,8 +1,11 @@
import { and, count, inArray, isNull } from 'drizzle-orm';
import z from 'zod';
import { Database } from '../db/index.js';
import { Env } from '../env.js';
import { ErrorCodes, VisibleError } from '../error.js';
import { Machine } from '../machine/index.js';
import { BoxTier } from './box.sql.js';
import { BoxTable, BoxTier } from './box.sql.js';
/**
* Deciding which host a box runs on.
@@ -66,6 +69,57 @@ export namespace Placement {
return hosts[0]!.id;
};
/**
* Place it on the fleet: a machine the fleet organisation owns.
*
* Only machines that are online — a box placed on one that is not would be a
* session that never starts — and, among those, the one holding the fewest
* boxes. That is a spread, not a scheduler: it knows nothing about how big a
* box is or whether it is running. It is the smallest policy that does not
* pile every customer onto the oldest row, and this file is still the one
* place a real scheduler replaces. todo(d-0014)
*/
export const fleet: Placer = async () => {
const organisationId = Env.get().FLEET_ORGANISATION_ID;
if (!organisationId) {
throw new VisibleError(
'internal',
ErrorCodes.Server.SERVICE_UNAVAILABLE,
'Nestri GPUs are not available on this deployment'
);
}
const online = (await Machine.listByOrganisation(organisationId)).filter((m) =>
Machine.isOnline(m.lastSeen ?? null)
);
if (online.length === 0) {
// Capacity, not a fault: the same request succeeds once a machine is
// back, which is what a 429 tells a caller.
throw new VisibleError(
'rate_limit',
ErrorCodes.Server.SERVICE_UNAVAILABLE,
'No Nestri GPU is free right now. Try again in a few minutes'
);
}
const held = await Database.use((tx) =>
tx
.select({ machineId: BoxTable.machineId, boxes: count() })
.from(BoxTable)
.where(
and(
inArray(
BoxTable.machineId,
online.map((m) => m.id)
),
isNull(BoxTable.timeDeleted)
)
)
.groupBy(BoxTable.machineId)
);
const boxes = new Map(held.map((h) => [h.machineId, h.boxes]));
// Stable: on a tie, the order `listByOrganisation` gives, oldest first.
return [...online].sort((a, b) => (boxes.get(a.id) ?? 0) - (boxes.get(b.id) ?? 0))[0]!.id;
};
/** Place a box, using `onlyHost` unless a caller supplies its own placer. */
export async function choose(request: Request, placer: Placer = onlyHost): Promise<string> {
return placer(Request.parse(request));
+31
View File
@@ -1,6 +1,7 @@
import { Actor } from '../actor.js';
import { Identifier } from '../id.js';
import { Machine } from '../machine/index.js';
import { Organisation } from '../organisation/index.js';
import { Team } from '../team/index.js';
import { User } from '../user/index.js';
import { LinkedAccount } from '../user/linked-account.js';
@@ -72,4 +73,34 @@ export namespace Fixtures {
});
return registered.id;
}
/**
* A fleet: an organisation and `hosts` machines it owns outright, all online.
*
* A fleet machine still names a person who registered it (`ownerUserId` is
* not nullable), so `operator` is that person — the one who plugged it in,
* not the one who pays for it.
*/
export async function fleet(operator: Owner, hosts = 1) {
const organisationId = Identifier.ascending('organisation');
await Organisation.create({
id: organisationId,
name: 'Fleet',
slug: `fleet-${organisationId.slice(-10).toLowerCase()}`,
domain: `${organisationId.slice(-10).toLowerCase()}.example.test`
});
const machines: { id: string; secret: string }[] = [];
for (let i = 0; i < hosts; i++) {
const registered = await Machine.register({
id: Identifier.ascending('machine'),
ownerUserId: operator.userId,
teamId: null,
organisationId,
label: `fleet-${i}`
});
await Machine.touchLastSeen({ id: registered.id });
machines.push({ id: registered.id, secret: registered.secret });
}
return { organisationId, machines };
}
}
+7 -1
View File
@@ -63,7 +63,13 @@ export namespace Env {
RELEASES_ACCESS_KEY_ID: z.string().optional(),
RELEASES_SECRET_ACCESS_KEY: z.string().optional(),
DATABASE_URL: z.string().optional()
DATABASE_URL: z.string().optional(),
/**
* The organisation whose machines are rented to customers: the fleet.
* Unset, nothing is placed on rented hardware. Configured per deploy,
* never written into the repository.
*/
FLEET_ORGANISATION_ID: z.string().optional()
});
export type Info = z.infer<typeof Info>;