server

Overview ¶

Package server provides an HTTP server for serving generated blog content with support for live content updates via atomic handler hot-swapping.

The server implements thread-safe handler replacement, allowing blog content to be regenerated and swapped in without dropping in-flight requests or requiring server restart.

Basic Usage ¶

Create and start a server:

import (
    "context"
    "log/slog"
    "os"
    "github.com/harrydayexe/GoBlog/v2/pkg/server"
    "github.com/harrydayexe/GoBlog/v2/pkg/config"
)

// Create server with posts from directory
logger := slog.New(slog.NewTextHandler(os.Stdout, nil))
postsFS := os.DirFS("posts/")

cfg := config.ServerConfig{
    Server: []config.BaseServerOption{
        config.WithPort(8080),
        config.WithLogger(logger).AsServerOption(),
    },
}

srv, err := server.New(nil, postsFS, cfg)
if err != nil {
    log.Fatal(err)
}

// Start serving (blocks until interrupted)
if err := srv.Run(context.Background()); err != nil {
    log.Fatal(err)
}

Feed Routes ¶

When the generator is configured with config.WithBaseURL (and config.WithDisableFeeds is not applied), the server exposes:

• GET {root}rss.xml — site-wide RSS 2.0 feed
• GET {root}atom.xml — site-wide Atom feed
• GET {root}tags/{tag}.rss.xml — per-tag RSS 2.0 feed
• GET {root}tags/{tag}.atom.xml — per-tag Atom feed

Feed routes always exist in the mux but return 404 when the generator did not produce feed content. This mirrors the static output written by pkg/outputter at rss.xml, atom.xml, tags/{tag}.rss.xml, tags/{tag}.atom.xml.

HTML Extension Handling ¶

The server automatically accepts requests with or without .html suffixes. Requests for /posts/my-post.html are rewritten to /posts/my-post before routing, so both forms return the same content. This is handled by middleware.NewStripHTMLExtension from github.com/harrydayexe/GoWebUtilities, which is applied unconditionally inside Handler(). User-supplied middleware added via config.WithMiddleware sees the original .html URL before it is stripped.

Middleware ¶

The server supports pluggable HTTP middleware for cross-cutting concerns like logging, metrics, authentication, or rate limiting. Middleware uses the standard pattern from github.com/harrydayexe/GoWebUtilities/middleware.

Adding middleware to a server:

import (
    "github.com/harrydayexe/GoBlog/v2/pkg/config"
    "github.com/harrydayexe/GoBlog/v2/pkg/server"
    "github.com/harrydayexe/GoWebUtilities/logging"
    "github.com/harrydayexe/GoWebUtilities/middleware"
)

// Create server with built-in logging middleware
cfg := config.ServerConfig{
    Server: []config.BaseServerOption{
        config.WithPort(8080),
        config.WithMiddleware(logging.New(logger)),
        config.WithLogger(logger).AsServerOption(),
    },
}

srv, err := server.New(nil, postsFS, cfg)

Custom middleware can be added following the standard pattern:

func customMiddleware(h http.Handler) http.Handler {
    return http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
        // Pre-request logic
        h.ServeHTTP(w, r)
        // Post-request logic
    })
}

cfg := config.ServerConfig{
    Server: []config.BaseServerOption{
        config.WithMiddleware(
            logging.New(logger),     // Built-in
            customMiddleware,        // Custom
        ),
    },
}

Middleware are applied in order: the first middleware in the list is executed first (outermost wrapper). The middleware chain is reapplied whenever the handler is refreshed via UpdatePosts().

Any middleware compatible with the standard http.Handler interface can be used, including third-party middleware packages following the func(http.Handler) http.Handler pattern.

Live Content Updates ¶

Update blog content while server is running:

// Load updated posts
updatedFS := os.DirFS("posts/")

// Atomically swap in new content
if err := srv.UpdatePosts(updatedFS, context.Background()); err != nil {
    log.Printf("Update failed: %v", err)
}

The handler swap is atomic - in-flight requests complete with the old handler while new requests immediately see the updated content.

For automatic filesystem-triggered reloads, use pkg/watcher alongside UpdatePosts. The watcher watches a directory tree for changes and invokes a callback (debounced) on each change:

postsPath := "posts/"
w, err := watcher.New(postsPath, config.WithLogger(logger).AsWatcherOption())
if err != nil {
    log.Fatal(err)
}
go w.Run(ctx, func(ctx context.Context) {
    srv.UpdatePosts(os.DirFS(postsPath), ctx)
})

Health Checks ¶

Enable health-check endpoints via config.WithHealthChecks():

cfg := config.ServerConfig{
    Server: []config.BaseServerOption{
        config.WithPort(8080),
        config.WithHealthChecks(),
    },
}
srv, err := server.New(nil, postsFS, cfg)

Three unauthenticated GET endpoints are exposed:

• /healthz/live — always 200 OK ("ok"); confirms the process is alive.
• /healthz/ready — 200 OK once posts and templates have loaded; 503 while starting up or if loading failed (body includes the reason).
• /healthz/startup — same semantics as /healthz/ready; used as the startup probe in Kubernetes deployments.

When health checks are enabled the server binds the HTTP listener before loading posts, so probes can observe startup state. The endpoints bypass middleware (including authentication) and are intercepted in ServeHTTP before the content handler. The Docker image enables health checks by default.

Concurrency ¶

All Server methods are safe for concurrent use by multiple goroutines. The handler is stored in an atomic.Value, providing lock-free reads during request serving and atomic writes during updates. This design supports high-concurrency request handling without lock contention.

Server implements http.Handler interface, delegating to the current handler via atomic load operations.