Skip to content

fix(openapi): register each internal job once, with the status its handler returns (#9706) #9759

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
JSONbored merged 1 commit into from
Jul 29, 2026
+208 −153
Merged

fix(openapi): register each internal job once, with the status its handler returns (#9706) #9759

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
69 changes: 51 additions & 18 deletions apps/loopover-ui/public/openapi.json
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -22079,6 +22079,9 @@
"202": {
"description": "Job queued"
},
"400": {
"description": "Malformed job request"
},
"401": {
"description": "Invalid internal token"
}
Expand All @@ -22102,6 +22105,9 @@
"202": {
"description": "Job queued"
},
"400": {
"description": "Malformed job request"
},
"401": {
"description": "Invalid internal token"
}
Expand All @@ -22125,6 +22131,9 @@
"202": {
"description": "Job queued"
},
"400": {
"description": "Malformed job request"
},
"401": {
"description": "Invalid internal token"
}
Expand Down Expand Up @@ -22212,7 +22221,7 @@
},
"/v1/internal/jobs/build-contributor-evidence": {
"post": {
"summary": "Queue a contributor evidence build job",
"summary": "Queue a job to build contributor evidence",
"responses": {
"202": {
"description": "Job queued"
Expand All @@ -22221,9 +22230,10 @@
"description": "Invalid internal token"
}
},
"operationId": "postInternalJobsBuildContributorEvidence",
"operationId": "queueBuildContributorEvidenceJob",
"tags": [
"Internal"
"Internal",
"Jobs"
],
"security": [
{
Expand Down Expand Up @@ -22257,7 +22267,7 @@
},
"/v1/internal/jobs/build-burden-forecasts": {
"post": {
"summary": "Queue a burden forecast build job",
"summary": "Queue a job to build burden forecasts",
"responses": {
"202": {
"description": "Job queued"
Expand All @@ -22266,9 +22276,10 @@
"description": "Invalid internal token"
}
},
"operationId": "postInternalJobsBuildBurdenForecasts",
"operationId": "queueBuildBurdenForecastsJob",
"tags": [
"Internal"
"Internal",
"Jobs"
],
"security": [
{
Expand Down Expand Up @@ -22325,7 +22336,7 @@
},
"/v1/internal/jobs/repair-data-fidelity": {
"post": {
"summary": "Queue a data fidelity repair job",
"summary": "Queue a job to repair data fidelity",
"responses": {
"202": {
"description": "Job queued"
Expand All @@ -22334,9 +22345,10 @@
"description": "Invalid internal token"
}
},
"operationId": "postInternalJobsRepairDataFidelity",
"operationId": "queueRepairDataFidelityJob",
"tags": [
"Internal"
"Internal",
"Jobs"
],
"security": [
{
Expand Down Expand Up @@ -25026,6 +25038,9 @@
"200": {
"description": "Job ran inline and returned its result"
},
"400": {
"description": "Malformed job request"
},
"401": {
"description": "Invalid internal token"
}
Expand All @@ -25049,6 +25064,9 @@
"202": {
"description": "Job queued"
},
"400": {
"description": "Malformed job request"
},
"401": {
"description": "Invalid internal token"
}
Expand All @@ -25072,6 +25090,9 @@
"200": {
"description": "Job ran inline and returned its result"
},
"400": {
"description": "Malformed job request"
},
"401": {
"description": "Invalid internal token"
}
Expand Down Expand Up @@ -25141,6 +25162,9 @@
"200": {
"description": "Job ran inline and returned its result"
},
"400": {
"description": "Malformed job request"
},
"401": {
"description": "Invalid internal token"
}
Expand Down Expand Up @@ -25187,6 +25211,9 @@
"200": {
"description": "Job ran inline and returned its result"
},
"400": {
"description": "Malformed job request"
},
"401": {
"description": "Invalid internal token"
}
Expand All @@ -25210,6 +25237,9 @@
"200": {
"description": "Job ran inline and returned its result"
},
"400": {
"description": "Malformed job request"
},
"401": {
"description": "Invalid internal token"
}
Expand Down Expand Up @@ -25315,21 +25345,21 @@
"Internal",
"Jobs"
],
"summary": "Run the job to index repository content for retrieval",
"summary": "Queue a job to index repository content for retrieval",
"security": [
{
"LoopOverBearer": []
}
],
"responses": {
"200": {
"description": "Job ran inline and returned its result"
},
"400": {
"description": "Malformed job request"
"202": {
"description": "Job queued"
},
"401": {
"description": "Invalid internal token"
},
"404": {
"description": "Retrieval is not enabled on this deployment"
}
}
}
Expand All @@ -25341,21 +25371,24 @@
"Internal",
"Jobs"
],
"summary": "Run the job to re-run the gate for one pull request",
"summary": "Queue a job to re-run the gate for one pull request",
"security": [
{
"LoopOverBearer": []
}
],
"responses": {
"200": {
"description": "Job ran inline and returned its result"
"202": {
"description": "Job queued"
},
"400": {
"description": "Malformed job request"
},
"401": {
"description": "Invalid internal token"
},
"404": {
"description": "The repository is not installed"
}
}
}
Expand Down
109 changes: 57 additions & 52 deletions src/openapi/internal-and-public-route-specs.ts
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -30,28 +30,60 @@ type SpecEntry = {
const INTERNAL_AUTH = { 401: { description: "Invalid internal token" } };
const QUEUED = { 202: { description: "Job queued" }, ...INTERNAL_AUTH };
const RAN = { 200: { description: "Job ran inline and returned its result" }, ...INTERNAL_AUTH };
/** Attached PER ENTRY, never folded into QUEUED/RAN: only some job routes validate a body, and widening
* the shared constants would attach a 400 to every route that happily accepts any body (#9706). */
const MALFORMED = { 400: { description: "Malformed job request" } };

/** `[path segment, operationId stem, human summary]` for the jobs that have BOTH forms. */
const JOB_PAIRS: ReadonlyArray<readonly [string, string, string]> = [
["refresh-registry", "RefreshRegistry", "refresh the Gittensor registry snapshot"],
["refresh-scoring-model", "RefreshScoringModel", "refresh the active scoring model"],
["refresh-upstream-drift", "RefreshUpstreamDrift", "recompute upstream ruleset drift"],
["file-upstream-drift-issues", "FileUpstreamDriftIssues", "file issues for open upstream drift"],
["build-contributor-decision-packs", "BuildContributorDecisionPacks", "rebuild contributor decision packs"],
["refresh-contributor-activity", "RefreshContributorActivity", "refresh cached contributor activity"],
["generate-signal-snapshots", "GenerateSignalSnapshots", "generate signal snapshots"],
["generate-weekly-value-report", "GenerateWeeklyValueReport", "generate the weekly value report"],
["generate-review-recap", "GenerateReviewRecap", "generate the maintainer review recap"],
["backfill-registered-repos", "BackfillRegisteredRepos", "backfill registered repository records"],
["backfill-repo-segment", "BackfillRepoSegment", "backfill repository segment assignments"],
["backfill-pr-details", "BackfillPrDetails", "backfill pull-request detail rows"],
["rollup-product-usage", "RollupProductUsage", "roll up product usage counters"],
/**
* A job that exists in BOTH forms: a bare POST that ENQUEUES onto the durable queue, and a `/run` sibling
* that executes inline. `queueValidates`/`runValidates` say which form rejects a malformed body -- the two
* are genuinely independent (build-contributor-decision-packs validates `login` only on `/run`), so a
* single flag would have published a 400 the bare form never returns.
*/
type JobPair = { segment: string; stem: string; summary: string; queueValidates?: boolean; runValidates?: boolean };

const JOB_PAIRS: readonly JobPair[] = [
{ segment: "refresh-registry", stem: "RefreshRegistry", summary: "refresh the Gittensor registry snapshot" },
{ segment: "refresh-scoring-model", stem: "RefreshScoringModel", summary: "refresh the active scoring model" },
{ segment: "refresh-upstream-drift", stem: "RefreshUpstreamDrift", summary: "recompute upstream ruleset drift" },
{ segment: "file-upstream-drift-issues", stem: "FileUpstreamDriftIssues", summary: "file issues for open upstream drift" },
{ segment: "build-contributor-decision-packs", stem: "BuildContributorDecisionPacks", summary: "rebuild contributor decision packs", runValidates: true },
{ segment: "refresh-contributor-activity", stem: "RefreshContributorActivity", summary: "refresh cached contributor activity", queueValidates: true, runValidates: true },
{ segment: "generate-signal-snapshots", stem: "GenerateSignalSnapshots", summary: "generate signal snapshots" },
{ segment: "generate-weekly-value-report", stem: "GenerateWeeklyValueReport", summary: "generate the weekly value report" },
{ segment: "generate-review-recap", stem: "GenerateReviewRecap", summary: "generate the maintainer review recap", queueValidates: true, runValidates: true },
{ segment: "backfill-registered-repos", stem: "BackfillRegisteredRepos", summary: "backfill registered repository records" },
{ segment: "backfill-repo-segment", stem: "BackfillRepoSegment", summary: "backfill repository segment assignments", queueValidates: true, runValidates: true },
{ segment: "backfill-pr-details", stem: "BackfillPrDetails", summary: "backfill pull-request detail rows", queueValidates: true, runValidates: true },
{ segment: "rollup-product-usage", stem: "RollupProductUsage", summary: "roll up product usage counters" },
];

/** Jobs that exist only in the bare (enqueue-or-run) form. */
const SINGLE_JOBS: ReadonlyArray<readonly [string, string, string]> = [
["rag-index", "RunRagIndex", "index repository content for retrieval"],
["regate-pr", "RegatePullRequest", "re-run the gate for one pull request"],
/**
* Jobs that exist only in the bare form.
*
* Every one of them ENQUEUES and answers 202 -- so the summary reads "Queue a job to", and the success
* status is 202 rather than the 200 this table used to publish, which was unreachable for all five.
* Responses vary per entry because the handlers do: rag-index 404s when retrieval is disabled and never
* validates a body at all (an unparseable one becomes `{}`), while regate-pr does both.
*/
type SingleJob = { segment: string; operationId: string; summary: string; responses: Record<number, { description: string }> };

const SINGLE_JOBS: readonly SingleJob[] = [
{
segment: "rag-index",
operationId: "RunRagIndex",
summary: "index repository content for retrieval",
responses: { ...QUEUED, 404: { description: "Retrieval is not enabled on this deployment" } },
},
{
segment: "regate-pr",
operationId: "RegatePullRequest",
summary: "re-run the gate for one pull request",
responses: { ...QUEUED, ...MALFORMED, 404: { description: "The repository is not installed" } },
},
{ segment: "build-contributor-evidence", operationId: "queueBuildContributorEvidenceJob", summary: "build contributor evidence", responses: QUEUED },
{ segment: "build-burden-forecasts", operationId: "queueBuildBurdenForecastsJob", summary: "build burden forecasts", responses: QUEUED },
{ segment: "repair-data-fidelity", operationId: "queueRepairDataFidelityJob", summary: "repair data fidelity", responses: QUEUED },
];

/**
Expand All @@ -69,15 +101,15 @@ const RUN_ONLY_JOBS: ReadonlyArray<readonly [string, string, string]> = [

function jobRoutes(): SpecEntry[] {
const entries: SpecEntry[] = [];
for (const [segment, stem, summary] of JOB_PAIRS) {
for (const { segment, stem, summary, queueValidates, runValidates } of JOB_PAIRS) {
entries.push({
method: "post",
path: `/v1/internal/jobs/${segment}`,
operationId: `queue${stem}Job`,
tags: ["Internal", "Jobs"],
summary: `Queue a job to ${summary}`,
auth: "internal",
responses: QUEUED,
responses: queueValidates ? { ...QUEUED, ...MALFORMED } : QUEUED,
});
entries.push({
method: "post",
Expand All @@ -86,7 +118,7 @@ function jobRoutes(): SpecEntry[] {
tags: ["Internal", "Jobs"],
summary: `Run the job to ${summary} inline, bypassing the queue`,
auth: "internal",
responses: RAN,
responses: runValidates ? { ...RAN, ...MALFORMED } : RAN,
});
}
for (const [segment, stem, summary] of RUN_ONLY_JOBS) {
Expand All @@ -100,15 +132,15 @@ function jobRoutes(): SpecEntry[] {
responses: RAN,
});
}
for (const [segment, operationId, summary] of SINGLE_JOBS) {
for (const { segment, operationId, summary, responses } of SINGLE_JOBS) {
entries.push({
method: "post",
path: `/v1/internal/jobs/${segment}`,
operationId,
tags: ["Internal", "Jobs"],
summary: `Run the job to ${summary}`,
summary: `Queue a job to ${summary}`,
auth: "internal",
responses: { ...RAN, 400: { description: "Malformed job request" } },
responses,
});
}
return entries;
Expand Down Expand Up @@ -546,33 +578,6 @@ const SILENT_401: SpecEntry[] = [
auth: "public",
responses: AUTH_FLOW_RESPONSES,
},
{
method: "post",
path: "/v1/internal/jobs/build-contributor-evidence",
operationId: "postInternalJobsBuildContributorEvidence",
tags: ["Internal"],
summary: "Queue a contributor evidence build job",
auth: "internal",
responses: QUEUED,
},
{
method: "post",
path: "/v1/internal/jobs/build-burden-forecasts",
operationId: "postInternalJobsBuildBurdenForecasts",
tags: ["Internal"],
summary: "Queue a burden forecast build job",
auth: "internal",
responses: QUEUED,
},
{
method: "post",
path: "/v1/internal/jobs/repair-data-fidelity",
operationId: "postInternalJobsRepairDataFidelity",
tags: ["Internal"],
summary: "Queue a data fidelity repair job",
auth: "internal",
responses: QUEUED,
},
];

export function registerInternalAndPublicRouteSpecs(registry: OpenAPIRegistry): void {
Expand Down
Loading
Loading