# Hectoday HTTP

> A web framework that refuses to make decisions for you.

Hectoday HTTP is built on Web Standards (Request/Response) and runs on Deno, Bun, and Cloudflare Workers. It describes facts about requests and lets you decide what they mean as HTTP responses.

## Core Philosophy

- **No magic**: Every decision boundary is visible in your code
- **Facts before decisions**: Validation describes data, doesn't control flow
- **Explicit control flow**: Guards and handlers are the only places requests can end
- **Web Standards**: Uses Fetch API (Request/Response) everywhere
- **Runtime independence**: Same code runs on Deno, Bun, and Workers

## Quick Start

```typescript
import { route, setup } from "@hectoday/http";

const app = setup({
  handlers: [
    route.get("/", {
      resolve: () => new Response("Hello World")
    })
  ]
});

Deno.serve(app.fetch);
```

## Documentation

### Part 1: Mental Models
- /docs/what-this-is - Understanding Hectoday HTTP's purpose and philosophy
- /docs/how-to-read-these-docs - A guide to understanding Hectoday HTTP's documentation structure
- /docs/a-mental-model-of-http - Understanding HTTP from first principles

### Part 2: Core Concepts
- /docs/the-web-standard-foundation - How Web Standards provide the primitives for HTTP servers
- /docs/your-first-server - Building your first Hectoday HTTP server
- /docs/describing-facts - Extracting request data without making decisions
- /docs/validation-without-control-flow - Using validation to describe data, not control requests
- /docs/guards-making-decisions-explicit - Using guards to control request flow explicitly

### Part 3: Composition
- /docs/the-request-lifecycle-fully-explicit - Understanding the complete path of every request
- /docs/hooks-the-three-extension-points - Understanding onRequest, onResponse, and onError hooks
- /docs/errors-are-responses - Handling failures explicitly without exceptions
- /docs/composition-over-configuration - Building larger APIs from small, reusable pieces

### Part 4: Real Concerns
- /docs/security-as-a-first-class-concept - Designing secure APIs with explicit security controls
- /docs/static-files-and-assets - Serving static files explicitly without magic conventions
- /docs/runtime-independence - Running the same code across Deno, Bun, and Cloudflare Workers

### Part 5: Reference
- /docs/reference - Complete API reference for Hectoday HTTP
- /docs/philosophy-revisited - Why Hectoday HTTP makes these design choices

### Helpers (Copy-paste recipes)
- /docs/helpers/max-body-bytes - Guard helper to limit request body size
- /docs/helpers/zod-validator - Validator adapter for using Zod schemas with Hectoday HTTP

## Key Concepts

### Context (c)
The context object passed to guards and handlers:
- `c.request` - The original Web Standard Request
- `c.raw` - Extracted but unvalidated inputs (params, query, body)
- `c.input` - Validation results (ok: true/false)
- `c.locals` - Request-scoped data from hooks and guards

### Guards
Functions that make allow/deny decisions:
```typescript
const requireAuth: GuardFn = (c) => {
  const token = c.request.headers.get("authorization");
  if (!token) {
    return { deny: Response.json({ error: "Unauthorized" }, { status: 401 }) };
  }
  return { allow: true, locals: { userId: "123" } };
};
```

### Validation
Validation describes data but never controls flow:
```typescript
route.post("/users", {
  request: {
    body: z.object({ name: z.string(), email: z.string().email() })
  },
  resolve: (c) => {
    if (!c.input.ok) {
      return Response.json({ error: c.input.issues }, { status: 400 });
    }
    return Response.json(c.input.body, { status: 201 });
  }
})
```

### Hooks
Three extension points:
- `onRequest` - Runs before routing, adds to locals
- `onResponse` - Runs after handler, can modify response
- `onError` - Handles unexpected errors (throws)

## Full Documentation

For complete documentation with all content: /llms-full.txt