[simonhamp]

Lets the mobile app attach images to a commit, a reply or a quote, as the web's composer does. It follows #130 and is one of a few small PRs for the endpoints the app (NativePHP/dev-null-app) uses on top of it.

Endpoint

POST /api/v1/commits now takes up to 3 images, with an optional image_descriptions list in the same order. The limits are the web's, checked by the same rules: JPEG, PNG or WebP by their contents, at most 10 MB and 6000 pixels a side, and descriptions of up to 1000 characters. With images, the body may be short or left out. The images go through the web's CreateCommit, so they are re-encoded as WebP without metadata, and the commit goes to the same moderation.

The 201 has the new commit with its images, as before.

How images fit the request signature

A signed request's signature covers its raw body, and PHP keeps no raw body for a multipart request, which is why #130 refuses multipart. So a request with images is signed the way devnull commit already signs a commit with images:

• It is sent as multipart/form-data, with the JSON body in a payload file part and the images in images[], and nothing else.
• The signed message gets one more line before the body: the SHA-256 of each image, comma-separated in the order they are attached.
• It is signed under its own namespace, devnull-api-images, so a signature says which format it covers.

The server hashes the files it received to rebuild the message, so a swapped, reordered or missing image fails the signature. Any other field or file, a payload that isn't JSON, or a payload sent as a text field is refused like any other body that isn't JSON. Once the signature checks out, the payload becomes the request's fields, cleaned by TrimStrings and ConvertEmptyStringsToNull like a JSON body is. An image PHP couldn't take, for example one over its upload limit, is a 422 on images rather than a bad signature.

I looked at two other ways:

• Base64 images inside the JSON body. Nothing in the signing changes, but bodies get a third bigger, and the request would have to turn strings into uploaded files to reuse the web's rules.
• A separate upload endpoint that stores images first and hands back ids for the commit. That needs a table for uploads nobody committed, pruning, and a limit on how much someone can upload without committing.

Multipart keeps one request and one transaction, so a commit and its images still come and go together, and it reuses a format the CLI already has.

Pending images in the app

The images of a pending commit are only served by commit-image.show to their author or a moderator over a web session, which the app doesn't have. So in a signed response, the images of a commit that isn't published yet come with a temporary signed URL instead, and ShowCommitImageRequest accepts a valid signature as long as the commit isn't deleted. The URL expires at the end of the next hour, so it stays the same for an hour at a time and the app can keep the image it loaded. Published images keep their plain URL.

Worth a look: anyone holding one of those URLs can see that pending image until it expires. Only the author and admins are ever sent one.

Testing

Everything CI runs passes on this branch locally: Pint, Rector, the JS lint, PHPStan, tsc, type coverage, and all 3,634 tests at 100% coverage.

The README documents the format, with an example. KNOWLEDGE_BASE.md said the signed API can't attach images and that its bodies are JSON only; it now says both.

The app side is NativePHP/dev-null-app#24. It ran against all four of these PRs merged together on an iOS simulator: photos from the library with a description, a poll, the preview, a reply with a photo, and a vote.