Something went wrong. Try again.
Reference implementation for HTTP/Minima;
Something went wrong. Try again.
httpmini-refserver main.go
20 kB · 688 lines
Go
at main
123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193194195196197198199200201202203204205206207208209210211212213214215216217218219220221222223224225226227228229230231232233234235236237238239240241242243244245246247248249250251252253254255256257258259260261262263264265266267268269270271272273274275276277278279280281282283284285286287288289290291292293294295296297298299300301302303304305306307308309310311312313314315316317318319320321322323324325326327328329330331332333334335336337338339340341342343344345346347348349350351352353354355356357358359360361362363364365366367368369370371372373374375376377378379380381382383384385386387388389390391392393394395396397398399400401402403404405406407408409410411412413414415416417418419420421422423424425426427428429430431432433434435436437438439440441442443444445446447448449450451452453454455456457458459460461462463464465466467468469470471472473474475476477478479480481482483484485486487488489490491492493494495496497498499500501502503504505506507508509510511512513514515516517518519520521522523524525526527528529530531532533534535536537538539540541542543544545546547548549550551552553554555556557558559560561562563564565566567568569570571572573574575576577578579580581582583584585586587588589590591592593594595596597598599600601602603604605606607608609610611612613614615616617618619620621622623624625626627628629630631632633634635636637638639640641642643644645646647648649650651652653654655656657658659660661662663664665666667668669670671672673674675676677678679680681682683684685686687688689// HTTP/Minimal Reference Server// A compliant server implementation for the HTTP/Minimal specification.//// Usage:// go run main.go -dir ./content -port 8080//// The server will:// - Serve Markdown files from the content directory// - Content-negotiate between text/markdown and text/html// - Strip raw HTML from Markdown before serving// - Validate and enforce HTTP/Minimal constraints// - Serve /.well-known/http-minimal policy endpoint
package main
import ( "bytes" "encoding/json" "flag" "fmt" "html/template" "io" "log" "mime" "net/http" "os" "path/filepath" "regexp" "strings"
"github.com/yuin/goldmark" "github.com/yuin/goldmark/extension" "github.com/yuin/goldmark/parser" "github.com/yuin/goldmark/renderer/html" "gopkg.in/yaml.v3")
// Config holds server configurationtype Config struct { Port string ContentDir string TemplateFile string BaseURL string Contact string}
// FrontMatter represents YAML front matter in Markdown documentstype FrontMatter struct { Title string `yaml:"title"` Author string `yaml:"author"` Date string `yaml:"date"` Lang string `yaml:"lang"` License string `yaml:"license"` Description string `yaml:"description"`}
// WellKnown represents the /.well-known/http-minimal responsetype WellKnown struct { HTTPMinimal string `json:"http_minimal"` Compliant bool `json:"compliant"` Scope string `json:"scope"` Contact string `json:"contact,omitempty"`}
// Server implements an HTTP/Minimal compliant servertype Server struct { config Config markdown goldmark.Markdown htmlTmpl *template.Template}
// defaultHTMLTemplate is the built-in fallback template for rendering Markdown to browsersconst defaultHTMLTemplate = `<!DOCTYPE html><html lang="{{.Lang}}"><head> <meta charset="utf-8"> <meta name="viewport" content="width=device-width, initial-scale=1"> <title>{{.Title}}</title> <!-- OpenGraph --> <meta property="og:title" content="{{.Title}}"> <meta property="og:type" content="article"> {{if .URL}}<meta property="og:url" content="{{.URL}}">{{end}} {{if .Description}}<meta property="og:description" content="{{.Description}}">{{end}} <meta property="og:locale" content="{{.Lang}}"> {{if .Author}}<meta name="author" content="{{.Author}}">{{end}} <style> :root { --text: #1a1a1a; --bg: #fefefe; --link: #0066cc; --code-bg: #f4f4f4; } @media (prefers-color-scheme: dark) { :root { --text: #e0e0e0; --bg: #1a1a1a; --link: #6db3f2; --code-bg: #2d2d2d; } } * { box-sizing: border-box; } body { font-family: -apple-system, BlinkMacSystemFont, "Segoe UI", Roboto, Oxygen, Ubuntu, sans-serif; font-size: 18px; line-height: 1.6; color: var(--text); background: var(--bg); max-width: 65ch; margin: 0 auto; padding: 2rem 1rem; } h1, h2, h3, h4, h5, h6 { line-height: 1.2; margin-top: 1.5em; } a { color: var(--link); } pre, code { font-family: "SF Mono", Consolas, "Liberation Mono", Menlo, monospace; font-size: 0.9em; background: var(--code-bg); } pre { padding: 1rem; overflow-x: auto; } code { padding: 0.1em 0.3em; border-radius: 3px; } pre code { padding: 0; background: none; } blockquote { border-left: 3px solid var(--link); margin-left: 0; padding-left: 1rem; font-style: italic; } img { max-width: 100%; height: auto; } hr { border: none; border-top: 1px solid var(--text); opacity: 0.2; } table { border-collapse: collapse; width: 100%; } th, td { border: 1px solid var(--text); padding: 0.5rem; text-align: left; } th { opacity: 0.8; } </style></head><body>{{.Content}}</body></html>`
func main() { config := Config{}
flag.StringVar(&config.Port, "port", "8080", "Listen port") flag.StringVar(&config.ContentDir, "dir", "./content", "Content directory") flag.StringVar(&config.TemplateFile, "template", "", "HTML template file (default: built-in template)") flag.StringVar(&config.BaseURL, "base-url", "http://localhost:8080", "Base URL for the site") flag.StringVar(&config.Contact, "contact", "", "Contact email for /.well-known/http-minimal") flag.Parse()
server, err := NewServer(config) if err != nil { log.Fatalf("Failed to create server: %v", err) }
log.Printf("HTTP/Minimal server starting on %s", config.Port) log.Printf("Serving content from: %s", config.ContentDir) log.Fatal(http.ListenAndServe(":"+config.Port, server))}
// TemplateViolation represents a compliance issue found in a templatetype TemplateViolation struct { Rule string Details string}
// validateTemplate checks a template for HTTP/Minimal compliance violationsfunc validateTemplate(content string) []TemplateViolation { var violations []TemplateViolation contentLower := strings.ToLower(content)
// Check for forbidden elements forbiddenElements := []struct { pattern string rule string }{ {"<script", "No JavaScript: <script> tags are forbidden"}, {"<iframe", "No embedded content: <iframe> tags are forbidden"}, {"<form", "No data collection: <form> tags are forbidden"}, {"<embed", "No embedded content: <embed> tags are forbidden"}, {"<object", "No embedded content: <object> tags are forbidden"}, {"<applet", "No embedded content: <applet> tags are forbidden"}, }
for _, elem := range forbiddenElements { if strings.Contains(contentLower, elem.pattern) { violations = append(violations, TemplateViolation{ Rule: elem.rule, Details: fmt.Sprintf("Found '%s' in template", elem.pattern), }) } }
// Check for inline JavaScript event handlers eventHandlers := []string{ "onclick", "onload", "onerror", "onmouseover", "onmouseout", "onsubmit", "onfocus", "onblur", "onchange", "onkeydown", "onkeyup", "onkeypress", "ondblclick", "onscroll", "onresize", } for _, handler := range eventHandlers { pattern := regexp.MustCompile(`(?i)\s` + handler + `\s*=`) if pattern.MatchString(content) { violations = append(violations, TemplateViolation{ Rule: "No JavaScript: inline event handlers are forbidden", Details: fmt.Sprintf("Found '%s' attribute in template", handler), }) } }
// Check for javascript: URLs if strings.Contains(contentLower, "javascript:") { violations = append(violations, TemplateViolation{ Rule: "No JavaScript: javascript: URLs are forbidden", Details: "Found 'javascript:' URL in template", }) }
// Check for common tracking/analytics patterns trackingPatterns := []struct { pattern string name string }{ {"google-analytics.com", "Google Analytics"}, {"googletagmanager.com", "Google Tag Manager"}, {"facebook.net", "Facebook tracking"}, {"plausible.io", "Plausible Analytics"}, {"analytics.", "Analytics service"}, {"tracking.", "Tracking service"}, {"pixel.", "Tracking pixel"}, {"beacon.", "Tracking beacon"}, }
for _, tp := range trackingPatterns { if strings.Contains(contentLower, tp.pattern) { violations = append(violations, TemplateViolation{ Rule: "No tracking: external tracking services are forbidden", Details: fmt.Sprintf("Found reference to %s (%s)", tp.name, tp.pattern), }) } }
// Check for external stylesheets (could be tracking vectors) externalCSSPattern := regexp.MustCompile(`(?i)<link[^>]+rel\s*=\s*["']?stylesheet["']?[^>]+href\s*=\s*["']?https?://`) if externalCSSPattern.MatchString(content) { violations = append(violations, TemplateViolation{ Rule: "External resources: external stylesheets may enable tracking", Details: "Found external stylesheet link (warning)", }) }
// Check for external fonts (could be tracking vectors) if strings.Contains(contentLower, "fonts.googleapis.com") || strings.Contains(contentLower, "fonts.gstatic.com") { violations = append(violations, TemplateViolation{ Rule: "External resources: external fonts may enable tracking", Details: "Found Google Fonts reference (warning)", }) }
return violations}
// NewServer creates a new HTTP/Minimal serverfunc NewServer(config Config) (*Server, error) { // Initialize Goldmark with GFM extensions md := goldmark.New( goldmark.WithExtensions( extension.GFM, // Tables, strikethrough, autolinks extension.Footnote, // Footnotes ), goldmark.WithParserOptions( parser.WithAutoHeadingID(), ), goldmark.WithRendererOptions( html.WithUnsafe(), // We'll strip HTML ourselves for validation ), )
// Load HTML template var tmpl *template.Template var tmplContent string if config.TemplateFile != "" { // Load from file content, err := os.ReadFile(config.TemplateFile) if err != nil { return nil, fmt.Errorf("failed to read template file: %w", err) } tmplContent = string(content) tmpl, err = template.New("page").Parse(tmplContent) if err != nil { return nil, fmt.Errorf("failed to parse template file: %w", err) } log.Printf("Using custom template: %s", config.TemplateFile) } else { // Use built-in default tmplContent = defaultHTMLTemplate var err error tmpl, err = template.New("page").Parse(tmplContent) if err != nil { return nil, fmt.Errorf("failed to parse default template: %w", err) } }
// Validate template for HTTP/Minimal compliance violations := validateTemplate(tmplContent) if len(violations) > 0 { log.Printf("Template validation found %d issue(s):", len(violations)) hasError := false for _, v := range violations { // Warnings don't block startup, errors do isWarning := strings.Contains(v.Details, "(warning)") if isWarning { log.Printf(" WARNING: %s - %s", v.Rule, v.Details) } else { log.Printf(" ERROR: %s - %s", v.Rule, v.Details) hasError = true } } if hasError { return nil, fmt.Errorf("template validation failed: %d compliance violation(s) found", len(violations)) } }
return &Server{ config: config, markdown: md, htmlTmpl: tmpl, }, nil}
// ServeHTTP implements http.Handlerfunc (s *Server) ServeHTTP(w http.ResponseWriter, r *http.Request) { // Enforce method restrictions if r.Method != http.MethodGet && r.Method != http.MethodHead { http.Error(w, "Method not allowed", http.StatusMethodNotAllowed) return }
// Strip forbidden request headers (log them for debugging) if cookie := r.Header.Get("Cookie"); cookie != "" { log.Printf("NOTICE: Stripped Cookie header from request to %s", r.URL.Path) }
// Route handling switch { case r.URL.Path == "/.well-known/http-minimal": s.handleWellKnown(w, r) default: s.handleContent(w, r) }}
// handleWellKnown serves the /.well-known/http-minimal endpointfunc (s *Server) handleWellKnown(w http.ResponseWriter, r *http.Request) { wellKnown := WellKnown{ HTTPMinimal: "0.1", Compliant: true, Scope: "/", Contact: s.config.Contact, }
w.Header().Set("Content-Type", "application/json; charset=utf-8") w.Header().Set("Cache-Control", "max-age=86400") s.setMinimalHeaders(w)
json.NewEncoder(w).Encode(wellKnown)}
// handleContent serves Markdown content with content negotiationfunc (s *Server) handleContent(w http.ResponseWriter, r *http.Request) { // Clean and resolve the path urlPath := filepath.Clean(r.URL.Path) if urlPath == "/" || urlPath == "." { urlPath = "/index" }
// Try to find the markdown file mdPath := filepath.Join(s.config.ContentDir, urlPath+".md") if _, err := os.Stat(mdPath); os.IsNotExist(err) { // Try without .md extension (maybe it's a directory with index.md) indexPath := filepath.Join(s.config.ContentDir, urlPath, "index.md") if _, err := os.Stat(indexPath); err == nil { mdPath = indexPath } else { // Check if it's a static file (images, etc.) staticPath := filepath.Join(s.config.ContentDir, urlPath) if info, err := os.Stat(staticPath); err == nil && !info.IsDir() { s.serveStaticFile(w, r, staticPath) return } http.NotFound(w, r) return } }
// Read the markdown file content, err := os.ReadFile(mdPath) if err != nil { log.Printf("Error reading file %s: %v", mdPath, err) http.Error(w, "Internal server error", http.StatusInternalServerError) return }
// Parse front matter and content frontMatter, body := s.parseFrontMatter(content)
// Strip raw HTML from markdown (HTTP/Minimal compliance) cleanBody := s.stripRawHTML(body)
// Validate the document if errors := s.validateDocument(cleanBody); len(errors) > 0 { log.Printf("Validation warnings for %s: %v", mdPath, errors) }
// Content negotiation accept := r.Header.Get("Accept") wantsMarkdown := s.prefersMarkdown(accept)
// Get file modification time for caching headers info, _ := os.Stat(mdPath) modTime := info.ModTime()
// Set common headers s.setMinimalHeaders(w) w.Header().Set("Last-Modified", modTime.UTC().Format(http.TimeFormat)) w.Header().Set("Cache-Control", "max-age=3600") w.Header().Set("Link", `</.well-known/http-minimal>; rel="profile"`)
if wantsMarkdown { // Serve raw markdown w.Header().Set("Content-Type", "text/markdown; charset=utf-8; variant=CommonMark") w.Write(cleanBody) } else { // Render to HTML for browsers s.renderHTML(w, r, frontMatter, cleanBody) }}
// serveStaticFile serves static files (images, etc.)func (s *Server) serveStaticFile(w http.ResponseWriter, r *http.Request, path string) { // Validate the file type is allowed ext := strings.ToLower(filepath.Ext(path)) allowedTypes := map[string]string{ ".jpg": "image/jpeg", ".jpeg": "image/jpeg", ".png": "image/png", ".gif": "image/gif", ".webp": "image/webp", ".avif": "image/avif", ".svg": "image/svg+xml", ".ico": "image/x-icon", }
contentType, allowed := allowedTypes[ext] if !allowed { http.Error(w, "Forbidden file type", http.StatusForbidden) return }
s.setMinimalHeaders(w) w.Header().Set("Content-Type", contentType) w.Header().Set("Cache-Control", "max-age=86400")
http.ServeFile(w, r, path)}
// parseFrontMatter extracts YAML front matter from markdown contentfunc (s *Server) parseFrontMatter(content []byte) (FrontMatter, []byte) { fm := FrontMatter{ Lang: "en", // Default language }
if !bytes.HasPrefix(content, []byte("---\n")) { return fm, content }
// Find the closing --- rest := content[4:] end := bytes.Index(rest, []byte("\n---\n")) if end == -1 { return fm, content }
// Parse YAML yamlContent := rest[:end] if err := yaml.Unmarshal(yamlContent, &fm); err != nil { log.Printf("Warning: failed to parse front matter: %v", err) return fm, content }
// Return content after front matter body := rest[end+5:] return fm, body}
// stripRawHTML removes raw HTML from Markdown contentfunc (s *Server) stripRawHTML(content []byte) []byte { // Pattern to match HTML tags htmlBlockPattern := regexp.MustCompile(`(?s)<[a-zA-Z][^>]*>.*?</[a-zA-Z]+>|<[a-zA-Z][^>]*/?>`)
// Pattern to match HTML comments commentPattern := regexp.MustCompile(`(?s)<!--.*?-->`)
result := commentPattern.ReplaceAll(content, []byte{}) result = htmlBlockPattern.ReplaceAll(result, []byte{})
return result}
// validateDocument checks for HTTP/Minimal compliancefunc (s *Server) validateDocument(content []byte) []string { var errors []string
// Check for remaining HTML (shouldn't exist after stripping, but double-check) if bytes.Contains(content, []byte("<script")) { errors = append(errors, "Document contains <script> tag") } if bytes.Contains(content, []byte("<iframe")) { errors = append(errors, "Document contains <iframe> tag") } if bytes.Contains(content, []byte("<form")) { errors = append(errors, "Document contains <form> tag") }
// Check for images without alt text imgPattern := regexp.MustCompile(`!\[\]\(`) if imgPattern.Match(content) { errors = append(errors, "Document contains images without alt text") }
return errors}
// prefersMarkdown checks if the client prefers markdown over HTMLfunc (s *Server) prefersMarkdown(accept string) bool { if accept == "" { return false }
// Parse Accept header types := strings.Split(accept, ",") for _, t := range types { mediaType, _, err := mime.ParseMediaType(strings.TrimSpace(t)) if err != nil { continue }
switch mediaType { case "text/markdown", "text/x-markdown": return true case "text/html", "application/xhtml+xml": return false case "*/*": // Wildcard - prefer HTML for browsers return false } }
return false}
// renderHTML renders markdown to HTML using the templatefunc (s *Server) renderHTML(w http.ResponseWriter, r *http.Request, fm FrontMatter, content []byte) { var htmlBuf bytes.Buffer if err := s.markdown.Convert(content, &htmlBuf); err != nil { log.Printf("Error converting markdown: %v", err) http.Error(w, "Internal server error", http.StatusInternalServerError) return }
// Set title from front matter or first heading title := fm.Title if title == "" { title = s.extractTitle(content) } if title == "" { title = "Untitled" }
lang := fm.Lang if lang == "" { lang = "en" }
// Build canonical URL pageURL := s.config.BaseURL + r.URL.Path
// Extract description from front matter or first paragraph description := fm.Description if description == "" { description = s.extractDescription(content) }
data := struct { Title string Lang string Content template.HTML URL string Description string Author string }{ Title: title, Lang: lang, Content: template.HTML(htmlBuf.String()), URL: pageURL, Description: description, Author: fm.Author, }
w.Header().Set("Content-Type", "text/html; charset=utf-8")
var pageBuf bytes.Buffer if err := s.htmlTmpl.Execute(&pageBuf, data); err != nil { log.Printf("Error executing template: %v", err) http.Error(w, "Internal server error", http.StatusInternalServerError) return }
io.Copy(w, &pageBuf)}
// extractDescription extracts the first paragraph from markdown contentfunc (s *Server) extractDescription(content []byte) string { lines := bytes.Split(content, []byte("\n")) var paragraph []byte inParagraph := false
for _, line := range lines { trimmed := bytes.TrimSpace(line)
// Skip headings, blank lines at start, and front matter markers if len(trimmed) == 0 { if inParagraph { break // End of first paragraph } continue } if bytes.HasPrefix(trimmed, []byte("#")) { continue } if bytes.HasPrefix(trimmed, []byte("---")) { continue } if bytes.HasPrefix(trimmed, []byte("-")) || bytes.HasPrefix(trimmed, []byte("*")) { if !inParagraph { continue // Skip list items at start } break }
// Found paragraph text inParagraph = true if len(paragraph) > 0 { paragraph = append(paragraph, ' ') } paragraph = append(paragraph, trimmed...) }
desc := string(paragraph) // Truncate to reasonable length for og:description if len(desc) > 200 { desc = desc[:197] + "..." } return desc}
// extractTitle extracts the first heading from markdown contentfunc (s *Server) extractTitle(content []byte) string { lines := bytes.Split(content, []byte("\n")) for _, line := range lines { line = bytes.TrimSpace(line) if bytes.HasPrefix(line, []byte("# ")) { return string(bytes.TrimPrefix(line, []byte("# "))) } } return ""}
// setMinimalHeaders sets headers required by HTTP/Minimal and removes forbidden onesfunc (s *Server) setMinimalHeaders(w http.ResponseWriter) { // Explicitly delete any forbidden headers that might be set by middleware w.Header().Del("Set-Cookie") w.Header().Del("WWW-Authenticate") w.Header().Del("Content-Security-Policy") w.Header().Del("X-Frame-Options") w.Header().Del("Refresh")
// Add security headers that don't conflict with the spec w.Header().Set("X-Content-Type-Options", "nosniff")}