zeptor

Zeptor

A Next.js-like Go framework with eBPF acceleration.

⚠️ Work in Progress - This project is in early development. APIs may change without notice.

Features

• 📁 File-based routing - Automatic route discovery from app/ directory
• ⚡ eBPF acceleration - Kernel-level routing and caching (Linux only)
• 🎨 Type-safe templates - Full type safety with templ
• 🔀 Dynamic routes - Support for {slug} style parameters
• 🔄 Hot reload - Instant browser refresh during development
• 🚀 Fast - Radix tree router with O(k) lookups

Quick Start

Prerequisites

• Go 1.23+
• templ CLI (go install github.com/a-h/templ/cmd/templ@latest)
• Docker (optional, for containerized development)

Create a New Project

# Install Zeptor CLI
git clone https://github.com/brattlof/zeptor.git
cd zeptor
make install-deps
make build

# Create a new project
./bin/zt create my-app
cd my-app
../bin/zt dev

Open http://localhost:3000

Project Templates

zt create my-app                    # Minimal (default)
zt create my-app -t basic           # Basic with routing examples
zt create my-api -t api             # API-only project
zt create my-app -t basic -p 8080   # Custom port

Run an Example

cd examples/hello-world
../../bin/zt dev

Examples

Project Structure

Each example is a standalone project:

my-zeptor-app/
├── app/                    # Your application
│   ├── page.templ          # Home page (/)
│   ├── about/
│   │   └── page.templ      # About page (/about)
│   ├── slug_/
│   │   └── page.templ      # Dynamic route (/{slug})
│   └── api/
│       └── users/
│           └── route.go    # API endpoint (/api/users)
├── public/                 # Static files (served at /public/*)
└── zeptor.config.yaml      # Configuration

Routing

File-based Routes

Note: Dynamic route directories use slug_ suffix (e.g., slug_ → {slug}) for Go package compatibility.

API Endpoints

CLI Commands

# Create a new project
zt create my-app
zt create my-app -t basic -p 8080

# Run development server (from project directory)
zt dev

# Custom port
zt dev -p 8080

# Disable eBPF
zt dev --no-ebpf

# List discovered routes
zt routes
zt routes --json

Configuration

# zeptor.config.yaml
app:
  port: 3000
  host: "0.0.0.0"

routing:
  appDir: "./app"
  publicDir: "./public"

ebpf:
  enabled: true
  interface: "eth0"
  cacheSize: 10000
  cacheTTLSec: 60

rendering:
  mode: "ssr"  # ssr, ssg, or isr

logging:
  level: "info"
  format: "text"

plugins:
  enabled: ["basicauth", "ratelimit"]
  dir: "./plugins"
  config:
    basicauth:
      users: ["admin:secret"]
      paths: ["/admin"]
      realm: "Admin Area"
    ratelimit:
      limit: 100
      windowSeconds: 60

Plugins

Zeptor supports a plugin architecture for extending functionality.

Built-in Plugins

Plugin Commands

# List loaded plugins
zt plugin list
zt plugin list --json

# Inspect a specific plugin
zt plugin inspect basicauth

Creating a Plugin

Plugins implement the plugin.Plugin interface:

package myplugin

import "github.com/brattlof/zeptor/pkg/plugin"

type MyPlugin struct{}

func (p *MyPlugin) Name() string        { return "myplugin" }
func (p *MyPlugin) Version() string     { return "1.0.0" }
func (p *MyPlugin) Description() string { return "My custom plugin" }
func (p *MyPlugin) Init(ctx *plugin.PluginContext) error { return nil }
func (p *MyPlugin) Close() error { return nil }

Available hooks:

• ConfigHook - Called when config is loaded
• RouterHook - Called when router is initialized
• MiddlewareHook - Provides middleware function
• RequestHook - Called on each request
• ResponseHook - Called after response
• BuildHook - Called during build process
• DevHook - Called during dev server lifecycle

Docker Development

# Without eBPF (works everywhere)
docker-compose -f docker/docker-compose.yml up -d zeptor-nobpf

# With eBPF (Linux only)
docker-compose -f docker/docker-compose.yml --profile ebpf up -d zeptor-ebpf

Requirements

• Go 1.23+
• templ CLI (for template generation)
• Linux kernel 5.4+ (for eBPF features)
• Docker (optional, for containerized development)

Development

make test      # Run tests
make lint      # Run linter
make fmt       # Format code
make build     # Build binaries

Status

This project is in early alpha. Expect breaking changes.

Roadmap

• File-based routing with radix tree
• SSR with templ rendering
• Hot module replacement (HMR)
• Dev server with file watching
• zt create project scaffolding
• Plugin architecture
• Full eBPF integration (XDP + TC)
• SSG build process
• Middleware system

Contributing

Contributions are welcome! Please read CONTRIBUTING.md for guidelines.

License

MIT

Acknowledgments

• cilium/ebpf - Pure Go eBPF library
• a-h/templ - Type-safe HTML templates
• go-chi/chi - Lightweight HTTP router