fcgi

Documentation

Index

• Constants
• Variables
• func DecodeParams(data []byte) (map[string]string, error)
• func EncodeParams(params map[string]string) []byte
• func WriteBeginRequest(w io.Writer, requestID uint16, role uint16, keepConn bool) error
• func WriteRecord(w io.Writer, recType uint8, requestID uint16, content []byte) error
• type Client
  • func NewClient(cfg ClientConfig) *Client
  • func (c *Client) Close()
  • func (c *Client) Do(req Request) (Response, error)
• type ClientConfig
• type ConnPool
  • func NewConnPool(network, address string, dialTimeout time.Duration, cfg PoolConfig) *ConnPool
  • func (p *ConnPool) Close()
  • func (p *ConnPool) Dial() (net.Conn, error)
  • func (p *ConnPool) Get() (conn net.Conn, reused bool, err error)
  • func (p *ConnPool) Put(conn net.Conn)
  • func (p *ConnPool) Stats() int
• type Header
• type PoolConfig
  • func DefaultPoolConfig() PoolConfig
• type Record
  • func ReadRecord(r io.Reader) (Record, error)
  • func ReadRecordInto(r io.Reader, stdout, stderr *bytes.Buffer, maxStdout, maxStderr int) (Record, error)
• type Request
• type Response

Constants

const (
	TypeBeginRequest    uint8 = 1
	TypeAbortRequest    uint8 = 2
	TypeEndRequest      uint8 = 3
	TypeParams          uint8 = 4
	TypeStdin           uint8 = 5
	TypeStdout          uint8 = 6
	TypeStderr          uint8 = 7
	TypeData            uint8 = 8
	TypeGetValues       uint8 = 9
	TypeGetValuesResult uint8 = 10
	TypeUnknownType     uint8 = 11
)

FastCGI record types.

const (
	RoleResponder  uint16 = 1
	RoleAuthorizer uint16 = 2
	RoleFilter     uint16 = 3
)

FastCGI roles.

const (
	StatusRequestComplete uint8 = 0
	StatusCantMPXConn     uint8 = 1
	StatusOverloaded      uint8 = 2
	StatusUnknownRole     uint8 = 3
)

Protocol status values.

Variables

var (
	ErrInvalidHeader  = errors.New("fcgi: invalid record header")
	ErrContentTooLong = errors.New("fcgi: content exceeds maximum size")
)

var (
	ErrParamsTruncated = errors.New("fcgi: params data truncated")
)

Functions

func DecodeParams

func DecodeParams(data []byte) (map[string]string, error)

DecodeParams decodes FastCGI params from the given data. Returns an error on malformed input instead of panicking.

func EncodeParams

func EncodeParams(params map[string]string) []byte

EncodeParams encodes key-value pairs into FastCGI params format.

func WriteBeginRequest

func WriteBeginRequest(w io.Writer, requestID uint16, role uint16, keepConn bool) error

WriteBeginRequest writes a BeginRequest record.

func WriteRecord

func WriteRecord(w io.Writer, recType uint8, requestID uint16, content []byte) error

WriteRecord writes a FastCGI record to the writer.

Types

type Client

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

Client is a FastCGI client that communicates with an upstream server. It maintains a connection pool for reuse across requests. Safe for concurrent use.

func NewClient

func NewClient(cfg ClientConfig) *Client

NewClient creates a new FastCGI client with a connection pool.

func (*Client) Close

func (c *Client) Close()

Close shuts down the client and its connection pool.

func (*Client) Do

func (c *Client) Do(req Request) (Response, error)

Do sends a FastCGI request and returns the response. Connections are reused from the pool when available.

If a pooled connection fails with a stale-connection error (EOF, ECONNRESET, EPIPE, "use of closed network connection") before any response bytes are received, Do retries once on a freshly dialed connection. This hides the race where an upstream worker (e.g. a PHP-FPM child hitting pm.max_requests) closes an idle keep-alive socket between requests. The retry only fires when the request body, if any, implements io.Seeker so it can be rewound safely.

type ClientConfig

type ClientConfig struct {
	Network      string
	Address      string
	DialTimeout  time.Duration
	ReadTimeout  time.Duration
	WriteTimeout time.Duration
	Pool         PoolConfig
}

ClientConfig holds connection parameters for the FastCGI client.

type ConnPool

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

ConnPool manages a pool of reusable TCP/Unix connections to a FastCGI upstream.

func NewConnPool

func NewConnPool(network, address string, dialTimeout time.Duration, cfg PoolConfig) *ConnPool

NewConnPool creates a connection pool with background eviction of idle connections.

func (*ConnPool) Close

func (p *ConnPool) Close()

Close shuts down the pool and closes all idle connections.

func (*ConnPool) Dial

func (p *ConnPool) Dial() (net.Conn, error)

Dial opens a brand-new connection, bypassing the idle pool. Used for retrying after a pooled connection was found to be stale.

func (*ConnPool) Get

func (p *ConnPool) Get() (conn net.Conn, reused bool, err error)

Get returns a connection from the pool or dials a new one. The reused return value is true when the connection came from the pool (and may therefore be stale), false when it was freshly dialed. Callers can use this to decide whether a connection-level error is retriable.

No liveness probe is performed — dead connections are detected on the first write/read and discarded by the caller. This eliminates 3 syscalls per reuse (SetReadDeadline + Read + SetReadDeadline).

func (*ConnPool) Put

func (p *ConnPool) Put(conn net.Conn)

Put returns a connection to the pool for reuse. If the pool is full or closed, the connection is closed.

func (*ConnPool) Stats

func (p *ConnPool) Stats() int

Stats returns the current number of idle connections (for monitoring/testing).

type Header

type Header struct {
	Version       uint8
	Type          uint8
	RequestID     uint16
	ContentLength uint16
	PaddingLength uint8
}

Header represents a FastCGI record header.

type PoolConfig

type PoolConfig struct {
	// MaxIdle is the maximum number of idle connections kept in the pool.
	MaxIdle int
	// IdleTimeout is how long an idle connection can sit unused before being closed.
	IdleTimeout time.Duration
}

PoolConfig holds connection pool parameters.

func DefaultPoolConfig

func DefaultPoolConfig() PoolConfig

DefaultPoolConfig returns sensible pool defaults.

type Record

type Record struct {
	Header  Header
	Content []byte
}

Record represents a single FastCGI record.

func ReadRecord

func ReadRecord(r io.Reader) (Record, error)

ReadRecord reads a single FastCGI record from the reader. The returned Content slice is a copy owned by the caller.

func ReadRecordInto

func ReadRecordInto(r io.Reader, stdout, stderr *bytes.Buffer, maxStdout, maxStderr int) (Record, error)

ReadRecordInto reads a FastCGI record and appends stdout/stderr content directly into the provided buffer, eliminating intermediate copies. Returns the header and the number of content bytes appended. For non-stdout/stderr records, content is returned in the Record.Content field.

type Request

type Request struct {
	Params map[string]string
	Stdin  io.Reader
}

Request represents a FastCGI request to send upstream.

type Response

type Response struct {
	StatusCode int
	Headers    map[string][]string
	Body       []byte
	Stderr     []byte
}

Response holds the parsed FastCGI response.