fix(storage): document multipart upload body for object upload routes - #1272
fix(storage): document multipart upload body for object upload routes#1272grdsdev wants to merge 1 commit into
Conversation
![claude[bot]](https://avatars.githubusercontent.com/in/1236702?s=60&v=4){kind=small}
There was a problem hiding this comment.
LGTM — doc-only change, no runtime impact.
Extended reasoning...
Overview
This PR adds documentMultipartUploadBody, a new step in the existing createOpenApiTransform pipeline in src/http/routes/openapi-transform.ts, which documents the multipart/form-data request body shape (cacheControl, metadata/userMetadata, contentType, file) for the three object-upload operations (createObject, updateObject, uploadSignedObject). These routes previously had no documented request body since they read the raw multipart stream directly rather than using Fastify schema validation. Test coverage is thorough: it verifies the documented shape for all three operations and confirms unrelated/undefined operations are left untouched.
Security risks
None. This only affects the generated OpenAPI/Swagger document (confirmed by tracing createOpenApiTransform usage into src/app.ts, where it is wired into @fastify/swagger's transform option). It does not touch route.schema, so it cannot affect live request validation, authentication, or any runtime behavior. The PR's own code comment explains this was a deliberate design choice to avoid a prior regression where a real schema.body caused 400s on genuine uploads.
Level of scrutiny
Low. This is a pure documentation/tooling change to an OpenAPI transform function, isolated to two files, following an established pattern already in the file (defaultErrorResponse). It's a mechanical split-out of a larger PR (#1270) per prior review feedback, with a clearly scoped TODO for the remaining raw-body documentation follow-up.
Other factors
Tests are comprehensive (11/11 passing per the PR description, and the diff itself shows solid positive/negative test cases). No CODEOWNER-sensitive paths, no auth/crypto/permission code involved. Nothing outstanding from a prior review appears unaddressed.
Coverage Report for CI Build 30384458308Warning Build has drifted: This PR's base is out of sync with its target branch, so coverage data may include unrelated changes. Warning No base build found for commit Coverage: 80.389%Details
Uncovered ChangesNo uncovered changes found. Coverage RegressionsRequires a base build to compare against. How to fix this → Coverage Stats
💛 - Coveralls |
…oad routes Documents both request-body shapes createObject/updateObject/ uploadSignedObject accept (see src/storage/uploader.ts): multipart/ form-data (cacheControl/metadata/userMetadata/contentType/file fields) and the raw upload variant, where the file bytes are the entire body and the same metadata is carried via Cache-Control/Content-Type/ x-metadata headers instead - the x-metadata header is base64-encoded JSON there, unlike the plain JSON-encoded multipart field. Uses schema.body.content (@fastify/swagger's supported multi-content- type body escape hatch, documented for responses in its README, same code path for requests) instead of the single consumes+body shorthand, since the two variants have genuinely different body schemas. Addresses the "we also support raw uploads" follow-up from #1270's review (#1270 (comment)).
8b7304f to
0359be0
Compare
2 participants
Context
Split out of #1270 per review feedback - stacked on top of it since it depends on
openapi-transform.ts. Rebase onto master once #1270 merges.Summary
createObject/updateObject/uploadSignedObjectnever setschema.body- they read the raw multipart stream directly (uploadFromRequest/fileUploadFromRequest, seesrc/storage/object.ts), so they had no documented request body at all. Adds a doc-only transform step (documentMultipartUploadBody) that documents the multipart/form-data shape:cacheControl,metadata(aliasuserMetadata),contentType,file.Still open, per review feedback: these routes also accept a raw (non-multipart) body - not documented here, tracked as a
TODO(follow-up)in the code.Test plan
tsc -noEmit— no errorsbiome checkon touched files — cleanvitest runonopenapi-transform.test.ts— 11/11 passing