Reference implementation for HTTP/Minima;
shindakun.net
1# HTTP/Minimal Reference Server
2
3A reference implementation of an HTTP/Minimal compliant server in Go.
4
5## Features
6
7- Serves Markdown files with proper `text/markdown` Content-Type
8- Content negotiation: serves HTML to browsers, Markdown to clients that request it
9- Strips raw HTML from Markdown sources (compliance enforcement)
10- YAML front matter support for metadata
11- `/.well-known/http-minimal` endpoint
12- Method restrictions (GET/HEAD only)
13- Forbidden header removal
14- Designed to run behind nginx/Caddy reverse proxy
15
16## Quick Start
17
18```bash
19# Install dependencies
20go mod download
21
22# Run the server
23go run main.go -dir ./content -port 8080
24```
25
26## Usage
27
28```
29Usage of http-minimal-server:
30 -port string
31 Listen port (default "8080")
32 -base-url string
33 Base URL for the site (default "http://localhost:8080")
34 -contact string
35 Contact email for /.well-known/http-minimal
36 -dir string
37 Content directory (default "./content")
38 -template string
39 HTML template file (default: built-in template)
40```
41
42## Content Directory Structure
43
44```
45content/
46├── index.md # Served at /
47├── about.md # Served at /about
48├── posts/
49│ ├── index.md # Served at /posts
50│ └── first.md # Served at /posts/first
51└── images/
52 └── logo.png # Served at /images/logo.png
53```
54
55## Front Matter
56
57Documents can include YAML front matter:
58
59```markdown
60---
61title: My Page Title
62author: Jane Doe
63date: 2025-12-27
64lang: en
65license: CC0-1.0
66---
67
68# Content starts here
69```
70
71## Content Negotiation
72
73The server respects the `Accept` header:
74
75```bash
76# Get HTML (default for browsers)
77curl http://localhost:8080/
78
79# Get raw Markdown
80curl -H "Accept: text/markdown" http://localhost:8080/
81
82# Check compliance policy
83curl http://localhost:8080/.well-known/http-minimal
84```
85
86## Compliance
87
88The server enforces HTTP/Minimal compliance:
89
90- **Methods**: Only GET and HEAD are allowed
91- **Response Headers**: Forbidden headers (Set-Cookie, WWW-Authenticate, etc.) are removed
92- **Content**: Raw HTML is stripped from Markdown before serving
93- **Validation**: Images without alt text are logged as warnings
94
95## Extending
96
97### Custom HTML Template
98
99Modify the `htmlTemplate` constant in `main.go` to customize the HTML rendering. Keep it minimal - no JavaScript, no external resources except same-origin images.
100
101### Adding Middleware
102
103The server implements `http.Handler`, so you can wrap it with standard Go middleware:
104
105```go
106server, _ := NewServer(config)
107handler := loggingMiddleware(server)
108http.ListenAndServe(":8080", handler)
109```
110
111### Integration with AT Protocol
112
113The `/.well-known/http-minimal` endpoint could be extended to include:
114
115```json
116{
117 "http_minimal": "0.1",
118 "compliant": true,
119 "did": "did:plc:example",
120 "atproto_pds": "https://bsky.social"
121}
122```
123
124## Dependencies
125
126- [goldmark](https://github.com/yuin/goldmark) - Markdown parser (CommonMark + GFM)
127- [yaml.v3](https://gopkg.in/yaml.v3) - YAML front matter parsing
128
129## License
130
131This reference implementation is released under CC0 1.0 Universal - no rights reserved.