fcgx

README

fcgx

A minimal, robust, and modern FastCGI client library for Go.

fcgx is designed for integrating with PHP-FPM and other FastCGI servers, aiming for idiomatic Go, high testability, and correct protocol handling. It supports context, deadlines, timeouts, and structured error handling.

Built with ❤️ by cbox.dk - Experts in cloud infrastructure and modern web solutions.

Features

• Idiomatic, thread-safe Go API
• Context and timeout support on all requests
• Structured sentinel errors for robust error handling (errors.Is)
• Manual and reliable FastCGI protocol handling
• Designed for integration with PHP-FPM status, pool metrics, and more
• Well-suited for Kubernetes, Docker, and production monitoring

Quick Example

import (
    "context"
    "github.com/cboxdk/fcgx"
    "io"
    "time"
)

func main() {
    ctx, cancel := context.WithTimeout(context.Background(), 2*time.Second)
    defer cancel()

    client, err := fcgx.DialContext(ctx, "unix", "/var/run/php-fpm.sock")
    if err != nil {
        panic(err)
    }
    defer client.Close()

    params := map[string]string{
        "SCRIPT_FILENAME": "/usr/share/phpmyadmin/index.php",
        "SCRIPT_NAME":     "/index.php",
        "REQUEST_METHOD":  "GET",
        "SERVER_PROTOCOL": "HTTP/1.1",
        "REMOTE_ADDR":     "127.0.0.1",
    }

    resp, err := client.Get(ctx, params)
    if err != nil {
        panic(err)
    }
    defer resp.Body.Close()
    body, _ := io.ReadAll(resp.Body)
    println(string(body))
}

Error Handling

fcgx returns strong sentinel errors for key error categories:

• ErrClientClosed
• ErrTimeout
• ErrContextCancelled
• ErrUnexpectedEOF
• ErrInvalidResponse
• ErrWrite, ErrRead

Use errors.Is to match error causes in your code.

About cbox.dk

This library is developed and maintained by cbox.dk, a Danish company specializing in:

• Cloud infrastructure solutions
• Modern web development
• DevOps and container orchestration
• High-performance backend systems

We build reliable, scalable solutions for businesses of all sizes. Visit us at cbox.dk to learn more about our services.

Authors

• Sylvester Damgaard

License

MIT

Documentation

Index

• Constants
• Variables
• func ReadBody(resp *http.Response) ([]byte, error)
• func ReadJSON(resp *http.Response, out any) error
• type Client
  • func Dial(network, address string) (*Client, error)
  • func DialContext(ctx context.Context, network, address string) (*Client, error)
  • func (c *Client) Close() error
  • func (c *Client) DoRequest(ctx context.Context, params map[string]string, body io.Reader) (*http.Response, error)
  • func (c *Client) Get(ctx context.Context, params map[string]string) (*http.Response, error)
  • func (c *Client) Post(ctx context.Context, params map[string]string, body io.Reader, ...) (*http.Response, error)

Constants

const (
	FCGI_HEADER_LEN = 8
)

Variables

var (
	ErrClientClosed     = errors.New("fcgx: client closed")
	ErrTimeout          = errors.New("fcgx: timeout")
	ErrContextCancelled = errors.New("fcgx: context cancelled")
	ErrUnexpectedEOF    = errors.New("fcgx: unexpected EOF")
	ErrInvalidResponse  = errors.New("fcgx: invalid response")
	ErrPHPFPM           = errors.New("fcgx: php-fpm error")
	ErrConnect          = errors.New("fcgx: connect error")
	ErrWrite            = errors.New("fcgx: write error")
	ErrRead             = errors.New("fcgx: read error")
)

Functions

func ReadBody

func ReadBody(resp *http.Response) ([]byte, error)

ReadBody reads and returns the actual response body as a []byte. It also strips any HTTP headers if present (as in FastCGI/PHP-FPM responses). It closes the response body after reading.

func ReadJSON

func ReadJSON(resp *http.Response, out any) error

ReadJSON reads and unmarshals the actual response body as JSON into out. It also strips any HTTP headers if present (as in FastCGI/PHP-FPM responses). It closes the response body after reading.

Types

type Client

type Client struct {
	// contains filtered or unexported fields
}

func Dial

func Dial(network, address string) (*Client, error)

Dial establishes a connection to the FastCGI server at the specified network address.

func DialContext

func DialContext(ctx context.Context, network, address string) (*Client, error)

DialContext establishes a connection to the FastCGI server at the specified network address with the given context.

func (*Client) Close

func (c *Client) Close() error

Close closes the FastCGI connection.

func (*Client) DoRequest

func (c *Client) DoRequest(ctx context.Context, params map[string]string, body io.Reader) (*http.Response, error)

func (*Client) Get

func (c *Client) Get(ctx context.Context, params map[string]string) (*http.Response, error)

func (*Client) Post

func (c *Client) Post(ctx context.Context, params map[string]string, body io.Reader, contentLength int) (*http.Response, error)