8000 GitHub - bariiss/zig-http-server · GitHub
[go: up one dir, main page]

Skip to content

About

No description, website, or topics provided.

Resources

Stars

0 stars

Watchers

0 watching

Forks

Latest commit

 

History

7 Commits

Folders and files

Repository files navigation

Zig HTTP Server - API Backend

CI Docker

A simple HTTP API server written in Zig.

Features

  • REST-style API endpoints
  • JSON request/response handling
  • Sample Users and Posts resources
  • HTTP method support (GET, POST)
  • Basic error handling with proper HTTP status codes
  • Health check endpoint
  • Configuration via environment variables

Requirements

  • Zig 0.14.0 or newer

Build & Run

Using Make (Recommended)

# Show all available commands
make help

# Build (debug)
make build

# Build (release - optimized)
make release

# Run server
make run

# Run with custom port
make run PORT=8099

Cross-Compilation

# Build for all platforms
make build-all

# Build for specific platforms
make build-linux        # Linux x86_64
make build-linux-arm64  # Linux ARM64
make build-windows      # Windows x86_64
make build-macos        # macOS (native)
make build-macos-x64    # macOS Intel

Using Zig Directly

# Build
zig build

# Build release
zig build -Doptimize=ReleaseFast

# Run
zig build run

Run the Binary

./zig-out/bin/zig-http-server

By default the server listens on http://127.0.0.1:9099.

Configuration

  • HOST: bind address (default: 127.0.0.1)
  • PORT: bind port (default: 9099)

Example:

HOST=0.0.0.0 PORT=9099 zig build run

Docker

Using Make

# Build multi-arch image (amd64 + arm64)
make docker

# Build for specific architecture
make docker-amd64
make docker-arm64

# Run container
make docker-run

# Build with custom version
make docker VERSION=1.0.0

Using Docker Directly

docker buildx build \
  --platform linux/amd64,linux/arm64 \
  --build-arg VERSION=0.1.0 \
  --build-arg VCS_REF="$(git rev-parse --short HEAD 2>/dev/null || echo unknown)" \
  --build-arg BUILD_DATE="$(date -u +%Y-%m-%dT%H:%M:%SZ)" \
  -t zig-http-server:0.1.0 .

Run (defaults inside container: HOST=0.0.0.0, PORT=9099):

docker run --rm -p 9099:9099 zig-http-server:0.1.0

API Documentation (Swagger)

Interactive API documentation is available via Swagger UI:

API Endpoints

Index

GET /

Returns a short help text with available endpoints.

Documentation

GET /docs

Swagger UI - Interactive API documentation.

GET /openapi.json

OpenAPI 3.0 specification in JSON format.

Health check

GET /api/health

Checks server health.

Response:

{
  "status": "ok",
  "timestamp": 1234567890
}

Users

List all users

GET /api/users

Response:

[
  {
    "id": 1,
    "name": "John Doe",
    "email": "john@example.com"
  },
  {
    "id": 2,
    "name": "Jane Smith",
    "email": "jane@example.com"
  }
]

Get user by id

GET /api/users/:id

Response:

{
  "id": 1,
  "name": "John Doe",
  "email": "john@example.com"
}

Create user

POST /api/users
Content-Type: application/json

{
  "name": "New User",
  "email": "new@example.com"
}

Response:

{
  "id": 999,
  "name": "New User",
  "email": "new@example.com"
}

Posts

List all posts

GET /api/posts

Response:

[
  {
    "id": 1,
    "title": "Getting Started with Zig",
    "content": "Zig is a modern systems programming language.",
    "author_id": 1
  }
]

Create post

POST /api/posts
Content-Type: application/json

{
  "title": "New Post Title",
  "content": "Post content goes here.",
  "author_id": 1
}

Response:

{
  "id": 999,
  "title": "New Post Title",
  "content": "Post content goes here.",
  "author_id": 1
}

Example Usage

Test with cURL

# Health check
curl http://127.0.0.1:9099/api/health

# List users
curl http://127.0.0.1:9099/api/users

# Get user
curl http://127.0.0.1:9099/api/users/1

# Create user
curl -X POST http://127.0.0.1:9099/api/users \
  -H "Content-Type: application/json" \
  -d '{"name":"Test User","email":"test@example.com"}'

# List posts
curl http://127.0.0.1:9099/api/posts

# Create post
curl -X POST http://127.0.0.1:9099/api/posts \
  -H "Content-Type: application/json" \
  -d '{"title":"Test Post","content":"Test content","author_id":1}'

Project Structure

zig-http-server/
├── build.zig          # Build configuration
├── src/
│   └── main.zig       # Server implementation
└── README.md          # This file

Development

Run tests

zig build test

CI/CD

This project uses GitHub Actions for CI/CD:

Workflows

Workflow Trigger Description
CI Push/PR to main Build, test, cross-compile
Docker Tags v*, push to main Build & push multi-arch Docker image

Release Process

  1. Create and push a tag:

    git tag v1.0.0
    git push origin v1.0.0
  2. GitHub Actions will:

    • Build binaries for Linux (amd64, arm64) and Windows
    • Create a GitHub Release with all binaries
    • Build and push Docker image to ghcr.io/bariiss/zig-http-server

Docker Images

# Pull from GitHub Container Registry
docker pull ghcr.io/bariiss/zig-http-server:latest

# Run
docker run --rm -p 9099:9099 ghcr.io/bariiss/zig-http-server:latest

Notes

  • This server is intended for learning/demo purposes.
  • Data is currently in-memory sample data; a real backend would persist to a database.
  • Routing is intentionally simple; consider a router library for more complex needs.

License

Educational/demo use.

About

No description, website, or topics provided.

Resources

Stars

0 stars

Watchers

0 watching

Forks

Releases

Packages

Contributors

Languages

0