Repository navigation
Conversation
Adjust the PHP annotations whose cause is in LibreSign so generated clients
describe the real API:
- rename the ID document schema `File` to `IdDocFile`: the name collides with
the global TypeScript `File`, and typescript-axios renamed the model without
updating its references, leaving `Array<any>`;
- declare literal media types for the CRL (application/pkix-crl) and the admin
background (image/png);
- document only `MessageResponse` for the 422 of request-signature POST and
PATCH, which always return `{message}`, and drop two `anyOf`;
- document `MessageResponse` for the 422 of removeSigner and remove the 422
that deleteFile and deleteSignatureRequest never return;
- make `DetailedFile.nodeId` nullable like `libresign_file.node_id`.
The notify 422 `anyOf` stays: canRequestSign() throws an action/errors body and
other validations a message body.
Specs and TypeScript types are regenerated, not hand-edited. Contract tests
cover the new shapes.
Signed-off-by: Luis Amorim <principal@felps.zip>
Re-run the LibreSign#9089 evaluation on main with the LibreSign contract fixes: - inject the real `@nextcloud/axios` instance (jsdom) into a generated client and cover requesttoken, X-Requested-With, OCS-APIRequest and the CSRF retry; - turn the former `anyOf` reproduction into a regression guard and add `union-defects.ts`, which compiles only while the remaining object unions are still generated incorrectly; - replace the removed `callback` checks with `status`; - record the result in REPORT.md (still No-Go for unmodified input) and the extractor and generator follow-ups in UPSTREAM-NOTES.md, including what remains open in LibreSign. No generator, extractor or generated source is modified. Signed-off-by: Luis Amorim <principal@felps.zip>
A previous commit on this branch narrowed the 422 of request-signature
(POST, PATCH), removeSigner, deleteFile and deleteSignatureRequest to a
`{message}` body or removed it. That was wrong: #[RequireManager] runs
canRequestSign() before the controller and its try block, so a user without
permission still receives 422 with an `{action, errors}` body.
Restore the original `ActionErrorResponse` documentation for those operations
and document removeSigner as `MessageResponse|ActionErrorResponse`, because its
catch block answers `{message}` with 422 when the exception code is 422.
`DetailedFile.nodeId` stays nullable.
Specs and TypeScript types are regenerated, not hand-edited. The contract test
now asserts both bodies instead of the narrowed contract.
Signed-off-by: Luis Amorim <principal@felps.zip>
Rewrite the sections that claimed the 422 of the guarded operations was
unreachable and that RequireManager answers 401: the middleware answers 422 with
an `{action, errors}` body. Update the anyOf count (15), the SHA-256 of
openapi-full.json, the methods that answer 401 for caught failures, the note on
policySnapshotFrozen, and the TS2578/TS2322 description in the README.
Signed-off-by: Luis Amorim <principal@felps.zip>
- say that the evaluation changes the LibreSign annotations, committed OpenAPI
and generated types, instead of claiming no change;
- separate the five merged 422 models from the seven envelope models that read
the contract faithfully;
- attribute the {action, errors} body of the notify endpoints to the call inside
NotifyService, since they have no RequireManager;
- describe the 82 untyped 401/403 responses as mostly implicit, not only
implicit;
- drop "object unions" from the extractor handoff option and the overstated
"schema-valid null" claim in the README;
- list the other RequireManager methods that do not document the permission 422.
Signed-off-by: Luis Amorim <principal@felps.zip>
Complete the annotations that omitted what the API really returns:
- file-save and file-add-file-to-envelope document the 422 as
`MessageResponse|ActionErrorResponse`: #[RequireManager] runs canRequestSign()
before the method, so a user without permission gets an `{action, errors}`
body, while the catch blocks answer `{message}`;
- identify-account/search documents the middleware 422
(`ActionErrorResponse`); the method has no try block;
- ValidatedFile and ValidatedChildFile accept a null nodeId, like DetailedFile:
BeforeNodeDeletedListener clears libresign_file.node_id when the original file
is deleted and the validation code copies the entity value as is.
The file filter in validationDocument.ts keeps rejecting a null nodeId; only its
type predicate follows the normalized value, so behavior is unchanged.
Specs and TypeScript types are regenerated, not hand-edited. The contract test
covers the new shapes.
Signed-off-by: Luis Amorim <principal@felps.zip>
Update the counts (17 anyOf, 14 of them in error bodies), the SHA-256, the list of corrected annotations, and note that the validation frontend treats a null nodeId as an invalid document. Signed-off-by: Luis Amorim <principal@felps.zip>
Only the notify endpoints rely on the middleware to serialize both 422 bodies.
For the five operations guarded by #[RequireManager] the `{message}` body is a
DataResponse built in the method's catch block, and the middleware only
serializes the permission body. Also list the frontend type adjustments among
the LibreSign changes of the evaluation.
Signed-off-by: Luis Amorim <principal@felps.zip>
… headers Psalm rejects the `@return` added for the literal `image/png` media type because `new FileDisplayResponse($file)` is inferred with empty headers. Pass the headers to the constructor, as CertificatePolicyController already does, and drop the redundant addHeader calls (the same keys are sent at the end). Cover the headers with a unit test. Signed-off-by: Luis Amorim <principal@felps.zip>
The previous commit moved the headers to the FileDisplayResponse constructor and dropped the addHeader calls, but the constructor always sets Content-Disposition to "inline" with the file name, so the response lost its `attachment; filename="background.png"` disposition. The unit test added there caught it. Keep the headers in the constructor, which lets Psalm infer the documented shape, and set the disposition again after construction. Signed-off-by: Luis Amorim <principal@felps.zip>
This branch has not been deployed
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Related: #9087
📝 Summary
Aligns the OpenAPI contract with what the controllers actually return, so a generated SDK (#9087,
typescript-axios) gets truthful types, and adds a harness that evaluates the generated client against that contract.Nothing in
vendor/,vendor-bin/or the generator is patched. Defects whose cause is innextcloud/openapi-extractoror OpenAPI Generator are only recorded intests/sdk-generation/UPSTREAM-NOTES.md, with a reproduction for each.Contract fixes (LibreSign side)
422bodies are documented asMessageResponse | ActionErrorResponsewhere both are really sent:#[RequireManager]/canRequestSign()answers{action, errors}before the method runs, and the method's owncatchanswers{message}. Affected:request-signature,update-signature-request,removeSigner,deleteFile,deleteSignatureRequest,file-save,file-add-file-to-envelopeand the notify endpoints.identify-account/searchdocuments the middleware 422.nodeIdis nullable inDetailedFile,ValidatedFileandValidatedChildFile, like the database column. The frontend type usage was adjusted accordingly.Fileis renamed toIdDocFile, because the generator renamesFiletoModelFilebut leaves its references asany.application/pkix-crland the admin backgroundimage/pnginstead of*/*. The background response is built with its documented headers, andContent-Disposition: attachmentis kept, because theFileDisplayResponseconstructor would otherwise forceinline.openapi.json,openapi-full.json,openapi-administration.jsonandsrc/types/openapi/*.ts.SDK evaluation harness (
tests/sdk-generation/)typescript-axiosclient from the current spec and exercises it against the Nextcloud axios usage, withREPORT.md(Go/No-Go handoff) andREADME.md.UPSTREAM-NOTES.mdlists what must change in the extractor (multipart bodies,anyOf,mixed, implicit 401/403 bodies) and in the generator (anyOfmerge, reservedFile, error types, multipart serialization).Known limitation, left on purpose
Six operations still document
401for failures that are not authentication failures (signatureGenerate, the two certificate generators,deleteFile,removeSigner,deleteSignatureRequest). Each produces an extraanyOfthat the generator mishandles. Changing those statuses is a breaking change and is not part of this PR; it is proposed separately infix/api-failure-status-codes.🧪 How to test
The harness is described in
tests/sdk-generation/README.md.Validation evidence
OpenApiErrorBodyContractTest,OpenApiIdDocSchemaTest,OpenApiBinaryMediaTypesTest.AdminControllerTest,RequestSignatureControllerTest.ts:checkand REUSE ran locally.act, with the branch merged with upstreammain, was green: openapi, php-cs, psalm, PHPUnit (5509 tests), eslint, typescript, vitest (3675 tests) and the 4 Behat shards (246 scenarios).Not verified: Playwright, Infection, devcontainer,
test:liveagainst a real Nextcloud, and a real browser with the XHR adapter.⚙️ API / Back-end changes
attachmentdisposition and now declares its media type. See the Summary for the list.OpenApiErrorBodyContractTestasserts that both422bodies are documented where the middleware and thecatchcan each answer.tests/sdk-generation/REPORT.md,UPSTREAM-NOTES.md,README.mdcomposer openapiwhen necessary🚧 Tasks
tests/sdk-generation/UPSTREAM-NOTES.md; nothing has been filed yetDetailedFile.policySnapshotFrozenis required but omitted without a user, and the frontend still rejects a nullnodeIdinvalidationDocument.ts✅ Checklist
openapi*.jsonandsrc/types/openapi/*.ts, as required by the contract change.)🤖 AI (if applicable)