Backend - valtownGeocities

The backend is built with Hono and provides a RESTful API for publishing and retrieving HTML websites.

Architecture

Framework: Hono v4.6.3
Database: SQLite (via Val Town's sqlite service)
Storage: Val Town Blob storage for HTML content
Security: SHA-256 password hashing with salt

Database Schema

`website_pages_v1` Table

CREATE TABLE website_pages_v1 (
  id INTEGER PRIMARY KEY AUTOINCREMENT,
  key TEXT UNIQUE NOT NULL,
  password_hash TEXT,
  created_at TEXT NOT NULL,
  updated_at TEXT NOT NULL,
  size INTEGER NOT NULL,
  is_public INTEGER DEFAULT 1
);

Key Features

Password Protection

Optional password protection for pages
SHA-256 hashing with salt
Password required for updates to protected pages
No password recovery (by design)

Data Storage

HTML content stored in Val Town Blob storage
Metadata stored in SQLite database
Automatic creation/update timestamps
File size tracking

Security

Input validation and sanitization
Key format validation (alphanumeric, hyphens, underscores)
Size limits (10MB max)
Secure password hashing

API Endpoints

`GET /`

Without key: Returns index page with all published websites
With key: Returns the published HTML website
With format=json: Returns website metadata as JSON

`POST /`

Purpose: Publish or update HTML content
Parameters:
- key (required): Website identifier
- password (optional): For protection or authentication
- format (optional): Response format
Body: HTML content (raw or JSON with data field)

Error Handling

The backend provides comprehensive error handling with appropriate HTTP status codes:

400 Bad Request: Invalid input, missing data, or validation errors
401 Unauthorized: Password required or invalid password
413 Payload Too Large: Content exceeds 10MB limit
500 Internal Server Error: Database or storage errors

Development Notes

Database Migrations

Table name includes version suffix (_v1) for schema changes
Run initDatabase() on startup to create tables
Change table name when modifying schema

Password Security

Passwords are hashed with SHA-256 and a salt
Salt: "salt_valtowngeocities"
No plain text password storage
Minimum password length: 4 characters

File Processing

Strips common markdown artifacts (```html blocks)
Handles both raw HTML and JSON input formats
Validates and sanitizes all input

Testing

Use the provided curl examples in the main README to test functionality:

# Test basic publishing
curl -X POST "https://your-val-url.web.val.run/?key=test" \
  -H "Content-Type: text/html" \
  -d "<html><body><h1>Test</h1></body></html>"

# Test password protection
curl -X POST "https://your-val-url.web.val.run/?key=protected&password=test123" \
  -H "Content-Type: text/html" \
  -d "<html><body><h1>Protected</h1></body></html>"

jamiedubs

valtownGeocities