Architecture Note: Using Fiber's Prefork Feature for Multi‑Core Go Microservices

Problem

When a Go‑based microservice must handle tens of thousands of concurrent TCP connections, the default single‑process scheduler can become a bottleneck. Goroutine contention, garbage‑collector pauses, and lock‑heavy middleware limit horizontal scaling on a single binary.

Useful Takeaway

Enabling Fiber’s Prefork option creates multiple OS‑level child processes, each with its own event loop and memory space. This bypasses the Go scheduler for network I/O, isolates state, and lets you scale CPU usage without rewriting concurrency logic—provided you externalize any shared state.

Requirements

• Target deployment on Unix‑like OS (Linux, macOS); Prefork is not supported on Windows.
• Ability to run multiple processes simultaneously (sufficient RAM and file‑descriptor limits).
• External store (Redis, database, etc.) for any state that must be shared across workers.

Smallest Suitable Design

The minimal change to a standard Fiber application is to set the Prefork flag when creating the server instance. No modifications to route handlers or middleware are required for the basic pattern.

package main

import (
	"log"
	"github.com/gofiber/fiber/v2"
)

func main() {
	app := fiber.New(fiber.Config{
		Prefork: true, // enable multi‑process mode
	})

	app.Get("/hello", func(c *fiber.Ctx) error {
		return c.SendString("Hello, World\n")
	})

	if err := app.Listen(":3000"); err != nil {
		log.Fatal(err)
	}
}

When the binary starts, the parent process forks N children (default equals runtime.NumCPU()). Each child runs an independent copy of the Fiber stack, listening on the same socket via SO_REUSEPORT.

Trust/Data Boundaries

Because each child receives a duplicate of the parent’s memory at fork time, any in‑memory data structures (global variables, maps, caches) become isolated. Changes made in one child are not visible to others. Therefore:

• Do not rely on in‑process caches for hit‑rate‑critical workloads.
• Use an external datastore (e.g., Redis) for session data, rate‑limiting counters, or feature flags.
• If a middleware stores state in a global variable, replace it with a store‑backed implementation before enabling Prefork.

Operational Checks

1. Verify process count: after starting the app, run ps -ef | grep <binary-name> or top and confirm you see one parent PID plus N child PIDs.
2. Check socket sharing: ss -lpn | grep :3000 should show the same address bound to multiple PIDs.
3. Monitor zombie processes during shutdown: send SIGTERM to the parent and ensure all children exit cleanly (no lingering <defunct> entries).
4. Log each child’s PID at startup (e.g., log.Printf("Worker %d started", os.Getpid())) to simplify tracing.

Failure Modes

• Memory overhead: Each child duplicates the Go runtime, libraries, and read‑only sections, increasing RSS roughly by a factor of N. On memory‑constrained hosts, this can outweigh CPU gains.
• File‑descriptor exhaustion: The parent inherits the FD limit; children share it unless raised. Adjust ulimit -n or set Fiber.Config.Prefork with a custom Server.MaxConnsPerWorker if needed.
• Inconsistent caches: Middleware that uses local maps for caching will see fragmented hit ratios, potentially increasing backend load.
• Windows incompatibility: Prefork will panic or fail to start; deployment pipelines targeting Windows must disable the feature.

Conditions That Would Change the Design

• If the application requires high‑frequency synchronization of fine‑grained state (e.g., per‑request counters that must be globally consistent without external round‑trips), the overhead of external stores may become prohibitive, prompting a return to standard Go concurrency (goroutines + sync/atomic or errgroup).
• When deploying to environments where process forking is disallowed (e.g., certain container security profiles, Windows nodes, or PaaS restrictions), Prefork cannot be used; you would need to rely on Go’s scheduler and tune GOMAXPROCS instead.
• If the binary size or startup time becomes a concern due to duplicated initialization (e.g., large template caches, ORM schemas), you might move shared initialization to a pre‑fork Init function that runs only in the parent and uses fork‑safe primitives, or accept the overhead as a trade‑off.

Practical Verification (No Claim of Testing)

To observe the lack of shared state, you could add a global counter and increment it on each request:

var requestCount int

func countMiddleware(c *fiber.Ctx) error {
	requestCount++
	log.Printf("Worker %d: count=%d\n", os.Getpid(), requestCount)
	return c.Next()
}

app.Use(countMiddleware)

When sending multiple requests (e.g., with hey or ab), you would see different count values in the log lines corresponding to different worker PIDs, confirming that each child maintains its own copy of requestCount. This experiment illustrates the data boundary but does not constitute proof of production correctness.

Rollback Considerations

Enabling Prefork does not mutate persistent state; disabling it merely stops the parent from forking children. To roll back, rebuild the binary with Prefork: false (or omit the field) and redeploy. No data migration is required because no in‑process state is relied upon for correctness.