servers.caddy.http #

HTTP Module README

Overview

The http module is a robust and production-ready HTTP server wrapper for the Caddy HTTP module. This module simplifies the creation and management of HTTP servers, routes, reverse proxies, file servers, and basic authentication. By default, HTTPS is enabled if the host matchers with qualifying names are used in any routes, with automatic certificate provisioning and renewal.

Features

• Easily Model and Configure Caddy HTTP: Simplifies the process of setting up and managing Caddy HTTP servers, routes, reverse proxies, file servers, and basic authentication using V programming language.
• Route Management: Add and manage HTTP routes effortlessly with predefined structures and handlers.
• Reverse Proxy Configuration: Simplify the configuration of reverse proxies with intuitive function calls.
• File Server Setup: Quickly set up file servers with defined domains and root directories.
• Basic Authentication Integration: Implement basic authentication for specific routes seamlessly.
• Helper Functions: Provides utility functions like password hashing to enhance security and ease of use.

Usage

Adding a Route

To add a new route to the server:

mut h := http.HTTP{}
h.add_route('/example', [http.Handle{handler: 'exampleHandler'}])!

Adding a File Server

To add a file server:

file_server_args := http.FileServer{
    domain: 'example.com',
    root: '/var/www/html'
}
h.add_file_server(file_server_args)!

Adding a Reverse Proxy

To add a reverse proxy:

reverse_proxy_args := http.ReverseProxy{
    from: '/proxy',
    to: 'http://backend.server'
}
h.add_reverse_proxy(reverse_proxy_args)!

Adding Basic Authentication

To add basic authentication to all routes for a specific domain:

basic_auth_args := http.BasicAuth{
    domain: 'example.com',
    username: 'user',
    password: 'password'
}
h.add_basic_auth(basic_auth_args)!

Handles

Handles are used to define the actions to be performed for each route. The following handles are available:

• authenticator_handle: Handles authentication using a specified portal.
• authentication_handle: Manages authentication policies.
• reverse_proxy_handle: Configures reverse proxy settings.
• basic_auth_handle: Sets up basic HTTP authentication.

Example of Using Handles

// Define a reverse proxy handle
rp_handle := http.reverse_proxy_handle(['http://backend1', 'http://backend2'])

// Use the handle in a route
mut h := http.HTTP{}
h.add_route('/proxy', [rp_handle])!

Merging HTTP Configurations

The http module provides functionality to merge two HTTP configurations into one. This allows you to combine multiple server configurations seamlessly. When merging, the function:

• Combines Servers: If servers from both configurations share the same key, they are merged; otherwise, the server from the second configuration is added.
• Merges Listening Ports: Ensures all unique listening ports from both servers are included.
• Merges Routes: Adds routes from the second server only if the host hasn't been defined in the first server's routes.

Here's an example of how to use the merge functionality:

import http

http1 := http.HTTP{...}
http2 := http.HTTP{...}

merged_http := http.merge_http(http1, http2)

This is useful for merging different caddy configurations.

fn authentication_handle(policy_name string) Handle

fn authenticator_handle(portal_name string) Handle

fn basic_auth_handle(username string, password string) !Handle

fn hash_password(plaintext string, params HashPasswordParams) !string

fn merge_http(http1 HTTP, http2 HTTP) HTTP

fn merge_servers(server1 Server, server2 Server) Server

fn reverse_proxy_handle(upstreams []string) Handle

struct Account {
pub:
	username string // Username for the account
	password string // Password for the account (hashed)
}

Account represents a user account for basic authentication.

struct Authorizer {
pub:
	gatekeeper_name string // Name of the gatekeeper
	route_matcher   string // Route matcher for the authorizer
}

Authorizer defines the authorizer for authentication.

struct BasicAuth {
pub:
	domain   string
	username string
	password string
}

struct FileServer {
pub:
	domain string // path on which the url will be proxied on the domain
	root   string // url that is being reverse proxied
}

struct HTTP {
pub mut:
	servers map[string]Server @[omitempty]
}

HTTP represents the main HTTP configuration, containing a map of servers.

fn (mut h HTTP) add_basic_auth(args BasicAuth) !

fn (mut h HTTP) add_file_server(args FileServer) !

fn (mut h HTTP) add_reverse_proxy(args ReverseProxy) !

fn (mut h HTTP) add_route(route string, handles []Handle) !

struct HTTPBasic {
pub mut:
	hash       Hash
	accounts   []Account         // List of accounts for basic auth
	hash_cache map[string]string // Cache for hashed passwords
}

HTTPBasic represents the basic HTTP authentication provider.

struct Handle {
pub mut:
	handler       string // Type of handler
	routes        []Route             @[omitempty] // Nested routes
	providers     Providers           @[omitempty] // Authentication providers
	root          string              @[omitempty] // Root directory for file server
	hide          []string            @[omitempty] // Paths to hide
	upstreams     []map[string]string @[omitempty] // Upstream servers for reverse proxy
	portal_name   string              @[omitempty] // Portal name for authentication
	route_matcher string              @[omitempty] // Route matcher for authentication
	body          string              @[omitempty] // Body content
	status_code   int                 @[omitempty] // Status code for response
}

Handle defines the actions to be performed for matched routes.

struct Hash {
pub:
	algorithm string // Hashing algorithm
}

Hash specifies the hashing algorithm used for passwords.

struct HashPasswordParams {
	algorithm string = 'bcrypt'
}

struct Match {
pub mut:
	host []string @[omitempty] // Hostnames to match
	path []string @[omitempty] // Paths to match
}

Match specifies the matching conditions for routes based on host and path.

struct Providers {
pub mut:
	authorizer Authorizer @[omitempty]
	http_basic HTTPBasic  @[omitempty]
}

Providers contains different authentication providers.

struct ReverseProxy {
pub:
	from string // path on which the url will be proxied on the domain
	to   string // url that is being reverse proxied
}

struct Route {
pub mut:
	@match   []Match  @[omitempty]
	handle   []Handle @[omitempty]
	terminal bool = true // Determines if this route is terminal
}

Route defines an HTTP route with match conditions and handlers.

fn (mut route Route) add_basic_auth(username string, password string) !

struct Server {
pub mut:
	listen []string = [':443'] // Ports the server listens on
	routes []Route @[omitempty]
}

Server represents a single HTTP server with listening ports and routes.

fn (mut server Server) add_basic_auth(domain string, username string, password string) !