Upload a file as multipart form data

cd compiler/examples/form_upload
sakura check --json
sakura test --json

[package]
name = "form_upload"
version = "0.1.0"
edition = "2026"

[permissions]

import std/blob.{Blob, FileData}
import std/form.{Form, FormError, FormLimits, Part}
import std/fs.{Fs}
import std/http.{Http, Matcher}
import std/path.{Path}
import std/request.{BadRequest, Bytes, Post, Request, Text}
import std/response.{HttpError, Response, Status}
import std/router.{Router}
import std/url.{Url}

/// A file named `name` holding `bytes` of `media_type`.
fn file(name: String, bytes: Bytes, media_type: String) -> FileData {
  FileData { blob: Blob.of(bytes, media_type), name, last_modified: Instant.from_unix_millis(0) }
}

/// The upload as a `POST` of a `multipart/form-data` body with a fresh boundary. The body is
/// `Bytes`, so the file may be any bytes.
fn upload_request(target: Url, title: String, report: FileData) -> Request ! {Random} {
  let form = Form { entries: [("title", Part.Text(title)), ("report", Part.File(report))] }
  let boundary = Form.boundary()
  Request.of(Post, target)
    .with_header("content-type", "multipart/form-data; boundary={boundary}")
    .with_payload(Bytes(Form.encode_multipart(form, boundary)))
}

fn upload(target: Url, title: String, report: FileData) -> Status
  ! {Http, Random, Fail<HttpError>}
{ Http.send(upload_request(target, title, report)).status }

fn csv(text: String) -> FileData { file("report.csv", String.to_bytes(text), "text/csv") }

/// The receiving side: at most 4 parts, 64 KiB in all and 32 KiB per part.
fn receive(req: Request) -> Response {
  let limits = FormLimits { max_parts: 4, max_bytes: 65_536, max_field_bytes: 32_768 }
  let content_type = Request.header(req, "content-type").unwrap_or("")
  try {
    match Form.parse_multipart(Request.bytes(req, limits.max_bytes), content_type, limits) {
      Ok(form) => {
        let names = List.map(form.entries, fn(e) {
          match e.1 {
            Part.Text(v) => "{e.0}={v}",
            Part.File(f) => "{e.0}={f.name} ({f.blob.media_type}, {Blob.size(f.blob)} bytes)",
          }
        })
        Response.status(201, List.join(names, "; "))
      },
      Err(FormError { reason }) => Response.status(400, "bad form: {reason}"),
    }
  } catch {
    BadRequest { detail } => Response.status(400, detail),
  }
}

test "the upload is sent once, as multipart" {
  with Http.scripted([(Matcher.Path("/v1/reports"), Response.status(201, "stored"))]) {
    expect_eq(
      upload(url"https://files.example.test/v1/reports", "Q3", csv("a,b\n1,2\n")),
      Status.from(201),
    )
  }
}

test "a binary upload and its binary answer replay from the cassette" {
  let png = Bytes.from_list([0x89, 0x50, 0x4E, 0x47, 0x0D, 0x0A, 0x1A, 0x0A, 0x00, 0xFF])
  let thumb = Response { ..Response.status(201, ""), body: Bytes(Bytes.from_list([0xFF, 0xD8])) }
  with Fs.rooted(Test.fixtures()),
      Http.scripted([(Matcher.Path("/v1/images"), thumb)]),
      Http.recording(Path.of("upload.jsonl")) {
    let req = upload_request(
      url"https://files.example.test/v1/images",
      "logo",
      file("logo.png", png, "image/png"),
    )
    let resp = Http.send(req)
    expect_eq(resp.status, Status.from(201))
    expect_eq(Response.bytes(resp, 16), Bytes.from_list([0xFF, 0xD8]))
  }
}

test "the receiving side reads both parts back" {
  let req = upload_request(url"/v1/reports", "Q3 \u{1F338}", csv("a,b\n1,2\n"))
  let response = Router.handle(Router.new().post("/v1/reports", receive), req)
  expect_eq(response.status, Status.from(201))
  expect_eq(response.body, Text("title=Q3 \u{1F338}; report=report.csv (text/csv, 8 bytes)"))
}

test "a body over the limits or with the wrong content type is refused" {
  let big = upload_request(url"/v1/reports", "big", csv(String.repeat("x", 40_000)))
  let app = Router.new().post("/v1/reports", receive)
  expect_eq(Router.handle(app, big).body, Text("bad form: Limit(MaxFieldBytes)"))
  let plain = Request { ..big, headers: [("content-type", "text/plain")] }
  expect_eq(Router.handle(app, plain).body, Text("bad form: ContentType"))
}

# Recorded cassette

`upload.jsonl` was written by `sakura test --record` against `Http.scripted`, so no request
left the machine. Both bodies are binary, so they are stored as `body_base64` and
`response_body_base64`.

{"schema_version":"1.0","kind":"cassette"}
{"method":"POST","url":"https://files.example.test/v1/images","headers":[["content-type","multipart/form-data; boundary=----SakuraFormBoundaryj-JGffEjUVnDfyNv"]],"body_base64":"LS0tLS0tU2FrdXJhRm9ybUJvdW5kYXJ5ai1KR2ZmRWpVVm5EZnlOdg0KQ29udGVudC1EaXNwb3NpdGlvbjogZm9ybS1kYXRhOyBuYW1lPSJ0aXRsZSINCg0KbG9nbw0KLS0tLS0tU2FrdXJhRm9ybUJvdW5kYXJ5ai1KR2ZmRWpVVm5EZnlOdg0KQ29udGVudC1EaXNwb3NpdGlvbjogZm9ybS1kYXRhOyBuYW1lPSJyZXBvcnQiOyBmaWxlbmFtZT0ibG9nby5wbmciDQpDb250ZW50LVR5cGU6IGltYWdlL3BuZw0KDQqJUE5HDQoaCgD/DQotLS0tLS1TYWt1cmFGb3JtQm91bmRhcnlqLUpHZmZFalVWbkRmeU52LS0NCg==","status":201,"response_headers":[],"response_body_base64":"/9g="}