Skip to content

Allow Response return from mock handlers for non-JSON, non-204 responses - #394

Merged
charliepark merged 3 commits into
mainfrom
status-or-response
Nov 16, 2026
Merged

charliepark merged 3 commits into
mainfrom
status-or-response

Conversation

@charliepark

@charliepark charliepark commented Nov 13, 2026 •

Copy link
Copy Markdown
Contributor

Closes #386

Mock handlers for endpoints without a JSON success type had the return type Promisable<StatusCode>, but some of those endpoints need headers or a body in the response. Console's supportBundleHead handler returns an HttpResponse with Content-Type and Content-Length, and it needed a @ts-expect-error to do that. (See here.) The dispatcher already passes Response instances through at runtime, so accepting only the StatusCode (in the handlers where we needed the response) was too narrow.

The generator now makes a distinction between two cases. Operations with a 204 success response keep Promisable<StatusCode>. Operations that respond with something other than JSON or a 204 (binary download, HEAD, redirect) get Promisable<StatusOrResponse>, where StatusOrResponse is a new alias for StatusCode | Response in the generated file.

To support this, Operation now has a successCode field (the key of the success response in the spec, e.g. "200", "204", "default"), and the MSW generator checks successCode === "204". getOperations now throws if an operation does not have exactly one non-error response; this replaces getSuccessResponse, which picked the first of 200, 201, 202 and 204 without a check. Every operation in the current Nexus spec has exactly one, so the generated client is unchanged.

In the current Nexus spec, nine handlers get the new result type; others are unchanged.

  • supportBundleHead, supportBundleHeadFile
  • supportBundleDownload, supportBundleDownloadFile, supportBundleIndex
  • deviceAuthRequest, deviceAccessToken
  • loginSaml, instanceSerialConsoleStream

When we merge this, (and update to the new version in console) we'll be able to remove the @ts-expect-error here.

I checked this locally, as I'm working on an OMICRON_VERSION bump as a part of oxidecomputer/console#3211 and I hit an issue with new missing handlers that weren't getting caught by npm run tsc until I dug into this. To test: linked the local build of openapi-gen-ts (this code) into local console's node_modules, then ran npm run gen-api and npm run tsc. It caught the missing handlers and then tsc passed once I added them in.

This also bumps the version to 0.17.0, as the generated handler types change.

@charliepark

Copy link
Copy Markdown
Contributor Author

@claude review

@claude claude Bot left a comment

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

LGTM. This is a small, type-only widening of the generated MSW handler return types, plus a patch version bump.

What was reviewed:

  • The new isNoContent field. It is set only in getOperations, which is the only place an Operation object is built, so no other construction site is missing the field.
  • The return-type choice in msw-handlers.ts. Operations with a 204 response keep StatusCode. Operations with no described response get StatusCode | Response. The existing dispatcher already passes Response results through at runtime.
  • The snapshot. It matches the generator output for the nine affected handlers and the new StatusOrResponse alias.
Extended reasoning...

The change touches the TypeScript code generator for MSW mock handlers (base.ts and msw-handlers.ts), its regenerated snapshot, and a patch version bump. It has no security-sensitive surface; it only affects types in the generated mock-API code. For endpoints whose success response is undescribed, the handler return type now also allows Response. The runtime wrapper already handled Response results, so generated behaviour does not change. The diff is small and mechanical, there are no CODEOWNERS files, and no reviewer objections are open.

Comment thread oxide-openapi-gen-ts/src/client/base.ts Outdated
queryParams,
bodyType: contentRef(conf.requestBody),
successType: contentRef(getSuccessResponse(conf.responses)),
isNoContent: "204" in conf.responses,

@david-crespo david-crespo Nov 16, 2026 •

Copy link
Copy Markdown
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Rather than putting isNoContent on here, I would put successCode and check successCode === 204 in the calling code. That way this code doesn't need to know what the MSW generator cares about. 🤖 suggests:

const [successCode, successResponse] =
  Object.entries(conf.responses).find(([code]) => !/^[45]/.test(code)) ?? [];

or maybe this if we want to blow up if there's ever more than one (I like it):

const successes = Object.entries(conf.responses).filter(
  ([code]) => !/^[45]/.test(code),
);
if (successes.length !== 1) {
  throw new Error(
    `Expected one non-error response for ${conf.operationId}, got ${successes.length}`,
  );
}
const [[successCode, successResponse]] = successes;

getSuccessResponse can go away.

Copy link
Copy Markdown
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Nice. That does seem more direct / transparent.

Comment thread oxide-openapi-gen-ts/package.json Outdated
{
"name": "@oxide/openapi-gen-ts",
"version": "0.16.0",
"version": "0.16.1",

Copy link
Copy Markdown
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

This should be a minor bump because it is a semantic change to generated output.

https://github.com/oxidecomputer/oxide.ts/tree/main/oxide-openapi-gen-ts#versioning-scheme

@david-crespo david-crespo left a comment

Copy link
Copy Markdown
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Looks good pending the two things.

@charliepark charliepark changed the title Allow Response return from mock handlers with undescribed responses Allow Response return from mock handlers for non-JSON, non-204 responses Nov 16, 2026
@charliepark
charliepark merged commit 2292ce8 into main Nov 16, 2026
5 checks passed
@charliepark
charliepark deleted the status-or-response branch November 16, 2026 18:32
`Expected one non-error response for ${conf.operationId}, got ${success ? rest.length + 1 : 0}`,
);
}
const [successCode, successResponse] = success;

Copy link
Copy Markdown
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Nice, yeah the [[ ... ]] in my suggestion was horrible

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

Want more permissive type on mock HEAD handlers

2 participants