# upl

`upl` is a small personal resumable upload service. The intended deployment is:

```text
browser -> nginx -> upl Rust server -> local filesystem
```

The server writes upload chunks directly into an inaccessible temp file at
their final offsets. Once every chunk is present, completion promotes that temp
file into the completed upload directory without replacing an existing file.

## Project Structure

```text
upl
  Rust server
    src/main.rs        binary entrypoint and listener setup
    src/app.rs         Axum router, shared state, static file service
    src/api.rs         HTTP handlers and API error responses
    src/model.rs       JSON request, response, and metadata shapes
    src/storage.rs     local filesystem layout, offset writes, and final promotion
    src/lib.rs         library surface used by integration tests
  Browser UI
    static/index.html  upload tool markup
    static/styles.css  responsive tool styling
    static/app.js      multi-file scheduler, retries, and browser resume state
  Deployment
    deploy/nginx/      nginx reverse proxy example
    scripts/           reusable local smoke tests
  Validation
    tests/             integration tests for server behavior
    TESTS.md           reusable manual and automated test checklist
```

## Configuration

- `--bind` sets the listen address. It overrides `UPL_BIND` and defaults to
  `127.0.0.1:3000`.
- `--static-dir` sets the static asset directory. It overrides `UPL_STATIC_DIR`
  and defaults to `static/` inside this repository.
- `--data-dir` sets the completed upload data root. Completed files land under
  its `complete/` subdirectory. It overrides `UPL_DATA_DIR` and defaults to
  `data/` inside this repository.
- `--temp-dir` sets the directory for upload metadata, completion markers, and
  inaccessible temp upload files. It overrides `UPL_TEMP_DIR` and defaults to
  `<data-dir>/staging`.
- `upl --help` prints the full argument help text.
- The server accepts request bodies up to 64 MiB, which leaves room for the
  planned 16 MiB upload chunks and matches the nginx example in `PLAN.md`.
- Keep `UPL_TEMP_DIR` on the same filesystem as `<data-dir>/complete` for the
  cheapest final promotion. Cross-filesystem temp directories still work, but
  completion falls back to copying into a newly created final file.

## Common Commands

Use the `justfile` for routine tasks:

```sh
just check
just run
```

`just check` also syntax-checks the static browser JavaScript with `node`.

## Browser Uploads

The browser UI accepts multiple selected files. `Start all` runs up to three
file uploads at the same time, and each file still uploads up to three chunks
concurrently. Every selected file keeps its own upload id, progress markers,
abort controller, retry state, and saved IndexedDB resume record.

If a completed file with the same sanitized name already exists, the server
rejects the upload before staging begins. The selected row is marked
unavailable and tells the user to rename the file if they want to upload that
copy.

## nginx

Run `upl` on localhost and put nginx in front of it for TLS and access control:

```sh
UPL_BIND=127.0.0.1:3000 \
UPL_DATA_DIR=/srv/upl/data \
UPL_TEMP_DIR=/srv/upl/data/staging \
upl
```

Use `deploy/nginx/upl.conf.example` as the starting point for the nginx site.
Before exposing the service, replace the certificate paths and add a protection
layer such as HTTP basic auth, an IP allowlist, or VPN-only access. The nginx
example aliases only `/srv/upl/data/complete`; do not expose `UPL_TEMP_DIR`.

For a local Docker-based reverse-proxy smoke test:

```sh
just nginx-smoke
```

The smoke test binds the Rust server to `0.0.0.0` so the nginx container can
reach it through Docker's host gateway. The production nginx example keeps the
server bound to localhost.