@marinoscar/platform-api 0.0.0-stage → 0.1.0-next.10

package/dist/nodes/nodes.controller.js

@@ -0,0 +1,616 @@
+"use strict";
+// =============================================================================
+// /api/nodes — the routes a worker node talks to (issues #268 & #269, epic #254)
+// =============================================================================
+//
+// Fourteen routes, four services, and a controller that binds, documents and
+// authorizes — nothing else. Every decision about what a request MEANS lives
+// in `nodes.service.ts` (the control plane), `node-data-plane.service.ts`
+// (#269's presigned IO), `node-secret-broker.service.ts` (#349) and
+// `node-telemetry.service.ts` (#608's span relay), including both guards;
+// this file must not grow a second opinion about ownership or about a lease,
+// because a check written here would be a check the services' own callers
+// (and their tests) do not get. The data plane's two routes go through the SAME
+// `assertJobHeldByNode` the control plane's do — reused, never reimplemented.
+//
+// -----------------------------------------------------------------------------
+// THIS IS THE MOUNT POINT THE `nod_` ALLOWLIST HAS BEEN POINTING AT SINCE #267
+// -----------------------------------------------------------------------------
+//
+// `JwtAuthGuard` admits a `nod_` credential on exactly `/api/nodes` and paths
+// beneath it, and refuses it everywhere else — including `/api/node-credentials`,
+// so a worker token can never mint another. Until this controller existed,
+// that allowlist pointed at nothing: a request to `/api/nodes` 404'd in the
+// router before the guard ran, which is why #267 could only assert the
+// admitted side by invoking the guard directly. These routes are what make
+// the boundary testable over real HTTP, and
+// `test/nodes/node-credential.integration.spec.ts` now does exactly that.
+//
+// ⚠ CONSEQUENCE WORTH KNOWING BEFORE ADDING A ROUTE HERE: everything mounted
+// under this controller is reachable by a node credential. That is the intended
+// blast radius (`docs/specs/worker-nodes.md`, "Route allowlist"), and it means
+// a route added here is a route an unattended, months-old credential on
+// somebody else's box can call. Anything that is not part of the node
+// conversation belongs on a different prefix.
+//
+// -----------------------------------------------------------------------------
+// PERMISSIONS, AND WHY THE READS ARE SPLIT FROM THE WRITES
+// -----------------------------------------------------------------------------
+//
+// Every write route is `nodes:write`; `GET /nodes`, `GET /nodes/:id` and
+// `GET /nodes/job-types` are `nodes:read`. Note that MINTING A SIGNED URL is a
+// write (`download-url` included): it hands out a capability against storage
+// and is scoped by a lease the node must be actively holding, which is not
+// the shape of anything a read-only auditor should be able to do.
+// The split is the same one `/api/node-credentials` makes and
+// exists for the same reason: a role that may AUDIT the fleet without being
+// able to change it is a distinction worth being able to express, and it is
+// the entire reason the permission pair is split at all. Note that claiming a
+// job is a WRITE — it takes rows and marks them running — even though a node
+// operator might think of "get me work" as a read.
+//
+// -----------------------------------------------------------------------------
+// ⚠ THE LITERALS ARE DECLARED BEFORE THE `:id` ROUTES, AND THE ORDER IS LOAD-BEARING
+// -----------------------------------------------------------------------------
+//
+// Nest matches in DECLARATION ORDER, not by specificity. `POST /nodes/register`
+// is one segment, exactly like a `POST /nodes/:id` would be, so the day
+// somebody adds one — an "update this node" route is the obvious candidate —
+// a `register` declared after it becomes unreachable, and the symptom is a
+// fleet-wide "node not found: register" with a UUID validation error rather
+// than anything naming this file. Literals first removes the trap in advance.
+//
+// `GET /nodes/job-types` (#269) is the live case, not a hypothetical one:
+// `GET /nodes/:id` ALREADY EXISTS, so declaring `job-types` after it would
+// route every request for the contract list into the node lookup, where
+// `ParseUUIDPipe` would answer `400 "Validation failed (uuid is expected)"`
+// for a path that has nothing to do with a UUID. It is declared immediately
+// after `register`, above every parameterised route.
+//
+// -----------------------------------------------------------------------------
+// WHY `register` RETURNS 200 AND NOT 201
+// -----------------------------------------------------------------------------
+//
+// It creates a row roughly half the time and refreshes an existing one the
+// rest — a restarted container reattaches, which is the normal case in a
+// steady fleet. Returning 201 for one and 200 for the other would make every
+// client branch on a status code to learn something the body already says
+// (`reattached`), and would publish "a node was created" as the meaning of a
+// status code on an endpoint whose whole design goal is that restarting a
+// container creates nothing. One status, one shape, one field to read.
+// =============================================================================
+var __decorate = (this && this.__decorate) || function (decorators, target, key, desc) {
+    var c = arguments.length, r = c < 3 ? target : desc === null ? desc = Object.getOwnPropertyDescriptor(target, key) : desc, d;
+    if (typeof Reflect === "object" && typeof Reflect.decorate === "function") r = Reflect.decorate(decorators, target, key, desc);
+    else for (var i = decorators.length - 1; i >= 0; i--) if (d = decorators[i]) r = (c < 3 ? d(r) : c > 3 ? d(target, key, r) : d(target, key)) || r;
+    return c > 3 && r && Object.defineProperty(target, key, r), r;
+};
+var __metadata = (this && this.__metadata) || function (k, v) {
+    if (typeof Reflect === "object" && typeof Reflect.metadata === "function") return Reflect.metadata(k, v);
+};
+var __param = (this && this.__param) || function (paramIndex, decorator) {
+    return function (target, key) { decorator(target, key, paramIndex); }
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.NodesController = void 0;
+const common_1 = require("@nestjs/common");
+const swagger_1 = require("@nestjs/swagger");
+const index_1 = require("../identity/index");
+const nodes_constants_1 = require("./nodes.constants");
+const node_control_plane_dto_1 = require("./dto/node-control-plane.dto");
+const node_response_dto_1 = require("./dto/node-response.dto");
+const node_data_plane_dto_1 = require("./dto/node-data-plane.dto");
+const node_job_secret_dto_1 = require("./dto/node-job-secret.dto");
+const node_telemetry_dto_1 = require("./dto/node-telemetry.dto");
+const node_data_plane_service_1 = require("./node-data-plane.service");
+const node_secret_broker_service_1 = require("./node-secret-broker.service");
+const node_telemetry_service_1 = require("./node-telemetry.service");
+const nodes_service_1 = require("./nodes.service");
+let NodesController = class NodesController {
+    nodes;
+    dataPlane;
+    secrets;
+    telemetry;
+    constructor(nodes, dataPlane, secrets, telemetry) {
+        this.nodes = nodes;
+        this.dataPlane = dataPlane;
+        this.secrets = secrets;
+        this.telemetry = telemetry;
+    }
+    // ---------------------------------------------------------------------------
+    // Literal routes first — see the header.
+    // ---------------------------------------------------------------------------
+    async register(dto, userId) {
+        const { node, reattached } = await this.nodes.register(userId, dto);
+        return { node: (0, node_response_dto_1.toWorkerNodeDto)(node), reattached };
+    }
+    async listJobTypes() {
+        // ASYNC SINCE #349: the list is intersected with this deployment's
+        // `nodes.jobSecretBrokerEnabled` setting, so a type that needs a per-job
+        // credential does not appear where the deployment does not issue them.
+        return { types: await this.nodes.listNodeEligibleJobTypes() };
+    }
+    async list(userId) {
+        const nodes = await this.nodes.listNodes(userId);
+        return nodes.map(node_response_dto_1.toWorkerNodeDto);
+    }
+    async get(id, userId) {
+        return (0, node_response_dto_1.toWorkerNodeDto)(await this.nodes.getNode(userId, id));
+    }
+    // ---------------------------------------------------------------------------
+    // The node's own lifecycle
+    // ---------------------------------------------------------------------------
+    async deregister(id, userId) {
+        return (0, node_response_dto_1.toWorkerNodeDto)(await this.nodes.deregister(userId, id));
+    }
+    async heartbeat(id, dto, userId) {
+        return (0, node_response_dto_1.toWorkerNodeDto)(await this.nodes.heartbeat(userId, id, dto));
+    }
+    // ---------------------------------------------------------------------------
+    // The work itself
+    // ---------------------------------------------------------------------------
+    async claim(id, dto, userId) {
+        const jobs = await this.nodes.claimJobs(userId, id, dto);
+        // The renewal cadence is resolved PER JOB, not once per batch: a node
+        // claims across several types in one call (#346), and with per-type
+        // runtime ceilings those rows no longer share a lease — so they no longer
+        // share a renewal interval either.
+        return {
+            jobs: jobs.map((job) => (0, node_response_dto_1.toNodeJobAssignment)(job, this.nodes.renewIntervalMsFor(job.type))),
+        };
+    }
+    async renew(id, jobId, dto, userId) {
+        // `dto.claimToken` is `undefined` for every node that has not learned to
+        // send it — including one posting no body at all, which is what every
+        // node did before #364 and what `renewLeaseSchema`'s `.default({})` keeps
+        // working. The service treats absent as "identify me by node id alone".
+        const renewed = await this.nodes.renewLease(userId, id, jobId, dto.claimToken);
+        return { jobId: renewed.jobId, leaseExpiresAt: renewed.leaseExpiresAt.toISOString() };
+    }
+    // ---------------------------------------------------------------------------
+    // The data plane (#269) — bytes move between the node and the storage
+    // provider DIRECTLY. Neither route carries a payload, and no storage
+    // credential ever leaves this server.
+    // ---------------------------------------------------------------------------
+    async downloadUrl(id, jobId, dto, userId) {
+        return this.dataPlane.createDownloadUrl(userId, id, jobId, dto);
+    }
+    async uploadUrl(id, jobId, dto, userId) {
+        return this.dataPlane.createUploadTarget(userId, id, jobId, dto);
+    }
+    // ---------------------------------------------------------------------------
+    // The secret broker (#349, epic #345) — the ONE credential a job may need,
+    // bounded by the lease the node is already renewing, revoked on settlement.
+    //
+    // ⚠ NO AUTH-GUARD CHANGE WAS REQUIRED, AND THAT IS WORTH VERIFYING RATHER
+    // THAN ASSUMING. `JwtAuthGuard` admits a `nod_` credential on `/api/nodes`
+    // and every path beneath it (see this file's header and #267), so this route
+    // — mounted on the same controller, under the same prefix — is inside that
+    // allowlist by construction. Nothing about the allowlist was touched, and
+    // nothing should be: the moment a credential route needed a new prefix
+    // admitted, the blast radius of a leaked worker token would have grown.
+    // `nodes:write`, like every other mint on this controller, for the reason the
+    // header gives about `download-url`: handing out a capability scoped by a
+    // live lease is not the shape of anything a read-only auditor should do.
+    // ---------------------------------------------------------------------------
+    async issueSecret(id, jobId, dto, userId) {
+        return this.secrets.issueForJob(userId, id, jobId, dto);
+    }
+    async submitResult(id, jobId, dto, userId) {
+        return this.nodes.submitResult(userId, id, jobId, dto);
+    }
+    async reportFailure(id, jobId, dto, userId) {
+        return this.nodes.reportFailure(userId, id, jobId, dto);
+    }
+    // ---------------------------------------------------------------------------
+    // The span relay (#608) — a node's phase spans, re-emitted by this server.
+    //
+    // Under the same `nod_` prefix allowlist as every route here, by
+    // construction: nothing in `jwt-auth.guard.ts` changed. `nodes:write`, like
+    // every other node-originated write on this controller — it writes into the
+    // deployment's trace store.
+    // ---------------------------------------------------------------------------
+    async relayTelemetry(id, dto, userId) {
+        return this.telemetry.relay(userId, id, dto);
+    }
+};
+exports.NodesController = NodesController;
+__decorate([
+    (0, common_1.Post)('register'),
+    (0, index_1.Auth)({ permissions: [nodes_constants_1.PERMISSIONS.NODES_WRITE] }),
+    (0, common_1.HttpCode)(common_1.HttpStatus.OK),
+    (0, swagger_1.ApiOperation)({
+        summary: 'Register a worker node, or reattach to an existing one',
+        description: 'Idempotent on `(owner, name)`: registering a name this owner already used REATTACHES ' +
+            'to that node — refreshing its hostname, platform, CLI version, eligible types and ' +
+            'concurrency, and bringing it back online — rather than creating a second row. That is ' +
+            'what lets a container be recreated without leaking a node on every restart. `reattached` ' +
+            'in the response says which happened. If the existing row is still heartbeating the server ' +
+            'warns and proceeds (last writer wins); if an operator has DISABLED the node, that status ' +
+            'survives the re-registration and the node still may not claim.',
+    }),
+    (0, swagger_1.ApiResponse)({ status: 200, description: 'Registered or reattached', type: node_response_dto_1.RegisterNodeResponseDto }),
+    (0, swagger_1.ApiResponse)({ status: 400, description: 'Validation error' }),
+    __param(0, (0, common_1.Body)()),
+    __param(1, (0, index_1.CurrentUser)('id')),
+    __metadata("design:type", Function),
+    __metadata("design:paramtypes", [node_control_plane_dto_1.RegisterNodeDto, String]),
+    __metadata("design:returntype", Promise)
+], NodesController.prototype, "register", null);
+__decorate([
+    (0, common_1.Get)('job-types'),
+    (0, index_1.Auth)({ permissions: [nodes_constants_1.PERMISSIONS.NODES_READ] }),
+    (0, swagger_1.ApiOperation)({
+        summary: 'List the job types a node can run, with their result contracts',
+        description: 'Every type whose handler carries both `nodeResultSchema` and `persistNodeResult` — the ' +
+            'only types a claim can ever return — each with a JSON Schema (2020-12) for the `result` ' +
+            'a submission must carry. The schema is generated from the server’s own Zod definition, ' +
+            'so a client validates against what this server will actually enforce rather than ' +
+            'against a copy that can go stale. `resultSchema` is `null` for the rare type whose ' +
+            'schema has no JSON Schema representation; submit and let the server validate. ' +
+            'The list is derived from the handler registry, so a fork’s own types appear with no ' +
+            'list to edit.',
+    }),
+    (0, swagger_1.ApiResponse)({ status: 200, description: 'The node-eligible types', type: node_data_plane_dto_1.NodeJobTypesResponseDto }),
+    __metadata("design:type", Function),
+    __metadata("design:paramtypes", []),
+    __metadata("design:returntype", Promise)
+], NodesController.prototype, "listJobTypes", null);
+__decorate([
+    (0, common_1.Get)(),
+    (0, index_1.Auth)({ permissions: [nodes_constants_1.PERMISSIONS.NODES_READ] }),
+    (0, swagger_1.ApiOperation)({
+        summary: "List the caller's worker nodes",
+        description: 'Fleet inventory for the calling owner: what is registered, what each node says it can ' +
+            'run, and when each was last heard from. `status` is operator state, not liveness — a node ' +
+            'can read `online` and be silently dead; compare `lastHeartbeatAt` to answer that.',
+    }),
+    (0, swagger_1.ApiResponse)({ status: 200, description: 'The nodes this user registered', type: [node_response_dto_1.WorkerNodeDto] }),
+    __param(0, (0, index_1.CurrentUser)('id')),
+    __metadata("design:type", Function),
+    __metadata("design:paramtypes", [String]),
+    __metadata("design:returntype", Promise)
+], NodesController.prototype, "list", null);
+__decorate([
+    (0, common_1.Get)(':id'),
+    (0, index_1.Auth)({ permissions: [nodes_constants_1.PERMISSIONS.NODES_READ] }),
+    (0, swagger_1.ApiOperation)({
+        summary: 'Get one worker node',
+        description: 'Returns the node when it belongs to the caller. A node that does not exist is `404`; ' +
+            'one that belongs to somebody else is `403` — deliberately distinguishable, because a ' +
+            'node id is not a secret and an operator holding the wrong id needs to be told the truth ' +
+            'rather than sent off to re-register.',
+    }),
+    (0, swagger_1.ApiParam)({ name: 'id', type: String, format: 'uuid' }),
+    (0, swagger_1.ApiResponse)({ status: 200, description: 'The node', type: node_response_dto_1.WorkerNodeDto }),
+    (0, swagger_1.ApiResponse)({ status: 404, description: 'No such node' }),
+    __param(0, (0, common_1.Param)('id', common_1.ParseUUIDPipe)),
+    __param(1, (0, index_1.CurrentUser)('id')),
+    __metadata("design:type", Function),
+    __metadata("design:paramtypes", [String, String]),
+    __metadata("design:returntype", Promise)
+], NodesController.prototype, "get", null);
+__decorate([
+    (0, common_1.Post)(':id/deregister'),
+    (0, index_1.Auth)({ permissions: [nodes_constants_1.PERMISSIONS.NODES_WRITE] }),
+    (0, common_1.HttpCode)(common_1.HttpStatus.OK),
+    (0, swagger_1.ApiOperation)({
+        summary: 'Deregister a worker node (graceful shutdown)',
+        description: 'Marks the node `offline`. It deliberately does NOT requeue the jobs the node is ' +
+            'holding: nothing proves a shutting-down process has actually stopped working, and ' +
+            'requeueing on the node’s say-so would hand a still-running job to a second executor. ' +
+            'Held jobs return through the lease reaper once their leases expire — the same path a ' +
+            'crashed node takes.',
+    }),
+    (0, swagger_1.ApiParam)({ name: 'id', type: String, format: 'uuid' }),
+    (0, swagger_1.ApiResponse)({ status: 200, description: 'The node, now offline', type: node_response_dto_1.WorkerNodeDto }),
+    __param(0, (0, common_1.Param)('id', common_1.ParseUUIDPipe)),
+    __param(1, (0, index_1.CurrentUser)('id')),
+    __metadata("design:type", Function),
+    __metadata("design:paramtypes", [String, String]),
+    __metadata("design:returntype", Promise)
+], NodesController.prototype, "deregister", null);
+__decorate([
+    (0, common_1.Post)(':id/heartbeat'),
+    (0, index_1.Auth)({ permissions: [nodes_constants_1.PERMISSIONS.NODES_WRITE] }),
+    (0, common_1.HttpCode)(common_1.HttpStatus.OK),
+    (0, swagger_1.ApiOperation)({
+        summary: 'Report liveness, and optionally refresh capabilities or concurrency',
+        description: 'Stamps `lastHeartbeatAt` and applies whatever the node reports about itself. A new ' +
+            '`concurrency` takes effect on the very NEXT claim — the claim endpoint reads the row ' +
+            'live rather than caching a value from registration. A node may report only `online` or ' +
+            '`offline`: `draining` and `disabled` are operator decisions, and a heartbeat can never ' +
+            'clear either of them. An optional `vitals` snapshot (strict, bounded, self-reported) ' +
+            'replaces the stored `lastVitals` and stamps `lastVitalsAt`; omitting it leaves both ' +
+            'untouched. An unknown or out-of-range vital is a 400 for the whole heartbeat.',
+    }),
+    (0, swagger_1.ApiParam)({ name: 'id', type: String, format: 'uuid' }),
+    (0, swagger_1.ApiResponse)({ status: 200, description: 'The refreshed node', type: node_response_dto_1.WorkerNodeDto }),
+    (0, swagger_1.ApiResponse)({ status: 400, description: 'The body failed validation (including `vitals`)' }),
+    __param(0, (0, common_1.Param)('id', common_1.ParseUUIDPipe)),
+    __param(1, (0, common_1.Body)()),
+    __param(2, (0, index_1.CurrentUser)('id')),
+    __metadata("design:type", Function),
+    __metadata("design:paramtypes", [String, node_control_plane_dto_1.HeartbeatNodeDto, String]),
+    __metadata("design:returntype", Promise)
+], NodesController.prototype, "heartbeat", null);
+__decorate([
+    (0, common_1.Post)(':id/claim'),
+    (0, index_1.Auth)({ permissions: [nodes_constants_1.PERMISSIONS.NODES_WRITE] }),
+    (0, common_1.HttpCode)(common_1.HttpStatus.OK),
+    (0, swagger_1.ApiOperation)({
+        summary: 'Claim runnable jobs for this node',
+        description: 'Takes up to the node’s declared `concurrency` runnable jobs and marks them running ' +
+            'under a server-derived lease, through the same atomic claim the in-process worker uses — ' +
+            'so a node and the server never receive the same row. Requested `types` are INTERSECTED ' +
+            'with the node’s registered `eligibleTypes` (a node may narrow, never widen) and with the ' +
+            'types this server could actually store a node-computed result for. `limit` is clamped ' +
+            'down to the node’s live concurrency. A `draining` node gets an empty list; a `disabled` ' +
+            'one gets `403`. An empty list is the common, non-error answer.',
+    }),
+    (0, swagger_1.ApiParam)({ name: 'id', type: String, format: 'uuid' }),
+    (0, swagger_1.ApiResponse)({ status: 200, description: 'The claimed jobs and their inputs', type: node_response_dto_1.ClaimJobsResponseDto }),
+    (0, swagger_1.ApiResponse)({ status: 403, description: 'This node is disabled, or belongs to another user' }),
+    __param(0, (0, common_1.Param)('id', common_1.ParseUUIDPipe)),
+    __param(1, (0, common_1.Body)()),
+    __param(2, (0, index_1.CurrentUser)('id')),
+    __metadata("design:type", Function),
+    __metadata("design:paramtypes", [String, node_control_plane_dto_1.ClaimJobsDto, String]),
+    __metadata("design:returntype", Promise)
+], NodesController.prototype, "claim", null);
+__decorate([
+    (0, common_1.Post)(':id/jobs/:jobId/renew'),
+    (0, index_1.Auth)({ permissions: [nodes_constants_1.PERMISSIONS.NODES_WRITE] }),
+    (0, common_1.HttpCode)(common_1.HttpStatus.OK),
+    (0, swagger_1.ApiOperation)({
+        summary: 'Extend the lease on a held job',
+        description: 'Pushes the job’s lease out by the server’s lease interval so the reaper does not requeue ' +
+            'work that is still running. The lease length is derived from the server’s job timeout and ' +
+            'is not negotiable: a node that could choose its own lease could park every row it claimed. ' +
+            'Refused with `409` once the lease has already expired — by then another executor may own ' +
+            'the job, and renewing would keep the reaper away from a run that is no longer this node’s. ' +
+            'Quote the assignment’s `claimToken` in the body to be identified as THIS claim rather ' +
+            'than merely as this node, which is what stops a stalled-and-re-claimed node extending ' +
+            'its own newer run’s lease. The body, and the field, are optional: omitting them is the ' +
+            'older behaviour and is never an error.',
+    }),
+    (0, swagger_1.ApiParam)({ name: 'id', type: String, format: 'uuid' }),
+    (0, swagger_1.ApiParam)({ name: 'jobId', type: String, format: 'uuid' })
+    // `required: false` because it genuinely is: every node built before #364
+    // posts to this route with no body and no `Content-Type`, and the published
+    // spec has to say that is legal or a generated client will start demanding
+    // one. Nest marks a `@Body()` required by default, so this is stated here.
+    ,
+    (0, swagger_1.ApiBody)({ type: node_control_plane_dto_1.RenewLeaseDto, required: false }),
+    (0, swagger_1.ApiResponse)({ status: 200, description: 'The new lease expiry', type: node_response_dto_1.RenewLeaseResponseDto }),
+    (0, swagger_1.ApiResponse)({ status: 409, description: 'This node no longer holds the job with a live lease' }),
+    __param(0, (0, common_1.Param)('id', common_1.ParseUUIDPipe)),
+    __param(1, (0, common_1.Param)('jobId', common_1.ParseUUIDPipe)),
+    __param(2, (0, common_1.Body)()),
+    __param(3, (0, index_1.CurrentUser)('id')),
+    __metadata("design:type", Function),
+    __metadata("design:paramtypes", [String, String, node_control_plane_dto_1.RenewLeaseDto, String]),
+    __metadata("design:returntype", Promise)
+], NodesController.prototype, "renew", null);
+__decorate([
+    (0, common_1.Post)(':id/jobs/:jobId/download-url'),
+    (0, index_1.Auth)({ permissions: [nodes_constants_1.PERMISSIONS.NODES_WRITE] }),
+    (0, common_1.HttpCode)(common_1.HttpStatus.OK),
+    (0, swagger_1.ApiOperation)({
+        summary: 'Mint a short-lived signed GET for a held job’s input object',
+        description: 'Returns a signed URL for the storage object this job names as its subject. Fetch it ' +
+            'DIRECTLY from the storage provider: the bytes never pass through this API, and a node ' +
+            'never receives a storage credential. The expiry is bounded by the server and is not ' +
+            'negotiable — ask again if a transfer needs longer, which is cheap while the lease is ' +
+            'live. Treat the URL as a secret and do not log it. `409` once the lease has expired ' +
+            '(another executor may own the job — drop the work); `422` when the job names no ' +
+            'resolvable input, which is permanent: report the job as FAILED rather than retrying, ' +
+            'and `details.reason` says which of `missing_subject_id`, `input_object_not_found` or ' +
+            '`input_object_has_no_storage_key` applied. Quote the assignment’s `claimToken` to be ' +
+            'identified as THIS claim rather than merely as this node; the body, and the field, are ' +
+            'optional and omitting them is the older behaviour.',
+    }),
+    (0, swagger_1.ApiParam)({ name: 'id', type: String, format: 'uuid' }),
+    (0, swagger_1.ApiParam)({ name: 'jobId', type: String, format: 'uuid' })
+    // `required: false` for the reason the renew route states: this endpoint
+    // took no body at all until #364, and every node built before it posts here
+    // with none.
+    ,
+    (0, swagger_1.ApiBody)({ type: node_data_plane_dto_1.NodeDownloadUrlDto, required: false }),
+    (0, swagger_1.ApiResponse)({ status: 200, description: 'A signed download URL', type: node_data_plane_dto_1.NodeDownloadUrlResponseDto }),
+    (0, swagger_1.ApiResponse)({ status: 409, description: 'This node no longer holds the job with a live lease' }),
+    (0, swagger_1.ApiResponse)({ status: 422, description: 'The job names no resolvable input object' }),
+    __param(0, (0, common_1.Param)('id', common_1.ParseUUIDPipe)),
+    __param(1, (0, common_1.Param)('jobId', common_1.ParseUUIDPipe)),
+    __param(2, (0, common_1.Body)()),
+    __param(3, (0, index_1.CurrentUser)('id')),
+    __metadata("design:type", Function),
+    __metadata("design:paramtypes", [String, String, node_data_plane_dto_1.NodeDownloadUrlDto, String]),
+    __metadata("design:returntype", Promise)
+], NodesController.prototype, "downloadUrl", null);
+__decorate([
+    (0, common_1.Post)(':id/jobs/:jobId/upload-url'),
+    (0, index_1.Auth)({ permissions: [nodes_constants_1.PERMISSIONS.NODES_WRITE] }),
+    (0, common_1.HttpCode)(common_1.HttpStatus.OK),
+    (0, swagger_1.ApiOperation)({
+        summary: 'Mint a short-lived signed PUT for a held job’s output',
+        description: 'Returns a signed URL accepting ONE `PUT` of a whole object, plus the storage key the ' +
+            'SERVER chose for it. A node may not choose its own key — a signed PUT is an ' +
+            'unconditional overwrite of exactly that key, so a node-supplied one would be a write ' +
+            'primitive over the whole bucket — and a request carrying `key` (or any field other ' +
+            'than `contentType`) is refused with `400` naming it. The key is returned so the node ' +
+            'can report it in its result; no `storage_objects` row is created here. If ' +
+            '`contentType` is supplied it becomes part of the signature and must be sent verbatim ' +
+            'on the PUT. `409` once the lease has expired — or, when the assignment’s `claimToken` ' +
+            'is quoted, once this is no longer the claim the job carries: with a type that derives ' +
+            'its own output key, a stale worker slot would otherwise be signed for the very key its ' +
+            'node’s newer claim is writing. The token is optional; omitting it is the older behaviour.',
+    }),
+    (0, swagger_1.ApiParam)({ name: 'id', type: String, format: 'uuid' }),
+    (0, swagger_1.ApiParam)({ name: 'jobId', type: String, format: 'uuid' })
+    // `required: false` states something that was already true rather than
+    // changing anything: `nodeUploadUrlSchema` has defaulted an absent body to
+    // `{}` since #269, and nodes do send none. The two routes that grew a body
+    // in #364 say it too, so the spec is consistent about which node-facing
+    // bodies may be omitted.
+    ,
+    (0, swagger_1.ApiBody)({ type: node_data_plane_dto_1.NodeUploadUrlDto, required: false }),
+    (0, swagger_1.ApiResponse)({ status: 200, description: 'A signed upload URL and its server-chosen key', type: node_data_plane_dto_1.NodeUploadUrlResponseDto }),
+    (0, swagger_1.ApiResponse)({ status: 400, description: 'The request carried a field a node may not set (e.g. `key`)' }),
+    (0, swagger_1.ApiResponse)({ status: 409, description: 'This node no longer holds the job with a live lease' }),
+    __param(0, (0, common_1.Param)('id', common_1.ParseUUIDPipe)),
+    __param(1, (0, common_1.Param)('jobId', common_1.ParseUUIDPipe)),
+    __param(2, (0, common_1.Body)()),
+    __param(3, (0, index_1.CurrentUser)('id')),
+    __metadata("design:type", Function),
+    __metadata("design:paramtypes", [String, String, node_data_plane_dto_1.NodeUploadUrlDto, String]),
+    __metadata("design:returntype", Promise)
+], NodesController.prototype, "uploadUrl", null);
+__decorate([
+    (0, common_1.Post)(':id/jobs/:jobId/secret'),
+    (0, index_1.Auth)({ permissions: [nodes_constants_1.PERMISSIONS.NODES_WRITE] }),
+    (0, common_1.HttpCode)(common_1.HttpStatus.OK)
+    // Belt and braces over `POST` already being uncacheable. What comes back is
+    // not a scoped URL but a credential, and an intermediary that decided to be
+    // clever is one nobody would find out about.
+    ,
+    (0, common_1.Header)('Cache-Control', 'no-store'),
+    (0, swagger_1.ApiOperation)({
+        summary: 'Obtain the short-lived credential for a held job',
+        description: 'Returns the ONE credential this job’s type declares it needs, valid no longer than ' +
+            'this job’s LEASE — the node is already renewing that lease, and the server does not ' +
+            'mint a second clock. ⚠ HOLD IT IN MEMORY ONLY: it is returned once, it is revoked ' +
+            'when the job settles, and a node must never write it to disk, to an environment ' +
+            'variable, or to a log. Re-callable while the lease is live — the same grant is ' +
+            'extended, never a second one issued. Send an EMPTY BODY, or one carrying only this ' +
+            'assignment’s `claimToken`: any other field is refused with `400`, because a node may ' +
+            'not request a secret it was not assigned — the token requests nothing, it only proves ' +
+            'WHICH claim is asking, so a stale worker slot is not handed a live credential bounded ' +
+            'by a lease belonging to its own later claim. `403` (with ' +
+            '`details.reason`) when this deployment does not issue per-job credentials at all; ' +
+            '`404` when this job’s type declares no broker, which will not change on a retry; ' +
+            '`409` once the lease has expired — drop the work; `503` when the broker exists but ' +
+            'cannot mint right now, carrying the operator-facing `remedy` in `details`.',
+    }),
+    (0, swagger_1.ApiParam)({ name: 'id', type: String, format: 'uuid' }),
+    (0, swagger_1.ApiParam)({ name: 'jobId', type: String, format: 'uuid' })
+    // `required: false` for the same reason the upload route states it: an empty
+    // body has always been legal here, and is still the whole request for a node
+    // that quotes no token.
+    ,
+    (0, swagger_1.ApiBody)({ type: node_job_secret_dto_1.NodeJobSecretRequestDto, required: false }),
+    (0, swagger_1.ApiResponse)({ status: 200, description: 'The credential, returned once', type: node_job_secret_dto_1.NodeJobSecretResponseDto }),
+    (0, swagger_1.ApiResponse)({ status: 400, description: 'The request body carried a field a node may not set' }),
+    (0, swagger_1.ApiResponse)({ status: 403, description: 'This deployment does not issue per-job credentials' }),
+    (0, swagger_1.ApiResponse)({ status: 404, description: 'This job’s type declares no secret broker' }),
+    (0, swagger_1.ApiResponse)({ status: 409, description: 'This node no longer holds the job with a live lease' }),
+    (0, swagger_1.ApiResponse)({ status: 503, description: 'The broker cannot mint a credential in this deployment' }),
+    __param(0, (0, common_1.Param)('id', common_1.ParseUUIDPipe)),
+    __param(1, (0, common_1.Param)('jobId', common_1.ParseUUIDPipe)),
+    __param(2, (0, common_1.Body)()),
+    __param(3, (0, index_1.CurrentUser)('id')),
+    __metadata("design:type", Function),
+    __metadata("design:paramtypes", [String, String, node_job_secret_dto_1.NodeJobSecretRequestDto, String]),
+    __metadata("design:returntype", Promise)
+], NodesController.prototype, "issueSecret", null);
+__decorate([
+    (0, common_1.Post)(':id/jobs/:jobId/result'),
+    (0, index_1.Auth)({ permissions: [nodes_constants_1.PERMISSIONS.NODES_WRITE] }),
+    (0, common_1.HttpCode)(common_1.HttpStatus.OK),
+    (0, swagger_1.ApiOperation)({
+        summary: 'Submit a computed result for a held job',
+        description: 'The server validates the result against the handler’s `nodeResultSchema`, persists it ' +
+            'through `persistNodeResult`, and settles the job — the node never writes to the database. ' +
+            '`400` if the declared `type` does not match the job, if the type is not node-persistable, ' +
+            'or if the result fails validation (the issues are in `details`); `409` if the lease has ' +
+            'expired, in which case nothing is persisted and the node should drop the work — also ' +
+            'returned when the claim is lost mid-settle (the job was reaped or re-claimed after the ' +
+            'lease check), in which case the settle is refused, the job is left to its current holder, ' +
+            'and the node should equally drop the work; `500` if persisting threw, in which case the ' +
+            'server has ALREADY settled the job through its normal failure path and the node must not ' +
+            'resubmit. Quote the assignment’s `claimToken` so a ' +
+            'stale worker slot cannot persist its result over a newer claim of the same job; the ' +
+            'field is optional and omitting it is the older, node-id-only behaviour.',
+    }),
+    (0, swagger_1.ApiParam)({ name: 'id', type: String, format: 'uuid' }),
+    (0, swagger_1.ApiParam)({ name: 'jobId', type: String, format: 'uuid' }),
+    (0, swagger_1.ApiResponse)({ status: 200, description: 'The job was settled', type: node_response_dto_1.JobSettlementResponseDto }),
+    (0, swagger_1.ApiResponse)({ status: 400, description: 'Wrong type, not node-persistable, or invalid result' }),
+    (0, swagger_1.ApiResponse)({ status: 409, description: 'This node no longer holds the job with a live lease' }),
+    __param(0, (0, common_1.Param)('id', common_1.ParseUUIDPipe)),
+    __param(1, (0, common_1.Param)('jobId', common_1.ParseUUIDPipe)),
+    __param(2, (0, common_1.Body)()),
+    __param(3, (0, index_1.CurrentUser)('id')),
+    __metadata("design:type", Function),
+    __metadata("design:paramtypes", [String, String, node_control_plane_dto_1.NodeJobResultDto, String]),
+    __metadata("design:returntype", Promise)
+], NodesController.prototype, "submitResult", null);
+__decorate([
+    (0, common_1.Post)(':id/jobs/:jobId/failure'),
+    (0, index_1.Auth)({ permissions: [nodes_constants_1.PERMISSIONS.NODES_WRITE] }),
+    (0, common_1.HttpCode)(common_1.HttpStatus.OK),
+    (0, swagger_1.ApiOperation)({
+        summary: 'Report that a held job failed',
+        description: 'The failure goes through the same terminal state machine an in-process handler’s throw ' +
+            'does: `rateLimited` is treated exactly as a thrown rate-limit error (it defers rather ' +
+            'than charging an attempt, and it backs off sibling jobs on this server too), and ' +
+            '`retryAfterMs` is a floor on the backoff. `willRetry` in the REQUEST is advisory and is ' +
+            'not acted on — the server’s attempt budget decides, and `willRetry` in the RESPONSE is ' +
+            'that decision. `409` if the node no longer holds the job — including when the claim is ' +
+            'lost mid-settle (reaped or re-claimed after the lease check), in which case nothing is ' +
+            'recorded and the node should drop the work. Quote the assignment’s `claimToken` so a ' +
+            'stale worker slot cannot settle a job a newer claim is still running; the field is ' +
+            'optional and omitting it is the older, node-id-only behaviour.',
+    }),
+    (0, swagger_1.ApiParam)({ name: 'id', type: String, format: 'uuid' }),
+    (0, swagger_1.ApiParam)({ name: 'jobId', type: String, format: 'uuid' }),
+    (0, swagger_1.ApiResponse)({ status: 200, description: 'The job was settled', type: node_response_dto_1.JobSettlementResponseDto }),
+    (0, swagger_1.ApiResponse)({ status: 409, description: 'This node no longer holds the job with a live lease' }),
+    __param(0, (0, common_1.Param)('id', common_1.ParseUUIDPipe)),
+    __param(1, (0, common_1.Param)('jobId', common_1.ParseUUIDPipe)),
+    __param(2, (0, common_1.Body)()),
+    __param(3, (0, index_1.CurrentUser)('id')),
+    __metadata("design:type", Function),
+    __metadata("design:paramtypes", [String, String, node_control_plane_dto_1.NodeJobFailureDto, String]),
+    __metadata("design:returntype", Promise)
+], NodesController.prototype, "reportFailure", null);
+__decorate([
+    (0, common_1.Post)(':id/telemetry'),
+    (0, index_1.Auth)({ permissions: [nodes_constants_1.PERMISSIONS.NODES_WRITE] }),
+    (0, common_1.HttpCode)(common_1.HttpStatus.OK),
+    (0, swagger_1.ApiOperation)({
+        summary: 'Relay a node’s job phase spans into the server’s traces',
+        description: 'A node reports the phases of jobs it ran (`job.download`, `job.execute`, `job.upload`, ' +
+            '`job.submit`, `job.secret`) and the server re-emits each as an OpenTelemetry span, ' +
+            'parented on the span that enqueued the job, with `node.id`/`node.name` taken from the ' +
+            'PATH and the node row — never from the body. The body is strict and bounded: at most ' +
+            '50 spans, an enum of phase names, integer-only allowlisted attributes, an ' +
+            'identifier-shaped `errorType` (never a message), and times no older than 24 hours nor ' +
+            'ending more than 5 minutes in the future; anything else is `400`. A span whose job is ' +
+            'neither held by this node nor settled by it within the last 10 minutes is DROPPED and ' +
+            'counted in `dropped`, never accepted. `429` when this node exceeds its relay budget ' +
+            '(per node: 60 requests and 1000 spans a minute); drop the batch. Best-effort by design: ' +
+            'a node must never delay or fail a job over this call.',
+    }),
+    (0, swagger_1.ApiParam)({ name: 'id', type: String, format: 'uuid' }),
+    (0, swagger_1.ApiResponse)({ status: 200, description: 'How many spans were accepted and dropped', type: node_telemetry_dto_1.NodeTelemetryResponseDto }),
+    (0, swagger_1.ApiResponse)({ status: 400, description: 'The body failed validation' }),
+    (0, swagger_1.ApiResponse)({ status: 403, description: 'This node belongs to another user' }),
+    (0, swagger_1.ApiResponse)({ status: 404, description: 'No such node' }),
+    (0, swagger_1.ApiResponse)({ status: 429, description: 'This node exceeded its span relay budget' }),
+    __param(0, (0, common_1.Param)('id', common_1.ParseUUIDPipe)),
+    __param(1, (0, common_1.Body)()),
+    __param(2, (0, index_1.CurrentUser)('id')),
+    __metadata("design:type", Function),
+    __metadata("design:paramtypes", [String, node_telemetry_dto_1.NodeTelemetryDto, String]),
+    __metadata("design:returntype", Promise)
+], NodesController.prototype, "relayTelemetry", null);
+exports.NodesController = NodesController = __decorate([
+    (0, swagger_1.ApiTags)('Worker Nodes'),
+    (0, common_1.Controller)('nodes'),
+    __metadata("design:paramtypes", [nodes_service_1.NodesService,
+        node_data_plane_service_1.NodeDataPlaneService,
+        node_secret_broker_service_1.NodeSecretBrokerService,
+        node_telemetry_service_1.NodeTelemetryService])
+], NodesController);
+//# sourceMappingURL=nodes.controller.js.map