diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml index 1c1737d..1636318 100644 --- a/.github/workflows/ci.yml +++ b/.github/workflows/ci.yml @@ -69,6 +69,37 @@ jobs: grep -q 'href="/jolt-project/css/screen.css"' "$root/_site/guide/index.html" \ || { echo "jolt build lost the base path"; exit 1; } + # serve binds with ring-chez-adapter under jolt (serve.jolt) and with + # http-kit under bb (serve.clj). This starts the jolt one on a free port + # and checks it answers under the base path, 404s outside it, and + # returns a binary asset byte for byte. + - name: Serve under jolt + run: | + set -euo pipefail + root="$(mktemp -d)/serve-project" + mkdir -p "$root/docs/guide" "$root/docs/media" + printf '# Serve\n\nServed by jolt.\n' > "$root/docs/guide/index.md" + printf '{:base-path "/serve-project" :asset-dirs ["media"]}\n' > "$root/docs/site.edn" + head -c 4096 /dev/urandom > "$root/docs/media/blob.bin" + port="$(python3 -c 'import socket; s = socket.socket(); s.bind(("127.0.0.1", 0)); print(s.getsockname()[1])')" + jolt run serve "$root" "$port" > serve.log 2>&1 & + pid=$! + trap 'kill "$pid" 2>/dev/null || true' EXIT + for _ in $(seq 1 120); do + grep -q '^Serving ' serve.log && break + kill -0 "$pid" 2>/dev/null || { cat serve.log; echo "jolt run serve exited"; exit 1; } + sleep 1 + done + grep -q '^Serving ' serve.log || { cat serve.log; echo "jolt run serve never started"; exit 1; } + base="http://127.0.0.1:$port" + test "$(curl -s -o /dev/null -w '%{http_code}' "$base/serve-project/")" = 200 \ + || { echo "homepage not served under the base path"; exit 1; } + test "$(curl -s -o /dev/null -w '%{http_code}' "$base/elsewhere/")" = 404 \ + || { echo "a path outside the base path was not a 404"; exit 1; } + curl -s "$base/serve-project/media/blob.bin" | cmp - "$root/docs/media/blob.bin" \ + || { echo "binary asset changed in transit"; exit 1; } + echo "jolt run serve works" + # The tests build sites from fixtures, which proves the renderer but # not that the engine works against a real project laid out on disk. # This builds one end to end and checks the properties that actually diff --git a/README.md b/README.md index 9edadce..59a23a8 100644 --- a/README.md +++ b/README.md @@ -3,11 +3,11 @@ The static-site generator behind jlt-commons project documentation. A project writes markdown, and this turns it into a site that GitHub Pages serves. -It is a small babashka program, and `build`, `clean` and `test` also run -under `jolt` (jolt reads `bb.edn` tasks directly). `serve` still needs `bb`: -it binds the port with `http-kit`, which jolt doesn't have. External dependencies -(`markdown-clj`, `selmer`, and the `jolt-lang/yaml`/`jolt-lang/time` shims -that make those two resolve under jolt) are fetched on first run. +It is a small Clojure program that runs on `jolt`, which reads the tasks in +`bb.edn` directly. External dependencies (`markdown-clj`, `selmer`, the +`jolt-lang/yaml`/`jolt-lang/time` shims that make those two resolve under +jolt, and `ring-chez-adapter` for the preview server) are fetched on first +run. Every task also still runs under babashka as `bb `. ## The idea @@ -91,19 +91,19 @@ callout. ```bash jolt run build ../your-project # generate ../your-project/_site/ jolt run clean ../your-project # delete the build output -jolt test # the test suite (or bb test) -bb serve ../your-project # build, then serve, honouring :base-path -bb serve ../your-project 4000 +jolt run test # the test suite +jolt run serve ../your-project # build, then serve, honouring :base-path +jolt run serve ../your-project 4000 ``` -`build`, `clean` and `test` run under either tool. Under `jolt` it's -`jolt run `, not bare `jolt `: `build` collides with jolt's own -native `build -m NS` compiler subcommand. `serve` stays `bb`-only, since it -uses `http-kit`. +Use `jolt run `, not bare `jolt `, because `build` collides with +jolt's own native `build -m NS` compiler subcommand. The preview server binds +with `ring-chez-adapter` under jolt and with `http-kit` under bb, so +`bb serve` works the same way. `_site/` is generated. Add it to the project's `.gitignore`. -`bb serve` mounts the build at the project's configured `:base-path`, so the +`jolt run serve` mounts the build at the project's configured `:base-path`, so the local URL matches the deployed one. A project with `:base-path "/your-project"` previews at `http://localhost:3000/your-project/`, and the server prints that full URL when it starts. A root-hosted project is served at `/` as before. diff --git a/bb.edn b/bb.edn index 477c4d3..5cca56a 100644 --- a/bb.edn +++ b/bb.edn @@ -41,7 +41,12 @@ ;; unchanged (bb already has real java.time; this just adds tick's ;; API on top of it). io.github.jolt-lang/time {:git/url "https://github.com/jolt-lang/time.git" - :git/sha "cdd785069e0e08a16c1ea9aae60f9532de21fad8"}} + :git/sha "cdd785069e0e08a16c1ea9aae60f9532de21fad8"} + ;; The HTTP server behind `serve` under jolt. Only site/serve.jolt + ;; requires it, and bb never loads that file (bb's serve.clj uses + ;; http-kit, which bb bundles). + io.github.jolt-lang/ring-chez-adapter {:git/url "https://github.com/jolt-lang/ring-chez-adapter.git" + :git/sha "387cf67ea7b6a8573c6ee6abca6026a45bc3b6bf"}} :tasks {;; tick.core first, unconditionally -- see the io.github.jolt-lang/time ;; comment above :deps. Everything after it in this list, and every @@ -53,20 +58,19 @@ (def project-dir (fn [] (or (first *command-line-args*) - (do (println "Usage: bb [...]") - (println " e.g. bb serve ../raylib-jlt") + (do (println "Usage: jolt run [...]") + (println " e.g. jolt run serve ../raylib-jlt") (System/exit 1))))) info {:doc "What this is and how to point it at a project" :task (do (println "docs-engine — the jlt-commons documentation site generator\n") - (println " jolt run build generate /_site/") - (println " jolt run clean delete /_site/") - (println " jolt test run the test suite") - (println " bb serve [port] build, then serve at localhost:3000\n") - (println "build/clean/test run under either tool (jolt run , not bare jolt :") - (println "build collides with jolt's own build -m NS subcommand). serve stays") - (println "bb-only: it uses http-kit.\n") + (println " jolt run build generate /_site/") + (println " jolt run clean delete /_site/") + (println " jolt run test run the test suite") + (println " jolt run serve [port] build, then serve at localhost:3000\n") + (println "Use jolt run , not bare jolt : build collides with jolt's own") + (println "build -m NS subcommand. Every task also runs under babashka as bb .\n") (println "A project configures itself in docs/site.edn. See README.md."))} test {:doc "Run the full test suite" @@ -78,15 +82,15 @@ :task (let [{:keys [fail error]} (t/run-tests 'site.markdown-test 'site.project-test 'site.core-test 'site.search-test)] (when (pos? (+ fail error)) (System/exit 1)))} - build {:doc "Generate a project's site into its _site/ (bb build , or jolt run build )" + build {:doc "Generate a project's site into its _site/ (jolt run build )" :requires ([site.core :as core]) :task (core/generate! (project/resolve-project (project-dir)))} - clean {:doc "Delete a project's _site/ build output (bb clean , or jolt run clean )" + clean {:doc "Delete a project's _site/ build output (jolt run clean )" :requires ([site.core :as core]) :task (core/clean! (project/resolve-project (project-dir)))} - serve {:doc "Build, then serve a project locally (bb serve [port], default 3000)" + serve {:doc "Build, then serve a project locally (jolt run serve [port], default 3000)" :requires ([site.serve :as serve]) :task (serve/serve! (project/resolve-project (project-dir)) (second *command-line-args*))}}} diff --git a/src/site/core.clj b/src/site/core.clj index 27e93c9..a02b2f9 100644 --- a/src/site/core.clj +++ b/src/site/core.clj @@ -380,7 +380,8 @@ ;; Everything below builds a plain Ring handler `(fn [req]) -> {:status ;; :headers :body}` and touches no HTTP-server library at all, so it costs ;; build/clean/test nothing. site.serve is the thin wrapper that actually -;; binds a port, with org.httpkit.server, so `serve` runs under bb only. +;; binds a port: serve.clj with org.httpkit.server under bb/JVM, and +;; serve.jolt with ring-chez.adapter under jolt. ;; Splitting it this way is what makes build/clean/test loadable under jolt ;; at all — org.httpkit.server isn't resolvable there, and previously every ;; task here required it via this namespace regardless of whether it ever diff --git a/src/site/serve.clj b/src/site/serve.clj index 76e605a..7448720 100644 --- a/src/site/serve.clj +++ b/src/site/serve.clj @@ -4,8 +4,9 @@ library involved at all; this namespace is the thin wrapper around org.httpkit.server that turns it into a running server. - http-kit isn't available under jolt, so `serve` is bb-only; no other - task requires this namespace." + Under jolt, site/serve.jolt replaces this file and binds with + ring-chez.adapter instead. No task other than `serve` requires this + namespace." (:require [org.httpkit.server :as hk] [site.core :as core])) diff --git a/src/site/serve.jolt b/src/site/serve.jolt new file mode 100644 index 0000000..4e9663d --- /dev/null +++ b/src/site/serve.jolt @@ -0,0 +1,23 @@ +(ns site.serve + "The local preview server's jolt half. jolt resolves .jolt before + .clj, so under jolt this file replaces site/serve.clj, and bb and + the JVM never see it. site.core builds the Ring handler; this namespace + binds the port with ring-chez.adapter, which runs over jolt's own + sockets, where serve.clj uses http-kit." + (:require [ring-chez.adapter :as adapter] + [site.core :as core])) + +(defn serve! + "Builds, then serves output-dir at http://localhost: + until interrupted." + [project port-str] + (core/generate! project) + (let [port (Integer/parseInt (or port-str "3000")) + output-dir (:output-dir project) + base (core/base-path (:base-path project))] + ;; ring-chez binds 127.0.0.1 by default; :host says so explicitly, since + ;; this is a local-only preview server. + (adapter/run-server (core/make-static-handler output-dir base) + {:port port :host "127.0.0.1"}) + (println (str "Serving " output-dir " at http://localhost:" port base "/")) + @(promise)))