fcgi.go

     1  // Copyright 2011 The Go Authors. All rights reserved.
     2  // Use of this source code is governed by a BSD-style
     3  // license that can be found in the LICENSE file.
     4  
     5  // Package fcgi implements the FastCGI protocol.
     6  //
     7  // See https://fast-cgi.github.io/ for an unofficial mirror of the
     8  // original documentation.
     9  //
    10  // Currently only the responder role is supported.
    11  package fcgi
    12  
    13  // This file defines the raw protocol and some utilities used by the child and
    14  // the host.
    15  
    16  import (
    17  	"bufio"
    18  	"bytes"
    19  	"encoding/binary"
    20  	"errors"
    21  	"io"
    22  	"sync"
    23  )
    24  
    25  // recType is a record type, as defined by
    26  // https://web.archive.org/web/20150420080736/http://www.fastcgi.com/drupal/node/6?q=node/22#S8
    27  type recType uint8
    28  
    29  const (
    30  	typeBeginRequest    recType = 1
    31  	typeAbortRequest    recType = 2
    32  	typeEndRequest      recType = 3
    33  	typeParams          recType = 4
    34  	typeStdin           recType = 5
    35  	typeStdout          recType = 6
    36  	typeStderr          recType = 7
    37  	typeData            recType = 8
    38  	typeGetValues       recType = 9
    39  	typeGetValuesResult recType = 10
    40  	typeUnknownType     recType = 11
    41  )
    42  
    43  // keep the connection between web-server and responder open after request
    44  const flagKeepConn = 1
    45  
    46  const (
    47  	maxWrite = 65535 // maximum record body
    48  	maxPad   = 255
    49  )
    50  
    51  const (
    52  	roleResponder = iota + 1 // only Responders are implemented.
    53  	roleAuthorizer
    54  	roleFilter
    55  )
    56  
    57  const (
    58  	statusRequestComplete = iota
    59  	statusCantMultiplex
    60  	statusOverloaded
    61  	statusUnknownRole
    62  )
    63  
    64  type header struct {
    65  	Version       uint8
    66  	Type          recType
    67  	Id            uint16
    68  	ContentLength uint16
    69  	PaddingLength uint8
    70  	Reserved      uint8
    71  }
    72  
    73  type beginRequest struct {
    74  	role     uint16
    75  	flags    uint8
    76  	reserved [5]uint8
    77  }
    78  
    79  func (br *beginRequest) read(content []byte) error {
    80  	if len(content) != 8 {
    81  		return errors.New("fcgi: invalid begin request record")
    82  	}
    83  	br.role = binary.BigEndian.Uint16(content)
    84  	br.flags = content[2]
    85  	return nil
    86  }
    87  
    88  // for padding so we don't have to allocate all the time
    89  // not synchronized because we don't care what the contents are
    90  var pad [maxPad]byte
    91  
    92  func (h *header) init(recType recType, reqId uint16, contentLength int) {
    93  	h.Version = 1
    94  	h.Type = recType
    95  	h.Id = reqId
    96  	h.ContentLength = uint16(contentLength)
    97  	h.PaddingLength = uint8(-contentLength & 7)
    98  }
    99  
   100  // conn sends records over rwc
   101  type conn struct {
   102  	mutex    sync.Mutex
   103  	rwc      io.ReadWriteCloser
   104  	closeErr error
   105  	closed   bool
   106  
   107  	// to avoid allocations
   108  	buf bytes.Buffer
   109  	h   header
   110  }
   111  
   112  func newConn(rwc io.ReadWriteCloser) *conn {
   113  	return &conn{rwc: rwc}
   114  }
   115  
   116  // Close closes the conn if it is not already closed.
   117  func (c *conn) Close() error {
   118  	c.mutex.Lock()
   119  	defer c.mutex.Unlock()
   120  	if !c.closed {
   121  		c.closeErr = c.rwc.Close()
   122  		c.closed = true
   123  	}
   124  	return c.closeErr
   125  }
   126  
   127  type record struct {
   128  	h   header
   129  	buf [maxWrite + maxPad]byte
   130  }
   131  
   132  func (rec *record) read(r io.Reader) (err error) {
   133  	if err = binary.Read(r, binary.BigEndian, &rec.h); err != nil {
   134  		return err
   135  	}
   136  	if rec.h.Version != 1 {
   137  		return errors.New("fcgi: invalid header version")
   138  	}
   139  	n := int(rec.h.ContentLength) + int(rec.h.PaddingLength)
   140  	if _, err = io.ReadFull(r, rec.buf[:n]); err != nil {
   141  		return err
   142  	}
   143  	return nil
   144  }
   145  
   146  func (r *record) content() []byte {
   147  	return r.buf[:r.h.ContentLength]
   148  }
   149  
   150  // writeRecord writes and sends a single record.
   151  func (c *conn) writeRecord(recType recType, reqId uint16, b []byte) error {
   152  	c.mutex.Lock()
   153  	defer c.mutex.Unlock()
   154  	c.buf.Reset()
   155  	c.h.init(recType, reqId, len(b))
   156  	if err := binary.Write(&c.buf, binary.BigEndian, c.h); err != nil {
   157  		return err
   158  	}
   159  	if _, err := c.buf.Write(b); err != nil {
   160  		return err
   161  	}
   162  	if _, err := c.buf.Write(pad[:c.h.PaddingLength]); err != nil {
   163  		return err
   164  	}
   165  	_, err := c.rwc.Write(c.buf.Bytes())
   166  	return err
   167  }
   168  
   169  func (c *conn) writeEndRequest(reqId uint16, appStatus int, protocolStatus uint8) error {
   170  	b := make([]byte, 8)
   171  	binary.BigEndian.PutUint32(b, uint32(appStatus))
   172  	b[4] = protocolStatus
   173  	return c.writeRecord(typeEndRequest, reqId, b)
   174  }
   175  
   176  func (c *conn) writePairs(recType recType, reqId uint16, pairs map[string]string) error {
   177  	w := newWriter(c, recType, reqId)
   178  	b := make([]byte, 8)
   179  	for k, v := range pairs {
   180  		n := encodeSize(b, uint32(len(k)))
   181  		n += encodeSize(b[n:], uint32(len(v)))
   182  		if _, err := w.Write(b[:n]); err != nil {
   183  			return err
   184  		}
   185  		if _, err := w.WriteString(k); err != nil {
   186  			return err
   187  		}
   188  		if _, err := w.WriteString(v); err != nil {
   189  			return err
   190  		}
   191  	}
   192  	return w.Close()
   193  }
   194  
   195  func readSize(s []byte) (uint32, int) {
   196  	if len(s) == 0 {
   197  		return 0, 0
   198  	}
   199  	size, n := uint32(s[0]), 1
   200  	if size&(1<<7) != 0 {
   201  		if len(s) < 4 {
   202  			return 0, 0
   203  		}
   204  		n = 4
   205  		size = binary.BigEndian.Uint32(s)
   206  		size &^= 1 << 31
   207  	}
   208  	return size, n
   209  }
   210  
   211  func readString(s []byte, size uint32) string {
   212  	if size > uint32(len(s)) {
   213  		return ""
   214  	}
   215  	return string(s[:size])
   216  }
   217  
   218  func encodeSize(b []byte, size uint32) int {
   219  	if size > 127 {
   220  		size |= 1 << 31
   221  		binary.BigEndian.PutUint32(b, size)
   222  		return 4
   223  	}
   224  	b[0] = byte(size)
   225  	return 1
   226  }
   227  
   228  // bufWriter encapsulates bufio.Writer but also closes the underlying stream when
   229  // Closed.
   230  type bufWriter struct {
   231  	closer io.Closer
   232  	*bufio.Writer
   233  }
   234  
   235  func (w *bufWriter) Close() error {
   236  	if err := w.Writer.Flush(); err != nil {
   237  		w.closer.Close()
   238  		return err
   239  	}
   240  	return w.closer.Close()
   241  }
   242  
   243  func newWriter(c *conn, recType recType, reqId uint16) *bufWriter {
   244  	s := &streamWriter{c: c, recType: recType, reqId: reqId}
   245  	w := bufio.NewWriterSize(s, maxWrite)
   246  	return &bufWriter{s, w}
   247  }
   248  
   249  // streamWriter abstracts out the separation of a stream into discrete records.
   250  // It only writes maxWrite bytes at a time.
   251  type streamWriter struct {
   252  	c       *conn
   253  	recType recType
   254  	reqId   uint16
   255  }
   256  
   257  func (w *streamWriter) Write(p []byte) (int, error) {
   258  	nn := 0
   259  	for len(p) > 0 {
   260  		n := len(p)
   261  		if n > maxWrite {
   262  			n = maxWrite
   263  		}
   264  		if err := w.c.writeRecord(w.recType, w.reqId, p[:n]); err != nil {
   265  			return nn, err
   266  		}
   267  		nn += n
   268  		p = p[n:]
   269  	}
   270  	return nn, nil
   271  }
   272  
   273  func (w *streamWriter) Close() error {
   274  	// send empty record to close the stream
   275  	return w.c.writeRecord(w.recType, w.reqId, nil)
   276  }
   277
View as plain text