Documentation

Getting Started

ALOS HTTP is a Linux amd64 web framework built around native io_uring, native TLS 1.3, and HTTP/2. This guide gets a Linux server running quickly and points out the current compatibility limits for streaming and hijack-based APIs.

Getting Started Benchmarks Routing Middleware Request & Response WebSocket Reverse Proxy TLS & ACME Rate Limiting Streaming & Files Configuration

Installation

Install the module with a single command:

bash 
go get github.com/guno1928/alos-http

ALOS HTTP's documented production runtime is Linux amd64. The native server path is built around io_uring.

Requires Go 1.25 or later. That matches the module's current go.mod.

Quick Start

The fastest way to get a server running:

1

Create your project

bash 
mkdir myapp && cd myapp
go mod init myapp
go get github.com/guno1928/alos-http
2

Write your server

go 
package main

import (
    "log"
    "github.com/guno1928/alos-http/core"
)

func main() {
    s := core.New()

    s.Router.GET("/", func(req *core.Request, resp *core.Response) {
        resp.String("Hello from ALOS!")
    })

    s.Router.Build()
    log.Fatal(s.ListenAndServe())
}
3

Run it

bash 
go run main.go

Your server is now running at http://localhost:80. On Linux amd64, ALOS will prefer its native io_uring server path when the kernel supports it.

Plain HTTP Mode

For development or internal services, start a plain HTTP server with no TLS overhead:

go 
s := core.New(core.Config{
    Addr:      ":8080",
    PlainHTTP: true,
})

s.Router.GET("/", func(req *core.Request, resp *core.Response) {
    resp.JSON([]byte(`{"status":"ok"}`))
})

s.Router.Build()
log.Fatal(s.ListenAndServe())

HTTPS & TLS

ALOS uses its own native TLS 1.3 serving path on the main Linux runtime. Older TLS 1.2/1.1 clients can still fall back through Go's crypto/tls compatibility path when needed. You can use manual certificates or auto-generate self-signed ones:

With Manual Certificates

go 
s := core.New(core.Config{
    Addr:        ":443",
    TLSCertFile: "cert.pem",
    TLSKeyFile:  "key.pem",
})

s.Router.Build()
log.Fatal(s.ListenAndServeTLS())

With Self-Signed Cert (Development)

go 
s := core.New(core.Config{
    Addr: ":443",
})

s.Router.Build()
log.Fatal(s.ListenAndServeTLS())

The self-signed cert is saved to .alos-cert.pem and .alos-key.pem and reused on subsequent runs.

Automatic Certificates (ACME)

ALOS integrates with Let's Encrypt for automatic, free TLS certificates. Just provide your email and domain names:

go 
s := core.New(core.Config{
    Addr:     ":443",
    HTTPAddr: ":80",
    ACME: &core.ACMEConfig{
        Email:    "admin@example.com",
        Domains:  []string{"example.com", "www.example.com"},
        CacheDir: ".alos-certs",
    },
})

s.Router.Build()
log.Fatal(s.ListenAndServeTLS())

What happens automatically:

  • Certificates are obtained on first startup
  • HTTP-01 challenges are served on port 80
  • Certs are stored in .alos-certs/ directory
  • Auto-renewal runs every 6 hours, 30 days before expiry
  • DNS validation ensures domains point to your server

Your First Routes

Register routes with the built-in router. ALOS supports all standard HTTP methods:

go 
s.Router.GET("/hello", func(req *core.Request, resp *core.Response) {
    resp.String("Hello, World!")
})

s.Router.GET("/users/:id", func(req *core.Request, resp *core.Response) {
    id := req.ParamValue("id")
    resp.JSON([]byte(`{"user":"` + id + `"}`))
})

s.Router.POST("/api/data", func(req *core.Request, resp *core.Response) {
    body := req.Body
    resp.Status(201).Bytes(body)
})

s.Router.Build()

For more advanced routing, see the Routing documentation.

Adding Middleware

Apply middleware globally or per-group. ALOS includes several production-ready middleware:

go 
s.Router.Use(core.Recovery())
s.Router.Use(core.Logger())
s.Router.Use(core.RealIP())
s.Router.Use(core.RequestID())
s.Router.Use(core.SecurityHeaders(core.DefaultSecurityHeaders()))

s.SetCORS(core.CORSConfig{
    AllowOrigins: []string{"*"},
    AllowMethods: []string{"GET", "POST", "PUT", "DELETE"},
})
s.Router.Use(s.CORS.Middleware())

s.Router.Build()

For detailed middleware configuration, see the Middleware documentation.

JSON Responses

ALOS provides multiple ways to send JSON data:

Pre-built JSON

go 
s.Router.GET("/api/status", func(req *core.Request, resp *core.Response) {
    resp.JSON([]byte(`{"status":"ok","version":"1.0"}`))
})

Auto-Marshal from Struct

go 
type User struct {
    ID   int    `json:"id"`
    Name string `json:"name"`
}

s.Router.GET("/api/user", func(req *core.Request, resp *core.Response) {
    user := User{ID: 1, Name: "Alice"}
    resp.JSONMarshal(user)
})

Parse JSON Request Body

go 
s.Router.POST("/api/users", func(req *core.Request, resp *core.Response) {
    var user User
    if err := json.Unmarshal(req.Body, &user); err != nil {
        resp.Status(400).JSON([]byte(`{"error":"invalid json"}`))
        return
    }
    resp.Status(201).JSONMarshal(user)
})

Complete Application

Putting it all together — a production-ready HTTPS server with routing, middleware, and JSON:

go 
package main

import (
    "log"
    "github.com/guno1928/alos-http/core"
)

func main() {
    s := core.New(core.Config{
        Addr:      ":8080",
        PlainHTTP: true,
    })

    s.Router.Use(core.Recovery(), core.Logger(), core.Compress(core.CompressConfig{}))

    s.Router.GET("/", func(req *core.Request, resp *core.Response) {
        resp.String("Welcome to ALOS HTTP")
    })

    s.Router.GET("/health", func(req *core.Request, resp *core.Response) {
        resp.JSON([]byte(`{"status":"ok"}`))
    })

    api := s.Router.Group("/api/v1", core.RealIP())

    api.GET("/users/:id", func(req *core.Request, resp *core.Response) {
        id := req.ParamValue("id")
        resp.JSONMarshal(map[string]string{"id": id})
    })

    api.POST("/users", func(req *core.Request, resp *core.Response) {
        resp.Status(201).Bytes(req.Body)
    })

    s.Router.NotFound(func(req *core.Request, resp *core.Response) {
        resp.Status(404).JSON([]byte(`{"error":"not found"}`))
    })

    s.Router.Build()
    log.Fatal(s.ListenAndServe())
}
ESC