121 lines
4.8 KiB
Markdown
121 lines
4.8 KiB
Markdown
# tbd
|
|
|
|
A small Clojure HTTP API built on [Ring](https://github.com/ring-clojure/ring) (Jetty) and
|
|
[reitit](https://github.com/metosin/reitit), with a ClojureScript
|
|
[re-frame](https://github.com/day8/re-frame) front end (`ui/`), Swagger UI docs, unit tests,
|
|
dockerized integration tests, and joint line coverage.
|
|
|
|
## Requirements
|
|
|
|
- Docker, for the integration tests and the `script/docker-*` tasks (all CI needs)
|
|
- For running tasks natively (optional): [Clojure CLI](https://clojure.org/guides/install_clojure) (tools.deps) with JDK 11+, [Node](https://nodejs.org/) 20+ (with a JDK) for the UI build, and [Babashka](https://babashka.org/) for `script/coverage-report`
|
|
|
|
## Running
|
|
|
|
```bash
|
|
script/ui-build # compile the UI (once, and after UI changes)
|
|
script/server [port]
|
|
```
|
|
|
|
The server listens on port `3000` by default; pass a port argument or set `PORT` to change it
|
|
(the argument wins):
|
|
|
|
```bash
|
|
script/server 8080
|
|
PORT=8080 script/server
|
|
```
|
|
|
|
This is a thin wrapper around `clojure -X:run`, which also honors `PORT`. Then open
|
|
http://localhost:3000 for the UI. Without `script/ui-build` the server still starts, but `/`
|
|
shows a placeholder.
|
|
|
|
Or build and run the container:
|
|
|
|
```bash
|
|
docker build -t tbd .
|
|
docker run --rm -p 3000:3000 tbd
|
|
```
|
|
|
|
## API
|
|
|
|
| Method | Path | Description |
|
|
|--------|------|-------------|
|
|
| `GET` | `/` | The UI: an HTML shell that loads the compiled ClojureScript from `/js/main.js` |
|
|
| `GET` | `/api/ping` | Health check, returns `pong` |
|
|
| `GET` | `/api/add?x=2&y=3` | Adds two numbers, returns EDN: `{:result 5}` (400 if either is missing or not a number) |
|
|
| `GET` | `/api-docs` | Swagger UI |
|
|
| `GET` | `/swagger.json` | OpenAPI/Swagger spec |
|
|
|
|
```bash
|
|
curl localhost:3000/api/ping # pong
|
|
curl 'localhost:3000/api/add?x=2&y=3' # {:result 5}
|
|
```
|
|
|
|
## UI
|
|
|
|
`ui/` is a [re-frame](https://github.com/day8/re-frame) app (ClojureScript, React 19 via
|
|
[Reagent](https://reagent-project.github.io/)) built with [shadow-cljs](https://github.com/thheller/shadow-cljs).
|
|
It's a small calculator form that calls `GET /api/add` and shows the sum (or the server's
|
|
validation error).
|
|
|
|
shadow-cljs compiles it into `resources/public/js/` (git-ignored). The server serves that
|
|
directory at `/js`, and serves `resources/public/index.html`, the shell that mounts the app, at `/`.
|
|
|
|
| Task | What it does |
|
|
|------|--------------|
|
|
| `script/ui-build` | Optimized release build into `resources/public/js` |
|
|
| `script/ui-watch` | Rebuilds on every change, with hot reload; run `script/server` alongside and refresh the page |
|
|
|
|
The Docker image builds the UI in its own stage, so `docker build` needs no local Node.
|
|
|
|
## Development
|
|
|
|
Every task is a bash script in `script/`. Start an nREPL server (with CIDER middleware) on the port in `.nrepl-port`, or `3000` if that
|
|
file doesn't exist:
|
|
|
|
```bash
|
|
script/repl
|
|
```
|
|
|
|
### Tests
|
|
|
|
| Task | What it does |
|
|
|------|--------------|
|
|
| `script/unit-test` | Runs the Clojure tests in `test/` |
|
|
| `script/integration-test` | Builds the app image, starts it on a random port, runs the [integration suite](integration-test/README.md) against it, then tears it down |
|
|
| `script/test` | Unit tests, then integration tests (stops at the first failure) |
|
|
| `script/docker-unit-test` | Same as `script/unit-test`, but inside the app image (Docker only) |
|
|
|
|
### Coverage
|
|
|
|
Line coverage via [Cloverage](https://github.com/cloverage/cloverage):
|
|
|
|
| Task | Output |
|
|
|------|--------|
|
|
| `script/unit-coverage` | `target/coverage/unit/` |
|
|
| `script/integration-coverage` | `target/coverage/integration/` |
|
|
| `script/coverage` | Runs both, then writes the merged report to `target/coverage/merged/` |
|
|
| `script/docker-unit-coverage`, `script/docker-coverage-report` | Dockerized versions of the unit run and the merge step, so `script/docker-unit-coverage`, `script/integration-coverage`, `script/docker-coverage-report` is `script/coverage` with no local Clojure or Babashka (this is what CI runs) |
|
|
|
|
Each report directory has an `index.html` and an `lcov.info`. See
|
|
[integration-test/README.md](integration-test/README.md) for how integration coverage is
|
|
collected.
|
|
|
|
|
|
## Project layout
|
|
|
|
```
|
|
src/tbd/
|
|
core.clj Router, Ring app, and server startup
|
|
<group>/routes.clj Each route group (health, math, ...) owns its route subtree
|
|
<group>/core.clj Business logic for the group, with no HTTP concerns
|
|
ui/ ClojureScript re-frame app (shadow-cljs project); ui/src/tbd/ui/{db,events,subs,views,core}.cljs
|
|
resources/public/ index.html (the shell served at /) and js/ (compiled UI output, git-ignored)
|
|
test/ Unit tests
|
|
integration-test/ Dockerized integration tests and coverage harness
|
|
script/ Bash entry points (server, ui-build, test, coverage, repl, ...) and coverage helpers
|
|
```
|
|
|
|
To add a new group, create `tbd.<group>.routes` with a `routes` fn that returns a reitit route
|
|
vector, then add it to the router in `src/tbd/core.clj`.
|