# 🐧 penguins.lan

A little intranet for a battery-powered LAN with no internet. The successor to
`inetravel` — same "have fun on the network" spirit, but a real Go app instead
of PHP includes, and actually fun stuff: live chat now, an r/place-style shared
canvas next.

## Stack

- **Go** standard-library HTTP server, no framework.
- **SQLite** (`mattn/go-sqlite3`) for persistence.
- **gorilla/websocket** for the realtime hub.
- `html/template` for server-rendered pages.

## Architecture

Requests flow through a small continuation-passing pipeline. Each route in
[`api/serve.go`](api/serve.go) reads as a flat chain of `Continuation`s, where
every link gets a `(success, failure)` pair and decides which to call. Shared
state for a request lives on `types.RequestContext`.

```
LogRequest -> ResolveSession -> RequireUser -> <feature continuations> -> Template -> LogTime
```

Layout:

| path             | what                                                        |
|------------------|-------------------------------------------------------------|
| `main.go`        | entrypoint: load env, open db, migrate, serve               |
| `args/`          | flag parsing                                                |
| `database/`      | sqlite conn, migrations, per-feature queries                |
| `adapters/arp/`  | resolves a client IP -> MAC from the host's ARP table       |
| `api/`           | server wiring (`serve.go`) + feature packages               |
| `api/auth/`      | **MAC-based identity** — sessions, portal, reclaim          |
| `api/ws/`        | **websocket hub** — broadcast chat, foundation for realtime |
| `api/template/`  | html/template rendering + 404 handling                      |
| `templates/`     | server-rendered pages, wrapped in `base.html`               |
| `static/`        | css / js / images                                           |

## Identity (`api/auth` + `adapters/arp`)

No passwords — on a trust-based LAN your **MAC address is your credential**. The
router (nodogsplash) keeps every client on one L2 segment, so the server reads
each visitor's MAC from the ARP table (`arp -an`).

- **First visit** → the portal asks for a handle; claiming it creates a `user`,
  binds your current MAC, and sets a session cookie.
- **Return visit** → a live session cookie logs you in; if it's gone, a
  recognised MAC logs you straight back in.
- **Rotated MAC** (privacy randomization) → you show up as a new device. The
  portal reports when that handle was *last online* and lets you **log back in**
  to reclaim it, re-binding your new MAC to the existing account.

One user can own many MACs (`macs` table). Chat messages reference `user_id`
(not a name), so identity survives MAC rotation and renames.

> **Local dev:** the browser is on loopback and never appears in the ARP table,
> so set `DEV_MAC=aa:bb:cc:dd:ee:ff` to force a MAC and exercise the whole flow.
> Never set it in production — it would make every visitor one shared identity.

## Realtime (`api/ws`)

The `Hub` owns the set of connected clients and a broadcast channel; all client
set mutations happen in its single `Run()` goroutine, so no locks. Each `Client`
has a `readPump` and `writePump`. Messages are JSON tagged by `type`
(`chat` / `system` / `history`). To add a new realtime feature (e.g. the canvas),
add a `type` and handle it in the hub + client — no new connection plumbing.

## Run it

```sh
go mod download
go run . --server --migrate
# -> http://localhost:8080
```

Flags: `--server`, `--migrate`, `--port 8080`,
`--database-path ./db/penguins.db`, `--template-path ./templates`,
`--static-path ./static`.

### Docker

```sh
docker compose up --build
```

## Roadmap

- [x] base framework + live chat over websockets
- [x] MAC-based accounts + portal with reclaim
- [ ] r/place-style shared canvas
- [ ] presence / who's online
- [ ] more LAN games