naas/CLAUDE.md

CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

Project Overview

NaaS (No as a Service) is a lightweight HTTP service written in pure Rust that always responds with "no" in various formats. It uses only the Rust standard library with zero external dependencies, making it extremely lightweight and fast.

Development Commands

Build and Run

# Debug build
cargo build

# Release build (optimized for size)
cargo build --release

# Run locally
PORT=8080 cargo run

# Run release binary
PORT=8080 ./target/release/naas

Testing

# Run tests (currently no test files exist)
cargo test

# Test endpoints manually
curl http://localhost:8080/api/no
curl http://localhost:8080/api/no?format=json
curl http://localhost:8080/health

Container Operations

# Build container with Podman (preferred over Docker)
BUILDAH_FORMAT=docker podman build -t naas:latest -f Containerfile .

# Run container
podman run -d --name naas -p 8080:8080 --restart=always naas:latest

# Check container health
podman healthcheck run naas

Architecture

Single-File Design

The entire application is contained in src/main.rs with ~372 lines of code. This monolithic approach is intentional for simplicity and minimal binary size.

Key Components

1. Embedded HTML Frontends: Two HTML frontends are embedded as string constants:

   • SIMPLE_FRONTEND: Minimalist main page with just "No" centered on screen
   • PLAYGROUND_FRONTEND: Interactive API testing playground with buttons and examples

2. Request Router: The route_request() function handles all routing logic:

   • / - Serves the minimalist "No" page
   • /playground - Serves the interactive API testing interface
   • /api/no - API endpoint with format parameter support
   • /health - Health check endpoint
   • CORS headers are added to all responses

3. Thread-per-Connection Model: Each incoming TCP connection spawns a new thread via thread::spawn(), providing simple concurrency without async complexity.

4. Manual HTTP Parsing: The application manually parses HTTP requests and constructs responses, avoiding HTTP library dependencies.

API Response Formats

The /api/no endpoint supports these formats via the format query parameter:

• text (default): Plain text "no"
• json: {"answer":"no"}
• bool: false
• xml: <?xml version="1.0" encoding="UTF-8"?><response><answer>no</answer></response>
• yaml: answer: no

Deployment Configuration

Container Security

• Runs as non-root user (UID 1000)
• Read-only filesystem
• All capabilities dropped except NET_BIND_SERVICE
• Health checks configured in Containerfile

Systemd Service

The naas.service file configures:

• Automatic container build and run via Podman
• Resource limits (256MB memory, 50% CPU)
• Security hardening (PrivateTmp, ProtectSystem, NoNewPrivileges)

Binary Optimization

The Cargo.toml release profile optimizes for minimal size:

• opt-level = "z" - Size optimization
• lto = true - Link-time optimization
• codegen-units = 1 - Single codegen unit
• strip = true - Strip debug symbols
• panic = "abort" - Smaller panic handler

Port Configuration

The application reads the PORT environment variable (defaults to 8080) and binds to 0.0.0.0:$PORT for all network interfaces.

Error Handling

The application uses simple error handling:

• TCP connection errors are logged to stderr
• Stream read/write errors are logged but don't crash the server
• Invalid HTTP requests return 400 Bad Request
• Non-GET methods return 405 Method Not Allowed
• When creating a release, we normally just increment the patch level. We always update all relevant version fields, and we always want to include an up to date debian package in the forgejo release.