Hugo Nijhuis
2db0628a89
Documents the host package covering: - Basic server setup with code example - Directory structure for WASM apps - Static file serving and SPA fallback - WASM MIME type configuration - Automatic gzip compression - Development vs production considerations Closes #3 Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
121 lines
2.4 KiB
Markdown
121 lines
2.4 KiB
Markdown
# Host Package
|
|
|
|
Static file server optimized for serving Iris WASM applications.
|
|
|
|
## Basic Setup
|
|
|
|
```go
|
|
package main
|
|
|
|
import (
|
|
"log"
|
|
"net/http"
|
|
|
|
"git.flowmade.one/flowmade-one/iris/host"
|
|
)
|
|
|
|
func main() {
|
|
server := host.New("public", "index.html")
|
|
log.Println("Server running on http://localhost:8080")
|
|
log.Fatal(http.ListenAndServe(":8080", server))
|
|
}
|
|
```
|
|
|
|
## Directory Structure
|
|
|
|
```
|
|
myapp/
|
|
├── server.go # Server code (above)
|
|
└── public/
|
|
├── index.html # Entry point
|
|
├── app.wasm # Compiled WASM binary
|
|
└── wasm_exec.js # Go WASM runtime
|
|
```
|
|
|
|
## Serving Static Files
|
|
|
|
The server serves files from the specified public directory. Any request path maps directly to files:
|
|
|
|
- `/` → `public/index.html`
|
|
- `/app.wasm` → `public/app.wasm`
|
|
- `/styles.css` → `public/styles.css`
|
|
|
|
**SPA Fallback**: Unknown paths and directories fall back to `index.html`, enabling client-side routing.
|
|
|
|
## WASM MIME Types
|
|
|
|
The server automatically sets correct MIME types for all common file types:
|
|
|
|
| Extension | MIME Type |
|
|
|-----------|-----------|
|
|
| `.wasm` | `application/wasm` |
|
|
| `.html` | `text/html; charset=utf-8` |
|
|
| `.js` | `application/javascript` |
|
|
| `.css` | `text/css` |
|
|
| `.json` | `application/json` |
|
|
| `.svg` | `image/svg+xml` |
|
|
|
|
This ensures browsers load WASM files correctly without manual configuration.
|
|
|
|
## Compression
|
|
|
|
Gzip compression is automatically applied to compressible content types when the client supports it:
|
|
|
|
- HTML, CSS, JavaScript
|
|
- JSON
|
|
- WASM binaries
|
|
- SVG images
|
|
|
|
Binary assets (PNG, JPEG, etc.) are served uncompressed since they're already compressed.
|
|
|
|
## Development vs Production
|
|
|
|
### Development
|
|
|
|
```go
|
|
func main() {
|
|
server := host.New("public", "index.html")
|
|
http.ListenAndServe(":8080", server)
|
|
}
|
|
```
|
|
|
|
Run with:
|
|
```bash
|
|
go run server.go
|
|
```
|
|
|
|
### Production
|
|
|
|
For production, compile the server and run as a binary:
|
|
|
|
```bash
|
|
go build -o server ./server.go
|
|
./server
|
|
```
|
|
|
|
Consider adding:
|
|
- TLS termination (via reverse proxy or `http.ListenAndServeTLS`)
|
|
- Environment-based port configuration
|
|
- Graceful shutdown handling
|
|
|
|
Example with TLS:
|
|
```go
|
|
func main() {
|
|
server := host.New("public", "index.html")
|
|
log.Fatal(http.ListenAndServeTLS(":443", "cert.pem", "key.pem", server))
|
|
}
|
|
```
|
|
|
|
Example with reverse proxy (nginx):
|
|
```nginx
|
|
server {
|
|
listen 443 ssl;
|
|
server_name example.com;
|
|
|
|
location / {
|
|
proxy_pass http://localhost:8080;
|
|
proxy_set_header Host $host;
|
|
}
|
|
}
|
|
```
|