gamertan
3eee0b542c
Resolve the immutable Beta 1 runtime first, verify the exact compiler identity on Linux and Windows, and commit generated outputs from the released ABI. Material implementation and review were assisted by OpenAI Codex. Cole Speelman reviewed the public tutorial and accepts human responsibility. Signed-off-by: Cole Speelman <crspeelman@gmail.com>
104 lines
4.3 KiB
Markdown
104 lines
4.3 KiB
Markdown
<!-- SPDX-License-Identifier: 0BSD -->
|
||
|
||
# Sandwich Hime tutorial starter
|
||
|
||
This is the runnable companion to the official
|
||
[Walk the path tutorial](https://sandwichhime.com/docs/tutorial/). The website
|
||
owns the lesson; this repository is the small application you can clone, run,
|
||
take apart, and turn into something of your own. It takes the lesson's minimal
|
||
`Link` model one small step further with a described `Trail` and adds visible
|
||
per-request proof, while preserving the same component structure.
|
||
|
||
**Use this, change it, or don’t—we’re just glad you’re here with us.**
|
||
|
||
The starter demonstrates the boundary plainly:
|
||
|
||
- Hime-san compiles three typed `.sando` templates into committed Go during
|
||
development.
|
||
- `Badge`, `Home`, and `Layout` nest through the same `sando.Component`
|
||
contract.
|
||
- An ordinary `net/http` handler builds the trail list and typed view data on
|
||
every request.
|
||
- `?name=` is untrusted input and is contextually escaped by generated code.
|
||
- Each successful response contains a fresh UTC timestamp and process-local
|
||
request number, uses `Cache-Control: no-store`, and reports buffered render
|
||
time through `Server-Timing`.
|
||
- Production imports the Apache-2.0 `sando` runtime, not the compiler.
|
||
|
||
## Walk the path with Beta 1
|
||
|
||
Install Go 1.25 or newer, then resolve the tiny runtime before installing the
|
||
immutable classroom compiler:
|
||
|
||
```sh
|
||
git clone https://gitea.speelman.ca/gamertan/sandwich-hime-tutorial.git
|
||
cd sandwich-hime-tutorial
|
||
GOWORK=off go mod download gamertan.com/sandwich-hime/sando@v1.0.0-beta.1
|
||
go install gamertan.com/sandwich-hime/cmd/himesan@v1.0.0-beta.1
|
||
./scripts/verify.sh
|
||
GOWORK=off go run ./cmd/site
|
||
```
|
||
|
||
On Windows PowerShell, use the native verifier:
|
||
|
||
```powershell
|
||
git clone https://gitea.speelman.ca/gamertan/sandwich-hime-tutorial.git
|
||
Set-Location sandwich-hime-tutorial
|
||
$env:GOWORK = "off"
|
||
go mod download gamertan.com/sandwich-hime/sando@v1.0.0-beta.1
|
||
go install gamertan.com/sandwich-hime/cmd/himesan@v1.0.0-beta.1
|
||
.\scripts\verify.ps1
|
||
go run ./cmd/site
|
||
```
|
||
|
||
Make sure Go's install directory—normally `$(go env GOPATH)/bin`—is on
|
||
`PATH`, or set `HIMESAN_BIN` to the full compiler path before running either
|
||
verifier. The starter deliberately runs with `GOWORK=off`: it proves the
|
||
application resolves the published Apache-2.0 runtime rather than a neighboring
|
||
development checkout. The verification scripts also reject any compiler or
|
||
runtime version other than `v1.0.0-beta.1`.
|
||
|
||
Beta 1 is intended for classrooms, learning, prototypes, and evaluation. Its
|
||
interfaces may still change before final v1. Linux and Windows have been
|
||
maintainer-tested; macOS is provisional while native maintainer testing is
|
||
pending. Useful Mac compatibility reports are welcome on canonical Gitea.
|
||
|
||
Open [http://127.0.0.1:8080/?name=Hime-san](http://127.0.0.1:8080/?name=Hime-san),
|
||
refresh it, and watch the request number and UTC time change. Then try:
|
||
|
||
```text
|
||
http://127.0.0.1:8080/?name=<script>alert("no")</script>
|
||
```
|
||
|
||
The browser displays those characters as text. They do not become markup or
|
||
script. The tests also prove that an ordinary `javascript:` URL is rejected at
|
||
render time.
|
||
|
||
## Project map
|
||
|
||
```text
|
||
cmd/site/main.go application-owned listener
|
||
internal/server/handler.go router, typed request data, and HTTP policy
|
||
internal/views/views.go typed template contracts
|
||
internal/views/*.sando templates people edit
|
||
internal/views/*.sando.go committed generated Go
|
||
scripts/verify.sh generation, tests, build, and dependency gate
|
||
scripts/verify.ps1 the same gate for native Windows PowerShell
|
||
```
|
||
|
||
The application owns the server, routing, headers, data, and deployment.
|
||
Sandwich Hime owns template compilation; `sando` owns the tiny runtime render
|
||
contract. Read the [language and security documentation](https://sandwichhime.com/docs/)
|
||
before accepting real user content.
|
||
|
||
## What the verification gate proves
|
||
|
||
`./scripts/verify.sh` and `scripts/verify.ps1` check committed output, generate
|
||
twice and compare digests, run all tests and `go vet`, build the server into a
|
||
temporary directory, and inspect its Go dependency graph. The only production
|
||
Sandwich Hime package allowed by that graph is
|
||
`gamertan.com/sandwich-hime/sando`.
|
||
|
||
The human-authored starter is [0BSD](LICENSES.md), specifically so copying it
|
||
does not drag a complicated license conversation into your application.
|