# File Upload

User picks one or more files in a form. The browser reads the bytes, an rpc
inserts each file into a Postgres `bytea` column, and a separate route serves
the bytes back so an `<img src>` can display them.

The `<input type="file" value={files}>` binding does the read for you. The
form's submit handler waits for any in-flight file reads to finish before it
runs, so there is no race between picking a file and submitting.

## One file or many

The `multiple` attribute decides the type the input binds:

```html
<input type="file" value={avatar}>            <!-- one File -->
<input type="file" multiple value={photos}>   <!-- a File[] -->
```

```ts
private avatar: File;      // no multiple
private photos: File[] = [];   // multiple
```

Mismatch them and the build says so. `File[]` on an input without `multiple`
is an error, and so is a single `File` on one with it.

The rest of this page builds a gallery, so everything below uses `multiple` and
`File[]`. For a single attachment, drop `multiple` and use `File` wherever you
see `File[]`.

## Migration

Scaffold with `elements create migration`, then add the columns specific to file
storage.

```bash
elements create migration 'add images' -tables=images
```

`app/migrations/<timestamp>-add-images.migration.sql`:

```sql
-- add images

-- Auto-update updatedAt on row changes.
create or replace function touchUpdatedAt()
returns trigger
language plpgsql
as $$
begin
  new.updatedAt = now();
  return new;
end;
$$;

create table images (
  id uuid primary key default uuidGenerateV7(),
  createdAt timestamptz not null default now(),
  updatedAt timestamptz not null default now(),
  name text not null,
  contentType text not null,
  size integer not null,
  data bytea not null
);

create trigger imagesTouchUpdatedAt
  before update on images
  for each row execute function touchUpdatedAt();
```

The four columns added on top of the scaffold are `name`, `contentType`, `size`,
and `data`. The `data` column is `bytea`. `File.data` (a `Uint8Array`)
interpolates into a `bytea` parameter directly.

## Gallery services

```bash
elements create page gallery
```

That writes
`app/pages/gallery/{index.ts, template.html, style.css, test.ts}`. Add a
`services.ts` sibling by hand for the `ImageMeta` interface and the `upload` rpc.

`app/pages/gallery/services.ts`:

```ts
import { sql, tx, File, ValidationError } from "@elements/app";

// The types this gallery is willing to store and later serve inline. Anything
// not on this list is rejected. See "Never trust the uploaded content type".
const ALLOWED = new Set(["image/png", "image/jpeg", "image/gif", "image/webp"]);

export interface ImageMeta {
  id: string;
  name: string;
  contentType: string;
  size: number;
  createdAt: Date;
}

/** @rpc */
export function upload(files: File[]): ImageMeta[] {
  for (let f of files) {
    if (!ALLOWED.has(f.contentType)) {
      throw new ValidationError(`${f.name} is not an image`);
    }
  }

  tx(() => {
    for (let f of files) {
      sql(
        `insert into images (name, contentType, size, data)
         values (${f.name}, ${f.contentType}, ${f.size}, ${f.data})`,
      );
    }
  });

  return sql<ImageMeta>(
    `select id, name, contentType, size, createdAt from images order by createdAt desc`,
  ).all();
}
```

The allowlist runs before `tx()` so a rejected file fails the whole batch before
anything is written. The bulk insert then runs inside `tx()` so the batch is
atomic: if one row fails, none commit. The rpc returns the refreshed metadata
list; the template reassigns its parameter and the grid re-renders.

This gallery uploads files only, so `File[]` is its own parameter. A form that
also collects text (a post with a title, a body, and an attachment) puts the
`File[]` in the same form object as the other fields and passes that one object
to a single `@rpc`, rather than splitting files into a separate parameter:

```ts
interface PostForm {
  title: string;
  body: string;
  files: File[];
}

/** @rpc */
export function createPost(form: PostForm): Post {
  // form.files is a File[] like any other field
}
```

```html
<input type="file" multiple value={form.files}>
```

`File[]` crosses the rpc boundary inside a form object exactly as it does on its
own. A single `File` field works the same way:

```ts
interface ProfileForm {
  name: string;
  avatar: File;
}
```

```html
<input type="file" value={form.avatar}>
```

## Gallery route

`app/pages/gallery/index.ts`:

```ts
import { sql } from "@elements/app";
import gallery from "./template";
import { ImageMeta } from "./services";

export default function route(req, res) {
  let images = sql<ImageMeta>(
    `select id, name, contentType, size, createdAt from images order by createdAt desc`,
  ).all();

  return new gallery({ images });
}
```

