115 lines
4.6 KiB
Markdown
115 lines
4.6 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 RC.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-rc.1
|
||
go install gamertan.com/sandwich-hime/cmd/himesan@v1.0.0-rc.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-rc.1
|
||
go install gamertan.com/sandwich-hime/cmd/himesan@v1.0.0-rc.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 require compiler
|
||
`v1.0.0-rc.1` and runtime `v1.0.0-rc.1` exactly.
|
||
|
||
If an earlier compiler-first attempt reports that the parent module does not
|
||
contain `gamertan.com/sandwich-hime/sando`, repair only that module selection:
|
||
|
||
```sh
|
||
GOWORK=off go mod download gamertan.com/sandwich-hime/sando@v1.0.0-rc.1
|
||
GOWORK=off go get gamertan.com/sandwich-hime/sando@v1.0.0-rc.1
|
||
```
|
||
|
||
Then run the verifier again. You do not need to clear your whole Go module
|
||
cache.
|
||
|
||
RC.1 freezes the intended v1 compiler/runtime contract while public dogfooding
|
||
and release-blocking corrections continue. Linux/amd64 and Apple Silicon
|
||
macOS/arm64 are maintained native targets. Useful compatibility reports remain
|
||
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.
|