README.md · glaze · main

# Glaze 🍯

Glaze is a small web frontend for **soft-serve**, built in **Odin**.

It serves **server-rendered HTML pages** that let you browse git repositories, inspect files, and download content. Everything is backend-driven and intentionally simple, primarily serving server side rendered pages.

## Goals

### Product goals

- Provide a clean, fast web UI for:
  - listing repositories
  - browsing directories and files
  - viewing text files in-browser
  - downloading raw files and archives
- Integrate cleanly with existing soft-serve setups.
- Be pleasant to self-host.

### Engineering goals

- Implement a **resilient HTTP/1.x server** in Odin using raw sockets:
  - incremental request parsing
  - keep-alive support with limits and timeouts
  - bounded memory usage per connection
  - clear connection state machine
- Keep the HTTP server reusable for future projects.

## Non-goals (initially)

- Public JSON API
- HTTP/2 or TLS (use a reverse proxy if needed)
- Chunked request bodies
- Full GitHub-like features (PRs, issues, etc.)

## High-level architecture

Glaze consists of two main layers:

1. **HTTP server**
   - TCP listener, raw sockets
   - HTTP/1.x parsing and response writing
   - routing and static file serving

2. **Application layer**
   - HTML page handlers
   - git / soft-serve integration
   - simple templating helpers

## Suggested layout

```
src/
| http/ # sockets, parsing, routing
| app/ # page handlers
| views/ # HTML helpers / templates
| integrations/
| softserve/ # repo + file access
| static/ # CSS, icons, etc.
| main.odin
```

## Pages & routes (initial scope)

- `GET /`
  - List repositories
- `GET /r//`
  - Repository overview, file list
- `GET /r//tree//`
  - Directory browsing
- `GET /r//blob//`
  - View text file
- `GET /r//raw//`
  - Download raw file
- `GET /r//archive/.(zip|tar.gz)`
  - Download repository archive (later)

## Git / soft-serve integration

Early versions will likely:
- run on the same host as soft-serve
- access repositories directly via `git` commands or filesystem access

Integration details are intentionally abstracted so the backend can later switch
to:
- soft-serve CLI
- SSH access
- or an internal soft-serve API

## HTTP server design notes

- Nonblocking sockets with an event loop (poll/epoll)
- One connection can serve multiple requests (keep-alive)
- Strict limits to avoid resource abuse:
  - max header size
  - max request line length
  - max body size
  - idle timeouts

## Milestones

### M1: Hello Glaze

- TCP listener + HTTP parsing
- `GET /` returns simple HTML
- keep-alive working

### M2: Layout + static assets

- Basic page layout
- CSS served from `/static/`

### M3: Repository list

- Real repo data
- Clickable repo links

### M4: Repository browsing

- Directory listing
- File view
- Raw downloads

### M5: Nice touches

- README rendering
- Archive downloads
- Better caching headers

## Development

- Local run:
  `glaze -listen 127.0.0.1:8080`
- Test with:
  `curl -v http://127.0.0.1:8080/`
🍯 Glaze

/ glaze / README.md