The `select` lists every column except `data` so the metadata stays small.
Pulling every image's bytes into the HTML render would put megabytes of base64
in the response. The bytes are served separately, on demand, by the route below.

## Gallery template

`app/pages/gallery/template.html`:

```html
import "./style.css";
import { File } from "@elements/app";
import { upload, ImageMeta } from "./services";

<html class="gallery"
      (images: ImageMeta[],
       private files: File[] = [])>
  <form onsubmit={() => {
    images = upload(files);
    files = [];
  }}>
    <input type="file" multiple accept="image/*" value={files}>

    <button type="submit">upload</button>
  </form>

  <ul class="gallery">
    <li e:for={img of images}>
      <img src={`/images/${img.id}`} alt={img.name}>
      <span>{img.name}</span>
    </li>
  </ul>
</html>
```

`value={files}` binds the file input to a `File[]` parameter. When the user
picks files, the runtime reads the bytes asynchronously and assigns the array.
The form's submit handler waits for the read to finish, then calls
`upload(files)`. The rpc's return value replaces `images`, which re-renders the
grid. Setting `files = []` after the rpc resolves clears the file input via the
same binding so the form is ready for the next batch.

## Serving the bytes

The serve route returns binary bytes, not HTML, so it isn't a page. Create the
file by hand alongside the pages.

`app/routes/images.ts`:

```ts
import { sql } from "@elements/app";

export interface Image {
  id: string;
  name: string;
  contentType: string;
  data: Buffer;
}

const INLINE = new Set(["image/png", "image/jpeg", "image/gif", "image/webp"]);

export default function serveImage(req, res) {
  let img = sql<Image>(
    `select id, name, contentType, data from images where id = ${req.params.id}`,
  ).firstOrThrow();

  if (INLINE.has(img.contentType)) {
    res.setHeader("Content-Type", img.contentType);
  } else {
    // Not a type we are willing to render on our own origin. Send it as an
    // opaque download instead of letting the browser decide what it is.
    res.setHeader("Content-Type", "application/octet-stream");
    res.setHeader("Content-Disposition", "attachment");
  }

  return img.data;
}
```

`firstOrThrow()` returns a safe 404 if the id doesn't exist. Returning a `Buffer`
directly sends raw bytes; the Elements response layer recognizes `Buffer` and
skips the EJSON serializer.

## Never trust the uploaded content type

The allowlist appears twice on purpose, and the second one is the one that
matters.

`f.contentType` is supplied by whoever uploaded the file. It is not derived from
the bytes. If you store it and echo it back, someone uploads a file declaring
`text/html`, your serve route answers with `Content-Type: text/html`, and the
browser runs their markup **on your origin**. The Elements session cookie is
readable from script by design, so that is not a defaced image, it is a stolen
session.

Checking on upload is necessary but not sufficient: rows can predate the check,
arrive from a migration, or be written by another code path. The serve route is
the only place that decides what the browser is told, so the guard belongs
there too.

Two more things make this solid:

- Elements sends `X-Content-Type-Options: nosniff` on every response, so a file
  whose declared type is `image/png` but whose bytes are HTML is not
  reinterpreted. The allowlist and the header work together: the allowlist
  controls what you declare, `nosniff` stops the browser second-guessing it.
- For anything beyond images, serve user content from a different origin. A
  separate hostname means a hostile file cannot reach your session cookie even
  if everything else goes wrong.

## Routes

Register both routes in `index.ts`:

```ts
import gallery from "#app/pages/gallery";
import serveImage from "#app/routes/images";

// ...
app.route("/gallery", gallery);
app.route("/images/:id", serveImage);
```

## Notes

- `File.data` is a `Uint8Array` on the browser. After the rpc, the server sees
  the same bytes via the Elements JSON deserializer. The `${f.data}`
  interpolation goes straight into the `bytea` parameter slot.
- The metadata query in the route handler omits `data` on purpose. Selecting `*`
  would pull every image's bytes into the HTML render, which is usually
  megabytes of base64 you don't need.
- For larger files, swap `bytea` storage for an S3 client (or any object store).
  The shape of this recipe stays the same; only the `upload` rpc and the serve
  route change.
- `accept="image/*"` is a hint to the browser's file picker, not a server-side
  check, and not a security boundary. The allowlist in the rpc is the check.