The Go Programming Language

Source file src/pkg/http/server.go

     1	// Copyright 2009 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	// HTTP server.  See RFC 2616.
     6	
     7	// TODO(rsc):
     8	//	logging
     9	
    10	package http
    11	
    12	import (
    13		"bufio"
    14		"bytes"
    15		"crypto/rand"
    16		"crypto/tls"
    17		"fmt"
    18		"io"
    19		"log"
    20		"net"
    21		"os"
    22		"path"
    23		"runtime/debug"
    24		"strconv"
    25		"strings"
    26		"sync"
    27		"time"
    28		"url"
    29	)
    30	
    31	// Errors introduced by the HTTP server.
    32	var (
    33		ErrWriteAfterFlush = os.NewError("Conn.Write called after Flush")
    34		ErrBodyNotAllowed  = os.NewError("http: response status code does not allow body")
    35		ErrHijacked        = os.NewError("Conn has been hijacked")
    36		ErrContentLength   = os.NewError("Conn.Write wrote more than the declared Content-Length")
    37	)
    38	
    39	// Objects implementing the Handler interface can be
    40	// registered to serve a particular path or subtree
    41	// in the HTTP server.
    42	//
    43	// ServeHTTP should write reply headers and data to the ResponseWriter
    44	// and then return.  Returning signals that the request is finished
    45	// and that the HTTP server can move on to the next request on
    46	// the connection.
    47	type Handler interface {
    48		ServeHTTP(ResponseWriter, *Request)
    49	}
    50	
    51	// A ResponseWriter interface is used by an HTTP handler to
    52	// construct an HTTP response.
    53	type ResponseWriter interface {
    54		// Header returns the header map that will be sent by WriteHeader.
    55		// Changing the header after a call to WriteHeader (or Write) has
    56		// no effect.
    57		Header() Header
    58	
    59		// Write writes the data to the connection as part of an HTTP reply.
    60		// If WriteHeader has not yet been called, Write calls WriteHeader(http.StatusOK)
    61		// before writing the data.
    62		Write([]byte) (int, os.Error)
    63	
    64		// WriteHeader sends an HTTP response header with status code.
    65		// If WriteHeader is not called explicitly, the first call to Write
    66		// will trigger an implicit WriteHeader(http.StatusOK).
    67		// Thus explicit calls to WriteHeader are mainly used to
    68		// send error codes.
    69		WriteHeader(int)
    70	}
    71	
    72	// The Flusher interface is implemented by ResponseWriters that allow
    73	// an HTTP handler to flush buffered data to the client.
    74	//
    75	// Note that even for ResponseWriters that support Flush,
    76	// if the client is connected through an HTTP proxy,
    77	// the buffered data may not reach the client until the response
    78	// completes.
    79	type Flusher interface {
    80		// Flush sends any buffered data to the client.
    81		Flush()
    82	}
    83	
    84	// The Hijacker interface is implemented by ResponseWriters that allow
    85	// an HTTP handler to take over the connection.
    86	type Hijacker interface {
    87		// Hijack lets the caller take over the connection.
    88		// After a call to Hijack(), the HTTP server library
    89		// will not do anything else with the connection.
    90		// It becomes the caller's responsibility to manage
    91		// and close the connection.
    92		Hijack() (net.Conn, *bufio.ReadWriter, os.Error)
    93	}
    94	
    95	// A conn represents the server side of an HTTP connection.
    96	type conn struct {
    97		remoteAddr string               // network address of remote side
    98		server     *Server              // the Server on which the connection arrived
    99		rwc        net.Conn             // i/o connection
   100		lr         *io.LimitedReader    // io.LimitReader(rwc)
   101		buf        *bufio.ReadWriter    // buffered(lr,rwc), reading from bufio->limitReader->rwc
   102		hijacked   bool                 // connection has been hijacked by handler
   103		tlsState   *tls.ConnectionState // or nil when not using TLS
   104		body       []byte
   105	}
   106	
   107	// A response represents the server side of an HTTP response.
   108	type response struct {
   109		conn          *conn
   110		req           *Request // request for this response
   111		chunking      bool     // using chunked transfer encoding for reply body
   112		wroteHeader   bool     // reply header has been written
   113		wroteContinue bool     // 100 Continue response was written
   114		header        Header   // reply header parameters
   115		written       int64    // number of bytes written in body
   116		contentLength int64    // explicitly-declared Content-Length; or -1
   117		status        int      // status code passed to WriteHeader
   118		needSniff     bool     // need to sniff to find Content-Type
   119	
   120		// close connection after this reply.  set on request and
   121		// updated after response from handler if there's a
   122		// "Connection: keep-alive" response header and a
   123		// Content-Length.
   124		closeAfterReply bool
   125	}
   126	
   127	type writerOnly struct {
   128		io.Writer
   129	}
   130	
   131	func (r *response) ReadFrom(src io.Reader) (n int64, err os.Error) {
   132		// Flush before checking r.chunking, as Flush will call
   133		// WriteHeader if it hasn't been called yet, and WriteHeader
   134		// is what sets r.chunking.
   135		r.Flush()
   136		if !r.chunking && r.bodyAllowed() && !r.needSniff {
   137			if rf, ok := r.conn.rwc.(io.ReaderFrom); ok {
   138				n, err = rf.ReadFrom(src)
   139				r.written += n
   140				return
   141			}
   142		}
   143		// Fall back to default io.Copy implementation.
   144		// Use wrapper to hide r.ReadFrom from io.Copy.
   145		return io.Copy(writerOnly{r}, src)
   146	}
   147	
   148	// noLimit is an effective infinite upper bound for io.LimitedReader
   149	const noLimit int64 = (1 << 63) - 1
   150	
   151	// Create new connection from rwc.
   152	func (srv *Server) newConn(rwc net.Conn) (c *conn, err os.Error) {
   153		c = new(conn)
   154		c.remoteAddr = rwc.RemoteAddr().String()
   155		c.server = srv
   156		c.rwc = rwc
   157		c.body = make([]byte, sniffLen)
   158		c.lr = io.LimitReader(rwc, noLimit).(*io.LimitedReader)
   159		br := bufio.NewReader(c.lr)
   160		bw := bufio.NewWriter(rwc)
   161		c.buf = bufio.NewReadWriter(br, bw)
   162	
   163		if tlsConn, ok := rwc.(*tls.Conn); ok {
   164			tlsConn.Handshake()
   165			c.tlsState = new(tls.ConnectionState)
   166			*c.tlsState = tlsConn.ConnectionState()
   167		}
   168	
   169		return c, nil
   170	}
   171	
   172	// DefaultMaxHeaderBytes is the maximum permitted size of the headers
   173	// in an HTTP request.
   174	// This can be overridden by setting Server.MaxHeaderBytes.
   175	const DefaultMaxHeaderBytes = 1 << 20 // 1 MB
   176	
   177	func (srv *Server) maxHeaderBytes() int {
   178		if srv.MaxHeaderBytes > 0 {
   179			return srv.MaxHeaderBytes
   180		}
   181		return DefaultMaxHeaderBytes
   182	}
   183	
   184	// wrapper around io.ReaderCloser which on first read, sends an
   185	// HTTP/1.1 100 Continue header
   186	type expectContinueReader struct {
   187		resp       *response
   188		readCloser io.ReadCloser
   189		closed     bool
   190	}
   191	
   192	func (ecr *expectContinueReader) Read(p []byte) (n int, err os.Error) {
   193		if ecr.closed {
   194			return 0, os.NewError("http: Read after Close on request Body")
   195		}
   196		if !ecr.resp.wroteContinue && !ecr.resp.conn.hijacked {
   197			ecr.resp.wroteContinue = true
   198			io.WriteString(ecr.resp.conn.buf, "HTTP/1.1 100 Continue\r\n\r\n")
   199			ecr.resp.conn.buf.Flush()
   200		}
   201		return ecr.readCloser.Read(p)
   202	}
   203	
   204	func (ecr *expectContinueReader) Close() os.Error {
   205		ecr.closed = true
   206		return ecr.readCloser.Close()
   207	}
   208	
   209	// TimeFormat is the time format to use with
   210	// time.Parse and time.Time.Format when parsing
   211	// or generating times in HTTP headers.
   212	// It is like time.RFC1123 but hard codes GMT as the time zone.
   213	const TimeFormat = "Mon, 02 Jan 2006 15:04:05 GMT"
   214	
   215	var errTooLarge = os.NewError("http: request too large")
   216	
   217	// Read next request from connection.
   218	func (c *conn) readRequest() (w *response, err os.Error) {
   219		if c.hijacked {
   220			return nil, ErrHijacked
   221		}
   222		c.lr.N = int64(c.server.maxHeaderBytes()) + 4096 /* bufio slop */
   223		var req *Request
   224		if req, err = ReadRequest(c.buf.Reader); err != nil {
   225			if c.lr.N == 0 {
   226				return nil, errTooLarge
   227			}
   228			return nil, err
   229		}
   230		c.lr.N = noLimit
   231	
   232		req.RemoteAddr = c.remoteAddr
   233		req.TLS = c.tlsState
   234	
   235		w = new(response)
   236		w.conn = c
   237		w.req = req
   238		w.header = make(Header)
   239		w.contentLength = -1
   240		c.body = c.body[:0]
   241		return w, nil
   242	}
   243	
   244	func (w *response) Header() Header {
   245		return w.header
   246	}
   247	
   248	func (w *response) WriteHeader(code int) {
   249		if w.conn.hijacked {
   250			log.Print("http: response.WriteHeader on hijacked connection")
   251			return
   252		}
   253		if w.wroteHeader {
   254			log.Print("http: multiple response.WriteHeader calls")
   255			return
   256		}
   257	
   258		// Per RFC 2616, we should consume the request body before
   259		// replying, if the handler hasn't already done so.
   260		if w.req.ContentLength != 0 {
   261			ecr, isExpecter := w.req.Body.(*expectContinueReader)
   262			if !isExpecter || ecr.resp.wroteContinue {
   263				w.req.Body.Close()
   264			}
   265		}
   266	
   267		w.wroteHeader = true
   268		w.status = code
   269		if code == StatusNotModified {
   270			// Must not have body.
   271			for _, header := range []string{"Content-Type", "Content-Length", "Transfer-Encoding"} {
   272				if w.header.Get(header) != "" {
   273					// TODO: return an error if WriteHeader gets a return parameter
   274					// or set a flag on w to make future Writes() write an error page?
   275					// for now just log and drop the header.
   276					log.Printf("http: StatusNotModified response with header %q defined", header)
   277					w.header.Del(header)
   278				}
   279			}
   280		} else {
   281			// If no content type, apply sniffing algorithm to body.
   282			if w.header.Get("Content-Type") == "" {
   283				w.needSniff = true
   284			}
   285		}
   286	
   287		if _, ok := w.header["Date"]; !ok {
   288			w.Header().Set("Date", time.UTC().Format(TimeFormat))
   289		}
   290	
   291		// Check for a explicit (and valid) Content-Length header.
   292		var hasCL bool
   293		var contentLength int64
   294		if clenStr := w.header.Get("Content-Length"); clenStr != "" {
   295			var err os.Error
   296			contentLength, err = strconv.Atoi64(clenStr)
   297			if err == nil {
   298				hasCL = true
   299			} else {
   300				log.Printf("http: invalid Content-Length of %q sent", clenStr)
   301				w.header.Del("Content-Length")
   302			}
   303		}
   304	
   305		te := w.header.Get("Transfer-Encoding")
   306		hasTE := te != ""
   307		if hasCL && hasTE && te != "identity" {
   308			// TODO: return an error if WriteHeader gets a return parameter
   309			// For now just ignore the Content-Length.
   310			log.Printf("http: WriteHeader called with both Transfer-Encoding of %q and a Content-Length of %d",
   311				te, contentLength)
   312			w.header.Del("Content-Length")
   313			hasCL = false
   314		}
   315	
   316		if w.req.Method == "HEAD" || code == StatusNotModified {
   317			// do nothing
   318		} else if hasCL {
   319			w.contentLength = contentLength
   320			w.header.Del("Transfer-Encoding")
   321		} else if w.req.ProtoAtLeast(1, 1) {
   322			// HTTP/1.1 or greater: use chunked transfer encoding
   323			// to avoid closing the connection at EOF.
   324			// TODO: this blows away any custom or stacked Transfer-Encoding they
   325			// might have set.  Deal with that as need arises once we have a valid
   326			// use case.
   327			w.chunking = true
   328			w.header.Set("Transfer-Encoding", "chunked")
   329		} else {
   330			// HTTP version < 1.1: cannot do chunked transfer
   331			// encoding and we don't know the Content-Length so
   332			// signal EOF by closing connection.
   333			w.closeAfterReply = true
   334			w.header.Del("Transfer-Encoding") // in case already set
   335		}
   336	
   337		if w.req.wantsHttp10KeepAlive() && (w.req.Method == "HEAD" || hasCL) {
   338			_, connectionHeaderSet := w.header["Connection"]
   339			if !connectionHeaderSet {
   340				w.header.Set("Connection", "keep-alive")
   341			}
   342		} else if !w.req.ProtoAtLeast(1, 1) {
   343			// Client did not ask to keep connection alive.
   344			w.closeAfterReply = true
   345		}
   346	
   347		if w.header.Get("Connection") == "close" {
   348			w.closeAfterReply = true
   349		}
   350	
   351		// Cannot use Content-Length with non-identity Transfer-Encoding.
   352		if w.chunking {
   353			w.header.Del("Content-Length")
   354		}
   355		if !w.req.ProtoAtLeast(1, 0) {
   356			return
   357		}
   358		proto := "HTTP/1.0"
   359		if w.req.ProtoAtLeast(1, 1) {
   360			proto = "HTTP/1.1"
   361		}
   362		codestring := strconv.Itoa(code)
   363		text, ok := statusText[code]
   364		if !ok {
   365			text = "status code " + codestring
   366		}
   367		io.WriteString(w.conn.buf, proto+" "+codestring+" "+text+"\r\n")
   368		w.header.Write(w.conn.buf)
   369	
   370		// If we need to sniff the body, leave the header open.
   371		// Otherwise, end it here.
   372		if !w.needSniff {
   373			io.WriteString(w.conn.buf, "\r\n")
   374		}
   375	}
   376	
   377	// sniff uses the first block of written data,
   378	// stored in w.conn.body, to decide the Content-Type
   379	// for the HTTP body.
   380	func (w *response) sniff() {
   381		if !w.needSniff {
   382			return
   383		}
   384		w.needSniff = false
   385	
   386		data := w.conn.body
   387		fmt.Fprintf(w.conn.buf, "Content-Type: %s\r\n\r\n", DetectContentType(data))
   388	
   389		if len(data) == 0 {
   390			return
   391		}
   392		if w.chunking {
   393			fmt.Fprintf(w.conn.buf, "%x\r\n", len(data))
   394		}
   395		_, err := w.conn.buf.Write(data)
   396		if w.chunking && err == nil {
   397			io.WriteString(w.conn.buf, "\r\n")
   398		}
   399	}
   400	
   401	// bodyAllowed returns true if a Write is allowed for this response type.
   402	// It's illegal to call this before the header has been flushed.
   403	func (w *response) bodyAllowed() bool {
   404		if !w.wroteHeader {
   405			panic("")
   406		}
   407		return w.status != StatusNotModified && w.req.Method != "HEAD"
   408	}
   409	
   410	func (w *response) Write(data []byte) (n int, err os.Error) {
   411		if w.conn.hijacked {
   412			log.Print("http: response.Write on hijacked connection")
   413			return 0, ErrHijacked
   414		}
   415		if !w.wroteHeader {
   416			w.WriteHeader(StatusOK)
   417		}
   418		if len(data) == 0 {
   419			return 0, nil
   420		}
   421		if !w.bodyAllowed() {
   422			return 0, ErrBodyNotAllowed
   423		}
   424	
   425		w.written += int64(len(data)) // ignoring errors, for errorKludge
   426		if w.contentLength != -1 && w.written > w.contentLength {
   427			return 0, ErrContentLength
   428		}
   429	
   430		var m int
   431		if w.needSniff {
   432			// We need to sniff the beginning of the output to
   433			// determine the content type.  Accumulate the
   434			// initial writes in w.conn.body.
   435			// Cap m so that append won't allocate.
   436			m := cap(w.conn.body) - len(w.conn.body)
   437			if m > len(data) {
   438				m = len(data)
   439			}
   440			w.conn.body = append(w.conn.body, data[:m]...)
   441			data = data[m:]
   442			if len(data) == 0 {
   443				// Copied everything into the buffer.
   444				// Wait for next write.
   445				return m, nil
   446			}
   447	
   448			// Filled the buffer; more data remains.
   449			// Sniff the content (flushes the buffer)
   450			// and then proceed with the remainder
   451			// of the data as a normal Write.
   452			// Calling sniff clears needSniff.
   453			w.sniff()
   454		}
   455	
   456		// TODO(rsc): if chunking happened after the buffering,
   457		// then there would be fewer chunk headers.
   458		// On the other hand, it would make hijacking more difficult.
   459		if w.chunking {
   460			fmt.Fprintf(w.conn.buf, "%x\r\n", len(data)) // TODO(rsc): use strconv not fmt
   461		}
   462		n, err = w.conn.buf.Write(data)
   463		if err == nil && w.chunking {
   464			if n != len(data) {
   465				err = io.ErrShortWrite
   466			}
   467			if err == nil {
   468				io.WriteString(w.conn.buf, "\r\n")
   469			}
   470		}
   471	
   472		return m + n, err
   473	}
   474	
   475	// If this is an error reply (4xx or 5xx)
   476	// and the handler wrote some data explaining the error,
   477	// some browsers (i.e., Chrome, Internet Explorer)
   478	// will show their own error instead unless the error is
   479	// long enough.  The minimum lengths used in those
   480	// browsers are in the 256-512 range.
   481	// Pad to 1024 bytes.
   482	func errorKludge(w *response) {
   483		const min = 1024
   484	
   485		// Is this an error?
   486		if kind := w.status / 100; kind != 4 && kind != 5 {
   487			return
   488		}
   489	
   490		// Did the handler supply any info?  Enough?
   491		if w.written == 0 || w.written >= min {
   492			return
   493		}
   494	
   495		// Is it a broken browser?
   496		var msg string
   497		switch agent := w.req.UserAgent(); {
   498		case strings.Contains(agent, "MSIE"):
   499			msg = "Internet Explorer"
   500		case strings.Contains(agent, "Chrome/"):
   501			msg = "Chrome"
   502		default:
   503			return
   504		}
   505		msg += " would ignore this error page if this text weren't here.\n"
   506	
   507		// Is it text?  ("Content-Type" is always in the map)
   508		baseType := strings.SplitN(w.header.Get("Content-Type"), ";", 2)[0]
   509		switch baseType {
   510		case "text/html":
   511			io.WriteString(w, "<!-- ")
   512			for w.written < min {
   513				io.WriteString(w, msg)
   514			}
   515			io.WriteString(w, " -->")
   516		case "text/plain":
   517			io.WriteString(w, "\n")
   518			for w.written < min {
   519				io.WriteString(w, msg)
   520			}
   521		}
   522	}
   523	
   524	func (w *response) finishRequest() {
   525		// If this was an HTTP/1.0 request with keep-alive and we sent a Content-Length
   526		// back, we can make this a keep-alive response ...
   527		if w.req.wantsHttp10KeepAlive() {
   528			sentLength := w.header.Get("Content-Length") != ""
   529			if sentLength && w.header.Get("Connection") == "keep-alive" {
   530				w.closeAfterReply = false
   531			}
   532		}
   533		if !w.wroteHeader {
   534			w.WriteHeader(StatusOK)
   535		}
   536		if w.needSniff {
   537			w.sniff()
   538		}
   539		errorKludge(w)
   540		if w.chunking {
   541			io.WriteString(w.conn.buf, "0\r\n")
   542			// trailer key/value pairs, followed by blank line
   543			io.WriteString(w.conn.buf, "\r\n")
   544		}
   545		w.conn.buf.Flush()
   546		w.req.Body.Close()
   547		if w.req.MultipartForm != nil {
   548			w.req.MultipartForm.RemoveAll()
   549		}
   550	
   551		if w.contentLength != -1 && w.contentLength != w.written {
   552			// Did not write enough. Avoid getting out of sync.
   553			w.closeAfterReply = true
   554		}
   555	}
   556	
   557	func (w *response) Flush() {
   558		if !w.wroteHeader {
   559			w.WriteHeader(StatusOK)
   560		}
   561		w.sniff()
   562		w.conn.buf.Flush()
   563	}
   564	
   565	// Close the connection.
   566	func (c *conn) close() {
   567		if c.buf != nil {
   568			c.buf.Flush()
   569			c.buf = nil
   570		}
   571		if c.rwc != nil {
   572			c.rwc.Close()
   573			c.rwc = nil
   574		}
   575	}
   576	
   577	// Serve a new connection.
   578	func (c *conn) serve() {
   579		defer func() {
   580			err := recover()
   581			if err == nil {
   582				return
   583			}
   584			c.rwc.Close()
   585	
   586			var buf bytes.Buffer
   587			fmt.Fprintf(&buf, "http: panic serving %v: %v\n", c.remoteAddr, err)
   588			buf.Write(debug.Stack())
   589			log.Print(buf.String())
   590		}()
   591	
   592		for {
   593			w, err := c.readRequest()
   594			if err != nil {
   595				if err == errTooLarge {
   596					// Their HTTP client may or may not be
   597					// able to read this if we're
   598					// responding to them and hanging up
   599					// while they're still writing their
   600					// request.  Undefined behavior.
   601					fmt.Fprintf(c.rwc, "HTTP/1.1 400 Request Too Large\r\n\r\n")
   602				}
   603				break
   604			}
   605	
   606			// Expect 100 Continue support
   607			req := w.req
   608			if req.expectsContinue() {
   609				if req.ProtoAtLeast(1, 1) {
   610					// Wrap the Body reader with one that replies on the connection
   611					req.Body = &expectContinueReader{readCloser: req.Body, resp: w}
   612				}
   613				if req.ContentLength == 0 {
   614					w.Header().Set("Connection", "close")
   615					w.WriteHeader(StatusBadRequest)
   616					w.finishRequest()
   617					break
   618				}
   619				req.Header.Del("Expect")
   620			} else if req.Header.Get("Expect") != "" {
   621				// TODO(bradfitz): let ServeHTTP handlers handle
   622				// requests with non-standard expectation[s]? Seems
   623				// theoretical at best, and doesn't fit into the
   624				// current ServeHTTP model anyway.  We'd need to
   625				// make the ResponseWriter an optional
   626				// "ExpectReplier" interface or something.
   627				//
   628				// For now we'll just obey RFC 2616 14.20 which says
   629				// "If a server receives a request containing an
   630				// Expect field that includes an expectation-
   631				// extension that it does not support, it MUST
   632				// respond with a 417 (Expectation Failed) status."
   633				w.Header().Set("Connection", "close")
   634				w.WriteHeader(StatusExpectationFailed)
   635				w.finishRequest()
   636				break
   637			}
   638	
   639			handler := c.server.Handler
   640			if handler == nil {
   641				handler = DefaultServeMux
   642			}
   643	
   644			// HTTP cannot have multiple simultaneous active requests.[*]
   645			// Until the server replies to this request, it can't read another,
   646			// so we might as well run the handler in this goroutine.
   647			// [*] Not strictly true: HTTP pipelining.  We could let them all process
   648			// in parallel even if their responses need to be serialized.
   649			handler.ServeHTTP(w, w.req)
   650			if c.hijacked {
   651				return
   652			}
   653			w.finishRequest()
   654			if w.closeAfterReply {
   655				break
   656			}
   657		}
   658		c.close()
   659	}
   660	
   661	// Hijack implements the Hijacker.Hijack method. Our response is both a ResponseWriter
   662	// and a Hijacker.
   663	func (w *response) Hijack() (rwc net.Conn, buf *bufio.ReadWriter, err os.Error) {
   664		if w.conn.hijacked {
   665			return nil, nil, ErrHijacked
   666		}
   667		w.conn.hijacked = true
   668		rwc = w.conn.rwc
   669		buf = w.conn.buf
   670		w.conn.rwc = nil
   671		w.conn.buf = nil
   672		return
   673	}
   674	
   675	// The HandlerFunc type is an adapter to allow the use of
   676	// ordinary functions as HTTP handlers.  If f is a function
   677	// with the appropriate signature, HandlerFunc(f) is a
   678	// Handler object that calls f.
   679	type HandlerFunc func(ResponseWriter, *Request)
   680	
   681	// ServeHTTP calls f(w, r).
   682	func (f HandlerFunc) ServeHTTP(w ResponseWriter, r *Request) {
   683		f(w, r)
   684	}
   685	
   686	// Helper handlers
   687	
   688	// Error replies to the request with the specified error message and HTTP code.
   689	func Error(w ResponseWriter, error string, code int) {
   690		w.Header().Set("Content-Type", "text/plain; charset=utf-8")
   691		w.WriteHeader(code)
   692		fmt.Fprintln(w, error)
   693	}
   694	
   695	// NotFound replies to the request with an HTTP 404 not found error.
   696	func NotFound(w ResponseWriter, r *Request) { Error(w, "404 page not found", StatusNotFound) }
   697	
   698	// NotFoundHandler returns a simple request handler
   699	// that replies to each request with a ``404 page not found'' reply.
   700	func NotFoundHandler() Handler { return HandlerFunc(NotFound) }
   701	
   702	// StripPrefix returns a handler that serves HTTP requests
   703	// by removing the given prefix from the request URL's Path
   704	// and invoking the handler h. StripPrefix handles a
   705	// request for a path that doesn't begin with prefix by
   706	// replying with an HTTP 404 not found error.
   707	func StripPrefix(prefix string, h Handler) Handler {
   708		return HandlerFunc(func(w ResponseWriter, r *Request) {
   709			if !strings.HasPrefix(r.URL.Path, prefix) {
   710				NotFound(w, r)
   711				return
   712			}
   713			r.URL.Path = r.URL.Path[len(prefix):]
   714			h.ServeHTTP(w, r)
   715		})
   716	}
   717	
   718	// Redirect replies to the request with a redirect to url,
   719	// which may be a path relative to the request path.
   720	func Redirect(w ResponseWriter, r *Request, urlStr string, code int) {
   721		if u, err := url.Parse(urlStr); err == nil {
   722			// If url was relative, make absolute by
   723			// combining with request path.
   724			// The browser would probably do this for us,
   725			// but doing it ourselves is more reliable.
   726	
   727			// NOTE(rsc): RFC 2616 says that the Location
   728			// line must be an absolute URI, like
   729			// "http://www.google.com/redirect/",
   730			// not a path like "/redirect/".
   731			// Unfortunately, we don't know what to
   732			// put in the host name section to get the
   733			// client to connect to us again, so we can't
   734			// know the right absolute URI to send back.
   735			// Because of this problem, no one pays attention
   736			// to the RFC; they all send back just a new path.
   737			// So do we.
   738			oldpath := r.URL.Path
   739			if oldpath == "" { // should not happen, but avoid a crash if it does
   740				oldpath = "/"
   741			}
   742			if u.Scheme == "" {
   743				// no leading http://server
   744				if urlStr == "" || urlStr[0] != '/' {
   745					// make relative path absolute
   746					olddir, _ := path.Split(oldpath)
   747					urlStr = olddir + urlStr
   748				}
   749	
   750				var query string
   751				if i := strings.Index(urlStr, "?"); i != -1 {
   752					urlStr, query = urlStr[:i], urlStr[i:]
   753				}
   754	
   755				// clean up but preserve trailing slash
   756				trailing := urlStr[len(urlStr)-1] == '/'
   757				urlStr = path.Clean(urlStr)
   758				if trailing && urlStr[len(urlStr)-1] != '/' {
   759					urlStr += "/"
   760				}
   761				urlStr += query
   762			}
   763		}
   764	
   765		w.Header().Set("Location", urlStr)
   766		w.WriteHeader(code)
   767	
   768		// RFC2616 recommends that a short note "SHOULD" be included in the
   769		// response because older user agents may not understand 301/307.
   770		// Shouldn't send the response for POST or HEAD; that leaves GET.
   771		if r.Method == "GET" {
   772			note := "<a href=\"" + htmlEscape(urlStr) + "\">" + statusText[code] + "</a>.\n"
   773			fmt.Fprintln(w, note)
   774		}
   775	}
   776	
   777	func htmlEscape(s string) string {
   778		s = strings.Replace(s, "&", "&amp;", -1)
   779		s = strings.Replace(s, "<", "&lt;", -1)
   780		s = strings.Replace(s, ">", "&gt;", -1)
   781		s = strings.Replace(s, "\"", "&quot;", -1)
   782		s = strings.Replace(s, "'", "&apos;", -1)
   783		return s
   784	}
   785	
   786	// Redirect to a fixed URL
   787	type redirectHandler struct {
   788		url  string
   789		code int
   790	}
   791	
   792	func (rh *redirectHandler) ServeHTTP(w ResponseWriter, r *Request) {
   793		Redirect(w, r, rh.url, rh.code)
   794	}
   795	
   796	// RedirectHandler returns a request handler that redirects
   797	// each request it receives to the given url using the given
   798	// status code.
   799	func RedirectHandler(url string, code int) Handler {
   800		return &redirectHandler{url, code}
   801	}
   802	
   803	// ServeMux is an HTTP request multiplexer.
   804	// It matches the URL of each incoming request against a list of registered
   805	// patterns and calls the handler for the pattern that
   806	// most closely matches the URL.
   807	//
   808	// Patterns named fixed, rooted paths, like "/favicon.ico",
   809	// or rooted subtrees, like "/images/" (note the trailing slash).
   810	// Longer patterns take precedence over shorter ones, so that
   811	// if there are handlers registered for both "/images/"
   812	// and "/images/thumbnails/", the latter handler will be
   813	// called for paths beginning "/images/thumbnails/" and the
   814	// former will receiver requests for any other paths in the
   815	// "/images/" subtree.
   816	//
   817	// Patterns may optionally begin with a host name, restricting matches to
   818	// URLs on that host only.  Host-specific patterns take precedence over
   819	// general patterns, so that a handler might register for the two patterns
   820	// "/codesearch" and "codesearch.google.com/" without also taking over
   821	// requests for "http://www.google.com/".
   822	//
   823	// ServeMux also takes care of sanitizing the URL request path,
   824	// redirecting any request containing . or .. elements to an
   825	// equivalent .- and ..-free URL.
   826	type ServeMux struct {
   827		m map[string]Handler
   828	}
   829	
   830	// NewServeMux allocates and returns a new ServeMux.
   831	func NewServeMux() *ServeMux { return &ServeMux{make(map[string]Handler)} }
   832	
   833	// DefaultServeMux is the default ServeMux used by Serve.
   834	var DefaultServeMux = NewServeMux()
   835	
   836	// Does path match pattern?
   837	func pathMatch(pattern, path string) bool {
   838		if len(pattern) == 0 {
   839			// should not happen
   840			return false
   841		}
   842		n := len(pattern)
   843		if pattern[n-1] != '/' {
   844			return pattern == path
   845		}
   846		return len(path) >= n && path[0:n] == pattern
   847	}
   848	
   849	// Return the canonical path for p, eliminating . and .. elements.
   850	func cleanPath(p string) string {
   851		if p == "" {
   852			return "/"
   853		}
   854		if p[0] != '/' {
   855			p = "/" + p
   856		}
   857		np := path.Clean(p)
   858		// path.Clean removes trailing slash except for root;
   859		// put the trailing slash back if necessary.
   860		if p[len(p)-1] == '/' && np != "/" {
   861			np += "/"
   862		}
   863		return np
   864	}
   865	
   866	// Find a handler on a handler map given a path string
   867	// Most-specific (longest) pattern wins
   868	func (mux *ServeMux) match(path string) Handler {
   869		var h Handler
   870		var n = 0
   871		for k, v := range mux.m {
   872			if !pathMatch(k, path) {
   873				continue
   874			}
   875			if h == nil || len(k) > n {
   876				n = len(k)
   877				h = v
   878			}
   879		}
   880		return h
   881	}
   882	
   883	// ServeHTTP dispatches the request to the handler whose
   884	// pattern most closely matches the request URL.
   885	func (mux *ServeMux) ServeHTTP(w ResponseWriter, r *Request) {
   886		// Clean path to canonical form and redirect.
   887		if p := cleanPath(r.URL.Path); p != r.URL.Path {
   888			w.Header().Set("Location", p)
   889			w.WriteHeader(StatusMovedPermanently)
   890			return
   891		}
   892		// Host-specific pattern takes precedence over generic ones
   893		h := mux.match(r.Host + r.URL.Path)
   894		if h == nil {
   895			h = mux.match(r.URL.Path)
   896		}
   897		if h == nil {
   898			h = NotFoundHandler()
   899		}
   900		h.ServeHTTP(w, r)
   901	}
   902	
   903	// Handle registers the handler for the given pattern.
   904	func (mux *ServeMux) Handle(pattern string, handler Handler) {
   905		if pattern == "" {
   906			panic("http: invalid pattern " + pattern)
   907		}
   908	
   909		mux.m[pattern] = handler
   910	
   911		// Helpful behavior:
   912		// If pattern is /tree/, insert permanent redirect for /tree.
   913		n := len(pattern)
   914		if n > 0 && pattern[n-1] == '/' {
   915			mux.m[pattern[0:n-1]] = RedirectHandler(pattern, StatusMovedPermanently)
   916		}
   917	}
   918	
   919	// HandleFunc registers the handler function for the given pattern.
   920	func (mux *ServeMux) HandleFunc(pattern string, handler func(ResponseWriter, *Request)) {
   921		mux.Handle(pattern, HandlerFunc(handler))
   922	}
   923	
   924	// Handle registers the handler for the given pattern
   925	// in the DefaultServeMux.
   926	// The documentation for ServeMux explains how patterns are matched.
   927	func Handle(pattern string, handler Handler) { DefaultServeMux.Handle(pattern, handler) }
   928	
   929	// HandleFunc registers the handler function for the given pattern
   930	// in the DefaultServeMux.
   931	// The documentation for ServeMux explains how patterns are matched.
   932	func HandleFunc(pattern string, handler func(ResponseWriter, *Request)) {
   933		DefaultServeMux.HandleFunc(pattern, handler)
   934	}
   935	
   936	// Serve accepts incoming HTTP connections on the listener l,
   937	// creating a new service thread for each.  The service threads
   938	// read requests and then call handler to reply to them.
   939	// Handler is typically nil, in which case the DefaultServeMux is used.
   940	func Serve(l net.Listener, handler Handler) os.Error {
   941		srv := &Server{Handler: handler}
   942		return srv.Serve(l)
   943	}
   944	
   945	// A Server defines parameters for running an HTTP server.
   946	type Server struct {
   947		Addr           string  // TCP address to listen on, ":http" if empty
   948		Handler        Handler // handler to invoke, http.DefaultServeMux if nil
   949		ReadTimeout    int64   // the net.Conn.SetReadTimeout value for new connections
   950		WriteTimeout   int64   // the net.Conn.SetWriteTimeout value for new connections
   951		MaxHeaderBytes int     // maximum size of request headers, DefaultMaxHeaderBytes if 0
   952	}
   953	
   954	// ListenAndServe listens on the TCP network address srv.Addr and then
   955	// calls Serve to handle requests on incoming connections.  If
   956	// srv.Addr is blank, ":http" is used.
   957	func (srv *Server) ListenAndServe() os.Error {
   958		addr := srv.Addr
   959		if addr == "" {
   960			addr = ":http"
   961		}
   962		l, e := net.Listen("tcp", addr)
   963		if e != nil {
   964			return e
   965		}
   966		return srv.Serve(l)
   967	}
   968	
   969	// Serve accepts incoming connections on the Listener l, creating a
   970	// new service thread for each.  The service threads read requests and
   971	// then call srv.Handler to reply to them.
   972	func (srv *Server) Serve(l net.Listener) os.Error {
   973		defer l.Close()
   974		for {
   975			rw, e := l.Accept()
   976			if e != nil {
   977				if ne, ok := e.(net.Error); ok && ne.Temporary() {
   978					log.Printf("http: Accept error: %v", e)
   979					continue
   980				}
   981				return e
   982			}
   983			if srv.ReadTimeout != 0 {
   984				rw.SetReadTimeout(srv.ReadTimeout)
   985			}
   986			if srv.WriteTimeout != 0 {
   987				rw.SetWriteTimeout(srv.WriteTimeout)
   988			}
   989			c, err := srv.newConn(rw)
   990			if err != nil {
   991				continue
   992			}
   993			go c.serve()
   994		}
   995		panic("not reached")
   996	}
   997	
   998	// ListenAndServe listens on the TCP network address addr
   999	// and then calls Serve with handler to handle requests
  1000	// on incoming connections.  Handler is typically nil,
  1001	// in which case the DefaultServeMux is used.
  1002	//
  1003	// A trivial example server is:
  1004	//
  1005	//	package main
  1006	//
  1007	//	import (
  1008	//		"http"
  1009	//		"io"
  1010	//		"log"
  1011	//	)
  1012	//
  1013	//	// hello world, the web server
  1014	//	func HelloServer(w http.ResponseWriter, req *http.Request) {
  1015	//		io.WriteString(w, "hello, world!\n")
  1016	//	}
  1017	//
  1018	//	func main() {
  1019	//		http.HandleFunc("/hello", HelloServer)
  1020	//		err := http.ListenAndServe(":12345", nil)
  1021	//		if err != nil {
  1022	//			log.Fatal("ListenAndServe: ", err.String())
  1023	//		}
  1024	//	}
  1025	func ListenAndServe(addr string, handler Handler) os.Error {
  1026		server := &Server{Addr: addr, Handler: handler}
  1027		return server.ListenAndServe()
  1028	}
  1029	
  1030	// ListenAndServeTLS acts identically to ListenAndServe, except that it
  1031	// expects HTTPS connections. Additionally, files containing a certificate and
  1032	// matching private key for the server must be provided. If the certificate
  1033	// is signed by a certificate authority, the certFile should be the concatenation
  1034	// of the server's certificate followed by the CA's certificate.
  1035	//
  1036	// A trivial example server is:
  1037	//
  1038	//	import (
  1039	//		"http"
  1040	//		"log"
  1041	//	)
  1042	//
  1043	//	func handler(w http.ResponseWriter, req *http.Request) {
  1044	//		w.Header().Set("Content-Type", "text/plain")
  1045	//		w.Write([]byte("This is an example server.\n"))
  1046	//	}
  1047	//
  1048	//	func main() {
  1049	//		http.HandleFunc("/", handler)
  1050	//		log.Printf("About to listen on 10443. Go to https://127.0.0.1:10443/")
  1051	//		err := http.ListenAndServeTLS(":10443", "cert.pem", "key.pem", nil)
  1052	//		if err != nil {
  1053	//			log.Fatal(err)
  1054	//		}
  1055	//	}
  1056	//
  1057	// One can use generate_cert.go in crypto/tls to generate cert.pem and key.pem.
  1058	func ListenAndServeTLS(addr string, certFile string, keyFile string, handler Handler) os.Error {
  1059		server := &Server{Addr: addr, Handler: handler}
  1060		return server.ListenAndServeTLS(certFile, keyFile)
  1061	}
  1062	
  1063	// ListenAndServeTLS listens on the TCP network address srv.Addr and
  1064	// then calls Serve to handle requests on incoming TLS connections.
  1065	//
  1066	// Filenames containing a certificate and matching private key for
  1067	// the server must be provided. If the certificate is signed by a
  1068	// certificate authority, the certFile should be the concatenation
  1069	// of the server's certificate followed by the CA's certificate.
  1070	//
  1071	// If srv.Addr is blank, ":https" is used.
  1072	func (s *Server) ListenAndServeTLS(certFile, keyFile string) os.Error {
  1073		addr := s.Addr
  1074		if addr == "" {
  1075			addr = ":https"
  1076		}
  1077		config := &tls.Config{
  1078			Rand:       rand.Reader,
  1079			Time:       time.Seconds,
  1080			NextProtos: []string{"http/1.1"},
  1081		}
  1082	
  1083		var err os.Error
  1084		config.Certificates = make([]tls.Certificate, 1)
  1085		config.Certificates[0], err = tls.LoadX509KeyPair(certFile, keyFile)
  1086		if err != nil {
  1087			return err
  1088		}
  1089	
  1090		conn, err := net.Listen("tcp", addr)
  1091		if err != nil {
  1092			return err
  1093		}
  1094	
  1095		tlsListener := tls.NewListener(conn, config)
  1096		return s.Serve(tlsListener)
  1097	}
  1098	
  1099	// TimeoutHandler returns a Handler that runs h with the given time limit.
  1100	//
  1101	// The new Handler calls h.ServeHTTP to handle each request, but if a
  1102	// call runs for more than ns nanoseconds, the handler responds with
  1103	// a 503 Service Unavailable error and the given message in its body.
  1104	// (If msg is empty, a suitable default message will be sent.)
  1105	// After such a timeout, writes by h to its ResponseWriter will return
  1106	// ErrHandlerTimeout.
  1107	func TimeoutHandler(h Handler, ns int64, msg string) Handler {
  1108		f := func() <-chan int64 {
  1109			return time.After(ns)
  1110		}
  1111		return &timeoutHandler{h, f, msg}
  1112	}
  1113	
  1114	// ErrHandlerTimeout is returned on ResponseWriter Write calls
  1115	// in handlers which have timed out.
  1116	var ErrHandlerTimeout = os.NewError("http: Handler timeout")
  1117	
  1118	type timeoutHandler struct {
  1119		handler Handler
  1120		timeout func() <-chan int64 // returns channel producing a timeout
  1121		body    string
  1122	}
  1123	
  1124	func (h *timeoutHandler) errorBody() string {
  1125		if h.body != "" {
  1126			return h.body
  1127		}
  1128		return "<html><head><title>Timeout</title></head><body><h1>Timeout</h1></body></html>"
  1129	}
  1130	
  1131	func (h *timeoutHandler) ServeHTTP(w ResponseWriter, r *Request) {
  1132		done := make(chan bool)
  1133		tw := &timeoutWriter{w: w}
  1134		go func() {
  1135			h.handler.ServeHTTP(tw, r)
  1136			done <- true
  1137		}()
  1138		select {
  1139		case <-done:
  1140			return
  1141		case <-h.timeout():
  1142			tw.mu.Lock()
  1143			defer tw.mu.Unlock()
  1144			if !tw.wroteHeader {
  1145				tw.w.WriteHeader(StatusServiceUnavailable)
  1146				tw.w.Write([]byte(h.errorBody()))
  1147			}
  1148			tw.timedOut = true
  1149		}
  1150	}
  1151	
  1152	type timeoutWriter struct {
  1153		w ResponseWriter
  1154	
  1155		mu          sync.Mutex
  1156		timedOut    bool
  1157		wroteHeader bool
  1158	}
  1159	
  1160	func (tw *timeoutWriter) Header() Header {
  1161		return tw.w.Header()
  1162	}
  1163	
  1164	func (tw *timeoutWriter) Write(p []byte) (int, os.Error) {
  1165		tw.mu.Lock()
  1166		timedOut := tw.timedOut
  1167		tw.mu.Unlock()
  1168		if timedOut {
  1169			return 0, ErrHandlerTimeout
  1170		}
  1171		return tw.w.Write(p)
  1172	}
  1173	
  1174	func (tw *timeoutWriter) WriteHeader(code int) {
  1175		tw.mu.Lock()
  1176		if tw.timedOut || tw.wroteHeader {
  1177			tw.mu.Unlock()
  1178			return
  1179		}
  1180		tw.wroteHeader = true
  1181		tw.mu.Unlock()
  1182		tw.w.WriteHeader(code)
  1183	}

release.r60.3. Except as noted, this content is licensed under a Creative Commons Attribution 3.0 License.