server: Document use of context in ListenAndServe

Shutdown and Close will hang if there are no active listeners or
connections. Try to close the done channel to avoid that.

certificate/create.go

@@ -1,4 +1,4 @@
-// Package certificate provides utility functions for TLS certificates.
+// Package certificate provides functions for creating and storing TLS certificates.
 package certificate
 
 import (

certificate/store.go

@@ -12,14 +12,19 @@ import (
 	"time"
 )
 
-// Store represents a certificate store.
+// A Store represents a certificate store.
+// It generates certificates as needed and automatically rotates expired certificates.
 // The zero value for Store is an empty store ready to use.
 //
+// Certificate scopes must be registered with Register before calling Get or Load.
+// This prevents the Store from creating or loading unnecessary certificates.
+//
 // Store is safe for concurrent use by multiple goroutines.
 type Store struct {
 	// CreateCertificate, if not nil, is called to create a new certificate
 	// to replace a missing or expired certificate. If CreateCertificate
 	// is nil, a certificate with a duration of 1 year will be created.
+	// The provided scope is suitable for use in a certificate's DNSNames.
 	CreateCertificate func(scope string) (tls.Certificate, error)
 
 	certs map[string]tls.Certificate
@@ -27,8 +32,9 @@ type Store struct {
 	mu    sync.RWMutex
 }
 
-// Register registers the provided scope in the certificate store.
+// Register registers the provided scope with the certificate store.
-// The certificate will be created upon calling GetCertificate.
+// The scope can either be a hostname or a wildcard pattern (e.g. "*.example.com").
+// To accept all hostnames, use the special pattern "*".
 func (s *Store) Register(scope string) {
 	s.mu.Lock()
 	defer s.mu.Unlock()
@@ -38,7 +44,8 @@ func (s *Store) Register(scope string) {
 	s.certs[scope] = tls.Certificate{}
 }
 
-// Add adds a certificate for the given scope to the certificate store.
+// Add adds a certificate with the given scope to the certificate store.
+// If a certificate for the given scope already exists, Add will overwrite it.
 func (s *Store) Add(scope string, cert tls.Certificate) error {
 	s.mu.Lock()
 	defer s.mu.Unlock()
@@ -56,10 +63,8 @@ func (s *Store) Add(scope string, cert tls.Certificate) error {
 	}
 
 	if s.path != "" {
-		// Escape slash character
+		certPath := filepath.Join(s.path, scope+".crt")
-		path := strings.ReplaceAll(scope, "/", ":")
+		keyPath := filepath.Join(s.path, scope+".key")
-		certPath := filepath.Join(s.path, path+".crt")
-		keyPath := filepath.Join(s.path, path+".key")
 		if err := Write(cert, certPath, keyPath); err != nil {
 			return err
 		}
@@ -69,29 +74,26 @@ func (s *Store) Add(scope string, cert tls.Certificate) error {
 	return nil
 }
 
-// Lookup returns the certificate for the provided scope.
+// Get retrieves a certificate for the given hostname.
-func (s *Store) Lookup(scope string) (tls.Certificate, bool) {
+// If no matching scope has been registered, Get returns an error.
+// Get generates new certificates as needed and rotates expired certificates.
+//
+// Get is suitable for use in a gemini.Server's GetCertificate field.
+func (s *Store) Get(hostname string) (*tls.Certificate, error) {
 	s.mu.RLock()
 	defer s.mu.RUnlock()
-	cert, ok := s.certs[scope]
+	cert, ok := s.certs[hostname]
-	return cert, ok
-}
-
-// GetCertificate retrieves the certificate for the given scope.
-// If the retrieved certificate is expired or the scope is registered but
-// has no certificate, it calls CreateCertificate to create a new certificate.
-func (s *Store) GetCertificate(scope string) (*tls.Certificate, error) {
-	cert, ok := s.Lookup(scope)
 	if !ok {
 		// Try wildcard
-		wildcard := strings.SplitN(scope, ".", 2)
+		wildcard := strings.SplitN(hostname, ".", 2)
 		if len(wildcard) == 2 {
-			cert, ok = s.Lookup("*." + wildcard[1])
+			hostname = "*." + wildcard[1]
+			cert, ok = s.certs[hostname]
 		}
 	}
 	if !ok {
 		// Try "*"
-		_, ok = s.Lookup("*")
+		cert, ok = s.certs["*"]
 	}
 	if !ok {
 		return nil, errors.New("unrecognized scope")
@@ -100,12 +102,12 @@ func (s *Store) GetCertificate(scope string) (*tls.Certificate, error) {
 	// If the certificate is empty or expired, generate a new one.
 	if cert.Leaf == nil || cert.Leaf.NotAfter.Before(time.Now()) {
 		var err error
-		cert, err = s.createCertificate(scope)
+		cert, err = s.createCertificate(hostname)
 		if err != nil {
 			return nil, err
 		}
-		if err := s.Add(scope, cert); err != nil {
+		if err := s.Add(hostname, cert); err != nil {
-			return nil, fmt.Errorf("failed to add certificate for %s: %w", scope, err)
+			return nil, fmt.Errorf("failed to add certificate for %s: %w", hostname, err)
 		}
 	}
 
@@ -127,24 +129,26 @@ func (s *Store) createCertificate(scope string) (tls.Certificate, error) {
 
 // Load loads certificates from the provided path.
 // New certificates will be written to this path.
-//
 // The path should lead to a directory containing certificates
 // and private keys named "scope.crt" and "scope.key" respectively,
 // where "scope" is the scope of the certificate.
+// Certificates with scopes that have not been registered will be ignored.
 func (s *Store) Load(path string) error {
 	matches, err := filepath.Glob(filepath.Join(path, "*.crt"))
 	if err != nil {
 		return err
 	}
 	for _, crtPath := range matches {
+		scope := strings.TrimSuffix(filepath.Base(crtPath), ".crt")
+		if _, ok := s.certs[scope]; !ok {
+			continue
+		}
+
 		keyPath := strings.TrimSuffix(crtPath, ".crt") + ".key"
 		cert, err := tls.LoadX509KeyPair(crtPath, keyPath)
 		if err != nil {
 			continue
 		}
-		scope := strings.TrimSuffix(filepath.Base(crtPath), ".crt")
-		// Unescape slash character
-		scope = strings.ReplaceAll(scope, ":", "/")
 		s.Add(scope, cert)
 	}
 	s.SetPath(path)

client.go

@@ -4,10 +4,12 @@ import (
 	"context"
 	"crypto/tls"
 	"crypto/x509"
-	"errors"
 	"net"
 	"net/url"
 	"time"
+	"unicode/utf8"
+
+	"golang.org/x/net/idna"
 )
 
 // A Client is a Gemini client. Its zero value is a usable client.
@@ -21,20 +23,14 @@ type Client struct {
 	// See the tofu submodule for an implementation of trust on first use.
 	TrustCertificate func(hostname string, cert *x509.Certificate) error
 
-	// Timeout specifies a time limit for requests made by this
-	// Client. The timeout includes connection time and reading
-	// the response body. The timer remains running after
-	// Get or Do return and will interrupt reading of the Response.Body.
-	//
-	// A Timeout of zero means no timeout.
-	Timeout time.Duration
-
 	// DialContext specifies the dial function for creating TCP connections.
 	// If DialContext is nil, the client dials using package net.
 	DialContext func(ctx context.Context, network, addr string) (net.Conn, error)
 }
 
 // Get sends a Gemini request for the given URL.
+// If the provided context is canceled or times out, the request
+// will be aborted and the context's error will be returned.
 //
 // An error is returned if there was a Gemini protocol error.
 // A non-2x status code doesn't cause an error.
@@ -51,8 +47,9 @@ func (c *Client) Get(ctx context.Context, url string) (*Response, error) {
 	return c.Do(ctx, req)
 }
 
-// Do sends a Gemini request and returns a Gemini response, following
+// Do sends a Gemini request and returns a Gemini response.
-// policy as configured on the client.
+// If the provided context is canceled or times out, the request
+// will be aborted and the context's error will be returned.
 //
 // An error is returned if there was a Gemini protocol error.
 // A non-2x status code doesn't cause an error.
@@ -75,15 +72,16 @@ func (c *Client) Do(ctx context.Context, req *Request) (*Response, error) {
 	if host != punycode {
 		host = punycode
 
-		// Make a copy of the request
+		// Copy the URL and update the host
-		r2 := new(Request)
+		u := new(url.URL)
-		*r2 = *req
+		*u = *req.URL
-		r2.URL = new(url.URL)
+		u.Host = net.JoinHostPort(host, port)
-		*r2.URL = *req.URL
-		req = r2
 
-		// Set the host
+		// Use the new URL in the request so that the server gets
-		req.URL.Host = net.JoinHostPort(host, port)
+		// the punycoded hostname
+		req = &Request{
+			URL: u,
+		}
 	}
 
 	// Use request host if provided
@@ -98,17 +96,11 @@ func (c *Client) Do(ctx context.Context, req *Request) (*Response, error) {
 	addr := net.JoinHostPort(host, port)
 
 	// Connect to the host
-	start := time.Now()
 	conn, err := c.dialContext(ctx, "tcp", addr)
 	if err != nil {
 		return nil, err
 	}
 
-	// Set the connection deadline
-	if c.Timeout != 0 {
-		conn.SetDeadline(start.Add(c.Timeout))
-	}
-
 	// Setup TLS
 	conn = tls.Client(conn, &tls.Config{
 		InsecureSkipVerify: true,
@@ -170,9 +162,7 @@ func (c *Client) dialContext(ctx context.Context, network, addr string) (net.Con
 	if c.DialContext != nil {
 		return c.DialContext(ctx, network, addr)
 	}
-	return (&net.Dialer{
+	return (&net.Dialer{}).DialContext(ctx, network, addr)
-		Timeout: c.Timeout,
-	}).DialContext(ctx, network, addr)
 }
 
 func (c *Client) verifyConnection(cs tls.ConnectionState, hostname string) error {
@@ -183,7 +173,7 @@ func (c *Client) verifyConnection(cs tls.ConnectionState, hostname string) error
 	}
 	// Check expiration date
 	if !time.Now().Before(cert.NotAfter) {
-		return errors.New("gemini: certificate expired")
+		return ErrCertificateExpired
 	}
 	// See if the client trusts the certificate
 	if c.TrustCertificate != nil {
@@ -202,3 +192,23 @@ func splitHostPort(hostport string) (host, port string) {
 	}
 	return
 }
+
+func isASCII(s string) bool {
+	for i := 0; i < len(s); i++ {
+		if s[i] >= utf8.RuneSelf {
+			return false
+		}
+	}
+	return true
+}
+
+// punycodeHostname returns the punycoded version of hostname.
+func punycodeHostname(hostname string) (string, error) {
+	if net.ParseIP(hostname) != nil {
+		return hostname, nil
+	}
+	if isASCII(hostname) {
+		return hostname, nil
+	}
+	return idna.Lookup.ToASCII(hostname)
+}

examples/auth.go

@@ -38,7 +38,7 @@ func main() {
 		Handler:        mux,
 		ReadTimeout:    30 * time.Second,
 		WriteTimeout:   1 * time.Minute,
-		GetCertificate: certificates.GetCertificate,
+		GetCertificate: certificates.Get,
 	}
 
 	if err := server.ListenAndServe(context.Background()); err != nil {

examples/server.go

@@ -8,6 +8,7 @@ import (
 	"context"
 	"log"
 	"os"
+	"os/signal"
 	"time"
 
 	"git.sr.ht/~adnano/go-gemini"
@@ -28,10 +29,29 @@ func main() {
 		Handler:        mux,
 		ReadTimeout:    30 * time.Second,
 		WriteTimeout:   1 * time.Minute,
-		GetCertificate: certificates.GetCertificate,
+		GetCertificate: certificates.Get,
 	}
 
-	if err := server.ListenAndServe(context.Background()); err != nil {
+	// Listen for interrupt signal
+	c := make(chan os.Signal, 1)
+	signal.Notify(c, os.Interrupt)
+
+	errch := make(chan error)
+	go func() {
+		ctx := context.Background()
+		errch <- server.ListenAndServe(ctx)
+	}()
+
+	select {
+	case err := <-errch:
 		log.Fatal(err)
+	case <-c:
+		// Shutdown the server
+		log.Println("Shutting down...")
+		ctx, _ := context.WithTimeout(context.Background(), 30*time.Second)
+		err := server.Shutdown(ctx)
+		if err != nil {
+			log.Fatal(err)
+		}
 	}
 }

examples/stream.go

@@ -8,7 +8,6 @@ import (
 	"context"
 	"fmt"
 	"log"
-	"sync"
 	"time"
 
 	"git.sr.ht/~adnano/go-gemini"
@@ -29,37 +28,17 @@ func main() {
 		Handler:        mux,
 		ReadTimeout:    30 * time.Second,
 		WriteTimeout:   1 * time.Minute,
-		GetCertificate: certificates.GetCertificate,
+		GetCertificate: certificates.Get,
 	}
 
-	var shutdownOnce sync.Once
+	ctx := context.Background()
-	var wg sync.WaitGroup
+	if err := server.ListenAndServe(ctx); err != nil {
-	wg.Add(1)
+		log.Fatal(err)
-	defer wg.Wait()
-	mux.HandleFunc("/shutdown", func(ctx context.Context, w gemini.ResponseWriter, r *gemini.Request) {
-		fmt.Fprintln(w, "Shutting down...")
-		if flusher, ok := w.(gemini.Flusher); ok {
-			flusher.Flush()
-		}
-		go shutdownOnce.Do(func() {
-			server.Shutdown(context.Background())
-			wg.Done()
-		})
-	})
-
-	if err := server.ListenAndServe(context.Background()); err != nil {
-		log.Println(err)
 	}
 }
 
 // stream writes an infinite stream to w.
 func stream(ctx context.Context, w gemini.ResponseWriter, r *gemini.Request) {
-	flusher, ok := w.(gemini.Flusher)
-	if !ok {
-		w.WriteHeader(gemini.StatusTemporaryFailure, "Internal error")
-		return
-	}
-
 	ch := make(chan string)
 	ctx, cancel := context.WithCancel(ctx)
 
@@ -84,7 +63,7 @@ func stream(ctx context.Context, w gemini.ResponseWriter, r *gemini.Request) {
 			break
 		}
 		fmt.Fprintln(w, s)
-		if err := flusher.Flush(); err != nil {
+		if err := w.Flush(); err != nil {
 			cancel()
 			return
 		}

fs.go

@@ -2,6 +2,7 @@ package gemini
 
 import (
 	"context"
+	"errors"
 	"fmt"
 	"io"
 	"io/fs"
@@ -33,7 +34,7 @@ type fileServer struct {
 }
 
 func (fs fileServer) ServeGemini(ctx context.Context, w ResponseWriter, r *Request) {
-	serveFile(ctx, w, r, fs, path.Clean(r.URL.Path), true)
+	serveFile(w, r, fs, path.Clean(r.URL.Path), true)
 }
 
 // ServeContent replies to the request using the content in the
@@ -42,15 +43,15 @@ func (fs fileServer) ServeGemini(ctx context.Context, w ResponseWriter, r *Reque
 //
 // ServeContent tries to deduce the type from name's file extension.
 // The name is otherwise unused; it is never sent in the response.
-func ServeContent(ctx context.Context, w ResponseWriter, r *Request, name string, content io.Reader) {
+func ServeContent(w ResponseWriter, r *Request, name string, content io.Reader) {
-	serveContent(ctx, w, name, content)
+	serveContent(w, name, content)
 }
 
-func serveContent(ctx context.Context, w ResponseWriter, name string, content io.Reader) {
+func serveContent(w ResponseWriter, name string, content io.Reader) {
 	// Detect mimetype from file extension
 	ext := path.Ext(name)
 	mimetype := mime.TypeByExtension(ext)
-	w.MediaType(mimetype)
+	w.SetMediaType(mimetype)
 	io.Copy(w, content)
 }
 
@@ -74,7 +75,7 @@ func serveContent(ctx context.Context, w ResponseWriter, name string, content io
 // Outside of those two special cases, ServeFile does not use r.URL.Path for
 // selecting the file or directory to serve; only the file or directory
 // provided in the name argument is used.
-func ServeFile(ctx context.Context, w ResponseWriter, r *Request, fsys fs.FS, name string) {
+func ServeFile(w ResponseWriter, r *Request, fsys fs.FS, name string) {
 	if containsDotDot(r.URL.Path) {
 		// Too many programs use r.URL.Path to construct the argument to
 		// serveFile. Reject the request under the assumption that happened
@@ -84,7 +85,7 @@ func ServeFile(ctx context.Context, w ResponseWriter, r *Request, fsys fs.FS, na
 		w.WriteHeader(StatusBadRequest, "invalid URL path")
 		return
 	}
-	serveFile(ctx, w, r, fsys, name, false)
+	serveFile(w, r, fsys, name, false)
 }
 
 func containsDotDot(v string) bool {
@@ -101,7 +102,7 @@ func containsDotDot(v string) bool {
 
 func isSlashRune(r rune) bool { return r == '/' || r == '\\' }
 
-func serveFile(ctx context.Context, w ResponseWriter, r *Request, fsys fs.FS, name string, redirect bool) {
+func serveFile(w ResponseWriter, r *Request, fsys fs.FS, name string, redirect bool) {
 	const indexPage = "/index.gmi"
 
 	// Redirect .../index.gmi to .../
@@ -118,14 +119,14 @@ func serveFile(ctx context.Context, w ResponseWriter, r *Request, fsys fs.FS, na
 
 	f, err := fsys.Open(name)
 	if err != nil {
-		w.WriteHeader(StatusNotFound, "Not found")
+		w.WriteHeader(toGeminiError(err))
 		return
 	}
 	defer f.Close()
 
 	stat, err := f.Stat()
 	if err != nil {
-		w.WriteHeader(StatusTemporaryFailure, "Temporary failure")
+		w.WriteHeader(toGeminiError(err))
 		return
 	}
 
@@ -173,7 +174,7 @@ func serveFile(ctx context.Context, w ResponseWriter, r *Request, fsys fs.FS, na
 		return
 	}
 
-	serveContent(ctx, w, name, f)
+	serveContent(w, name, f)
 }
 
 func dirList(w ResponseWriter, f fs.File) {
@@ -204,3 +205,13 @@ func dirList(w ResponseWriter, f fs.File) {
 		fmt.Fprintln(w, link.String())
 	}
 }
+
+func toGeminiError(err error) (status Status, meta string) {
+	if errors.Is(err, fs.ErrNotExist) {
+		return StatusNotFound, "Not found"
+	}
+	if errors.Is(err, fs.ErrPermission) {
+		return StatusNotFound, "Forbidden"
+	}
+	return StatusTemporaryFailure, "Internal server error"
+}

gemini.go

@@ -8,24 +8,15 @@ var crlf = []byte("\r\n")
 
 // Errors.
 var (
-	ErrInvalidURL      = errors.New("gemini: invalid URL")
 	ErrInvalidRequest  = errors.New("gemini: invalid request")
 	ErrInvalidResponse = errors.New("gemini: invalid response")
 
+	ErrCertificateExpired = errors.New("gemini: certificate expired")
+
 	// ErrBodyNotAllowed is returned by ResponseWriter.Write calls
 	// when the response status code does not permit a body.
 	ErrBodyNotAllowed = errors.New("gemini: response status code does not allow body")
 
-	// ErrServerClosed is returned by the Server's Serve and ListenAndServe
-	// methods after a call to Shutdown or Close.
-	ErrServerClosed = errors.New("gemini: server closed")
-
-	// ErrAbortHandler is a sentinel panic value to abort a handler.
-	// While any panic from ServeGemini aborts the response to the client,
-	// panicking with ErrAbortHandler also suppresses logging of a stack
-	// trace to the server's error log.
-	ErrAbortHandler = errors.New("gemini: abort Handler")
-
 	// ErrHandlerTimeout is returned on ResponseWriter Write calls
 	// in handlers which have timed out.
 	ErrHandlerTimeout = errors.New("gemini: Handler timeout")

handler.go

@@ -14,13 +14,6 @@ import (
 // of the ServeGemini call.
 //
 // Handlers should not modify the provided Request.
-//
-// If ServeGemini panics, the server (the caller of ServeGemini) assumes that
-// the effect of the panic was isolated to the active request. It recovers
-// the panic, logs a stack trace to the server error log, and closes the
-// network connection. To abort a handler so the client sees an interrupted
-// response but the server doesn't log an error, panic with the value
-// ErrAbortHandler.
 type Handler interface {
 	ServeGemini(context.Context, ResponseWriter, *Request)
 }
@@ -53,9 +46,7 @@ func (h *statusHandler) ServeGemini(ctx context.Context, w ResponseWriter, r *Re
 // NotFoundHandler returns a simple request handler that replies to each
 // request with a “51 Not found” reply.
 func NotFoundHandler() Handler {
-	return HandlerFunc(func(ctx context.Context, w ResponseWriter, r *Request) {
+	return StatusHandler(StatusNotFound, "Not found")
-		w.WriteHeader(StatusNotFound, "Not found")
-	})
 }
 
 // StripPrefix returns a handler that serves Gemini requests by removing the

mux.go

@@ -294,9 +294,6 @@ func appendSorted(es []muxEntry, e muxEntry) []muxEntry {
 }
 
 // HandleFunc registers the handler function for the given pattern.
-func (mux *ServeMux) HandleFunc(pattern string, handler func(context.Context, ResponseWriter, *Request)) {
+func (mux *ServeMux) HandleFunc(pattern string, handler HandlerFunc) {
-	if handler == nil {
+	mux.Handle(pattern, handler)
-		panic("gemini: nil handler")
-	}
-	mux.Handle(pattern, HandlerFunc(handler))
 }

punycode.go

@@ -1,28 +0,0 @@
-package gemini
-
-import (
-	"net"
-	"unicode/utf8"
-
-	"golang.org/x/net/idna"
-)
-
-func isASCII(s string) bool {
-	for i := 0; i < len(s); i++ {
-		if s[i] >= utf8.RuneSelf {
-			return false
-		}
-	}
-	return true
-}
-
-// punycodeHostname returns the punycoded version of hostname.
-func punycodeHostname(hostname string) (string, error) {
-	if net.ParseIP(hostname) != nil {
-		return hostname, nil
-	}
-	if isASCII(hostname) {
-		return hostname, nil
-	}
-	return idna.Lookup.ToASCII(hostname)
-}

response.go

@@ -160,18 +160,18 @@ func (r *Response) Write(w io.Writer) error {
 // A ResponseWriter may not be used after the Handler.ServeGemini method
 // has returned.
 type ResponseWriter interface {
-	// MediaType sets the media type that will be sent by Write for a
+	// SetMediaType sets the media type that will be sent by Write for a
 	// successful response. If no media type is set, a default of
 	// "text/gemini; charset=utf-8" will be used.
 	//
 	// Setting the media type after a call to Write or WriteHeader has
 	// no effect.
-	MediaType(string)
+	SetMediaType(string)
 
 	// Write writes the data to the connection as part of a Gemini response.
 	//
 	// If WriteHeader has not yet been called, Write calls WriteHeader with
-	// StatusSuccess and the media type set in MediaType before writing the data.
+	// StatusSuccess and the media type set in SetMediaType before writing the data.
 	// If no media type was set, Write uses a default media type of
 	// "text/gemini; charset=utf-8".
 	Write([]byte) (int, error)
@@ -181,21 +181,13 @@ type ResponseWriter interface {
 	//
 	// If WriteHeader is not called explicitly, the first call to Write
 	// will trigger an implicit call to WriteHeader with a successful
-	// status code and the media type set in MediaType.
+	// status code and the media type set in SetMediaType.
 	//
 	// The provided code must be a valid Gemini status code.
 	// The provided meta must not be longer than 1024 bytes.
 	// Only one header may be written.
 	WriteHeader(status Status, meta string)
-}
 
-// The Flusher interface is implemented by ResponseWriters that allow a
-// Gemini handler to flush buffered data to the client.
-//
-// The default Gemini ResponseWriter implementation supports Flusher,
-// but ResponseWriter wrappers may not. Handlers should always test
-// for this ability at runtime.
-type Flusher interface {
 	// Flush sends any buffered data to the client.
 	Flush() error
 }
@@ -218,7 +210,7 @@ func newResponseWriter(w io.Writer) *responseWriter {
 	}
 }
 
-func (w *responseWriter) MediaType(mediatype string) {
+func (w *responseWriter) SetMediaType(mediatype string) {
 	w.mediatype = mediatype
 }
 

server.go

@@ -6,9 +6,7 @@ import (
 	"errors"
 	"log"
 	"net"
-	"runtime"
 	"sync"
-	"sync/atomic"
 	"time"
 )
 
@@ -40,21 +38,34 @@ type Server struct {
 	//
 	// If GetCertificate is nil or returns nil, then no certificate
 	// will be used and the connection will be aborted.
+	//
+	// See the certificate submodule for a certificate store that creates
+	// and rotates certificates as needed.
 	GetCertificate func(hostname string) (*tls.Certificate, error)
 
 	// ErrorLog specifies an optional logger for errors accepting connections,
 	// unexpected behavior from handlers, and underlying file system errors.
 	// If nil, logging is done via the log package's standard logger.
-	ErrorLog *log.Logger
+	ErrorLog interface {
+		Printf(format string, v ...interface{})
+	}
 
 	listeners map[*net.Listener]context.CancelFunc
 	conns     map[*net.Conn]context.CancelFunc
+	closed    bool // true if Closed or Shutdown called
+	shutdown  bool // true if Shutdown called
 	doneChan  chan struct{}
-	closed    int32
 	mu        sync.Mutex
 }
 
-// done returns a channel that's closed when the server has finished closing.
+func (srv *Server) isClosed() bool {
+	srv.mu.Lock()
+	defer srv.mu.Unlock()
+	return srv.closed
+}
+
+// done returns a channel that's closed when the server is closed and
+// all listeners and connections are closed.
 func (srv *Server) done() chan struct{} {
 	srv.mu.Lock()
 	defer srv.mu.Unlock()
@@ -68,16 +79,24 @@ func (srv *Server) doneLocked() chan struct{} {
 	return srv.doneChan
 }
 
-// tryFinishShutdown closes srv.done() if there are no active listeners or requests.
+// tryCloseDone closes srv.done() if the server is closed and
-func (srv *Server) tryFinishShutdown() {
+// there are no active listeners or connections.
+func (srv *Server) tryCloseDone() {
 	srv.mu.Lock()
 	defer srv.mu.Unlock()
+	srv.tryCloseDoneLocked()
+}
+
+func (srv *Server) tryCloseDoneLocked() {
+	if !srv.closed {
+		return
+	}
 	if len(srv.listeners) == 0 && len(srv.conns) == 0 {
-		done := srv.doneLocked()
+		ch := srv.doneLocked()
 		select {
-		case <-done:
+		case <-ch:
 		default:
-			close(done)
+			close(ch)
 		}
 	}
 }
@@ -85,17 +104,23 @@ func (srv *Server) tryFinishShutdown() {
 // Close immediately closes all active net.Listeners and connections.
 // For a graceful shutdown, use Shutdown.
 func (srv *Server) Close() error {
-	if !atomic.CompareAndSwapInt32(&srv.closed, 0, 1) {
-		return ErrServerClosed
-	}
-
-	// Close active listeners and connections.
 	srv.mu.Lock()
-	for _, cancel := range srv.listeners {
+	{
-		cancel()
+		if srv.closed {
-	}
+			srv.mu.Unlock()
-	for _, cancel := range srv.conns {
+			return nil
-		cancel()
+		}
+		srv.closed = true
+
+		srv.tryCloseDoneLocked()
+
+		// Close all active connections and listeners.
+		for _, cancel := range srv.listeners {
+			cancel()
+		}
+		for _, cancel := range srv.conns {
+			cancel()
+		}
 	}
 	srv.mu.Unlock()
 
@@ -106,27 +131,33 @@ func (srv *Server) Close() error {
 }
 
 // Shutdown gracefully shuts down the server without interrupting any
-// active connections. Shutdown works by first closing all open
+// active connections. Shutdown works by first closing all open listeners
-// listeners and then waiting indefinitely for connections
+// and then waiting indefinitely for connections to close.
-// to close and then shut down.
 // If the provided context expires before the shutdown is complete,
 // Shutdown returns the context's error.
 //
-// When Shutdown is called, Serve and ListenAndServer immediately
+// When Shutdown is called, Serve and ListenAndServe immediately
-// return ErrServerClosed. Make sure the program doesn't exit and
+// return an error. Make sure the program doesn't exit and waits instead for
-// waits instead for Shutdown to return.
+// Shutdown to return.
 //
 // Once Shutdown has been called on a server, it may not be reused;
-// future calls to methods such as Serve will return ErrServerClosed.
+// future calls to methods such as Serve will return an error.
 func (srv *Server) Shutdown(ctx context.Context) error {
-	if !atomic.CompareAndSwapInt32(&srv.closed, 0, 1) {
-		return ErrServerClosed
-	}
-
-	// Close active listeners.
 	srv.mu.Lock()
-	for _, cancel := range srv.listeners {
+	{
-		cancel()
+		if srv.closed {
+			srv.mu.Unlock()
+			return nil
+		}
+		srv.closed = true
+		srv.shutdown = true
+
+		srv.tryCloseDoneLocked()
+
+		// Close all active listeners.
+		for _, cancel := range srv.listeners {
+			cancel()
+		}
 	}
 	srv.mu.Unlock()
 
@@ -141,15 +172,16 @@ func (srv *Server) Shutdown(ctx context.Context) error {
 
 // ListenAndServe listens for requests at the server's configured address.
 // ListenAndServe listens on the TCP network address srv.Addr and then calls
-// Serve to handle requests on incoming connections.
+// Serve to handle requests on incoming connections. If the provided
+// context expires, ListenAndServe closes l and returns the context's error.
 //
 // If srv.Addr is blank, ":1965" is used.
 //
-// ListenAndServe always returns a non-nil error. After Shutdown or Close, the
+// ListenAndServe always returns a non-nil error.
-// returned error is ErrServerClosed.
+// After Shutdown or Closed, the returned error is context.Canceled.
 func (srv *Server) ListenAndServe(ctx context.Context) error {
-	if atomic.LoadInt32(&srv.closed) == 1 {
+	if srv.isClosed() {
-		return ErrServerClosed
+		return context.Canceled
 	}
 
 	addr := srv.Addr
@@ -177,13 +209,17 @@ func (srv *Server) getCertificate(h *tls.ClientHelloInfo) (*tls.Certificate, err
 	return srv.GetCertificate(h.ServerName)
 }
 
-func (srv *Server) trackListener(l *net.Listener, cancel context.CancelFunc) {
+func (srv *Server) trackListener(l *net.Listener, cancel context.CancelFunc) bool {
 	srv.mu.Lock()
 	defer srv.mu.Unlock()
+	if srv.closed {
+		return false
+	}
 	if srv.listeners == nil {
 		srv.listeners = make(map[*net.Listener]context.CancelFunc)
 	}
 	srv.listeners[l] = cancel
+	return true
 }
 
 func (srv *Server) deleteListener(l *net.Listener) {
@@ -193,23 +229,22 @@ func (srv *Server) deleteListener(l *net.Listener) {
 }
 
 // Serve accepts incoming connections on the Listener l, creating a new
-// service goroutine for each. The service goroutines read requests and
+// service goroutine for each. The service goroutines reads the request and
-// then calls the appropriate Handler to reply to them.
+// then calls the appropriate Handler to reply to them. If the provided
+// context expires, Serve closes l and returns the context's error.
 //
-// Serve always returns a non-nil error and closes l. After Shutdown or Close,
+// Serve always closes l and returns a non-nil error.
-// the returned error is ErrServerClosed.
+// After Shutdown or Close, the returned error is context.Canceled.
 func (srv *Server) Serve(ctx context.Context, l net.Listener) error {
 	defer l.Close()
 
-	if atomic.LoadInt32(&srv.closed) == 1 {
-		return ErrServerClosed
-	}
-
 	lnctx, cancel := context.WithCancel(ctx)
 	defer cancel()
 
-	srv.trackListener(&l, cancel)
+	if !srv.trackListener(&l, cancel) {
-	defer srv.tryFinishShutdown()
+		return context.Canceled
+	}
+	defer srv.tryCloseDone()
 	defer srv.deleteListener(&l)
 
 	errch := make(chan error, 1)
@@ -219,9 +254,6 @@ func (srv *Server) Serve(ctx context.Context, l net.Listener) error {
 
 	select {
 	case <-lnctx.Done():
-		if atomic.LoadInt32(&srv.closed) == 1 {
-			return ErrServerClosed
-		}
 		return lnctx.Err()
 	case err := <-errch:
 		return err
@@ -229,21 +261,10 @@ func (srv *Server) Serve(ctx context.Context, l net.Listener) error {
 }
 
 func (srv *Server) serve(ctx context.Context, l net.Listener) error {
-	// how long to sleep on accept failure
+	var tempDelay time.Duration // how long to sleep on accept failure
-	var tempDelay time.Duration
-
 	for {
 		rw, err := l.Accept()
 		if err != nil {
-			select {
-			case <-ctx.Done():
-				if atomic.LoadInt32(&srv.closed) == 1 {
-					return ErrServerClosed
-				}
-				return ctx.Err()
-			default:
-			}
-
 			// If this is a temporary error, sleep
 			if ne, ok := err.(net.Error); ok && ne.Temporary() {
 				if tempDelay == 0 {
@@ -258,22 +279,24 @@ func (srv *Server) serve(ctx context.Context, l net.Listener) error {
 				time.Sleep(tempDelay)
 				continue
 			}
-
 			return err
 		}
-
 		tempDelay = 0
-		go srv.serveConn(ctx, rw)
+		go srv.ServeConn(ctx, rw)
 	}
 }
 
-func (srv *Server) trackConn(conn *net.Conn, cancel context.CancelFunc) {
+func (srv *Server) trackConn(conn *net.Conn, cancel context.CancelFunc) bool {
 	srv.mu.Lock()
 	defer srv.mu.Unlock()
+	if srv.closed && !srv.shutdown {
+		return false
+	}
 	if srv.conns == nil {
 		srv.conns = make(map[*net.Conn]context.CancelFunc)
 	}
 	srv.conns[conn] = cancel
+	return true
 }
 
 func (srv *Server) deleteConn(conn *net.Conn) {
@@ -282,31 +305,24 @@ func (srv *Server) deleteConn(conn *net.Conn) {
 	delete(srv.conns, conn)
 }
 
-// serveConn serves a Gemini response over the provided connection.
+// ServeConn serves a Gemini response over the provided connection.
 // It closes the connection when the response has been completed.
-func (srv *Server) serveConn(ctx context.Context, conn net.Conn) {
+// If the provided context expires before the response has completed,
+// ServeConn closes the connection and returns the context's error.
+//
+// Note that ServeConn can be used during a Shutdown.
+func (srv *Server) ServeConn(ctx context.Context, conn net.Conn) error {
 	defer conn.Close()
 
-	if atomic.LoadInt32(&srv.closed) == 1 {
-		return
-	}
-
 	ctx, cancel := context.WithCancel(ctx)
 	defer cancel()
 
-	srv.trackConn(&conn, cancel)
+	if !srv.trackConn(&conn, cancel) {
-	defer srv.tryFinishShutdown()
+		return context.Canceled
+	}
+	defer srv.tryCloseDone()
 	defer srv.deleteConn(&conn)
 
-	defer func() {
-		if err := recover(); err != nil && err != ErrAbortHandler {
-			const size = 64 << 10
-			buf := make([]byte, size)
-			buf = buf[:runtime.Stack(buf, false)]
-			srv.logf("gemini: panic serving %v: %v\n%s", conn.RemoteAddr(), err, buf)
-		}
-	}()
-
 	if d := srv.ReadTimeout; d != 0 {
 		conn.SetReadDeadline(time.Now().Add(d))
 	}
@@ -314,26 +330,26 @@ func (srv *Server) serveConn(ctx context.Context, conn net.Conn) {
 		conn.SetWriteDeadline(time.Now().Add(d))
 	}
 
-	done := make(chan struct{})
+	errch := make(chan error, 1)
 	go func() {
-		srv.respond(ctx, conn)
+		errch <- srv.serveConn(ctx, conn)
-		close(done)
 	}()
 
 	select {
 	case <-ctx.Done():
-	case <-done:
+		return ctx.Err()
+	case err := <-errch:
+		return err
 	}
 }
 
-func (srv *Server) respond(ctx context.Context, conn net.Conn) {
+func (srv *Server) serveConn(ctx context.Context, conn net.Conn) error {
 	w := newResponseWriter(conn)
-	defer w.Flush()
 
 	req, err := ReadRequest(conn)
 	if err != nil {
 		w.WriteHeader(StatusBadRequest, "Bad request")
-		return
+		return w.Flush()
 	}
 
 	// Store the TLS connection state
@@ -349,10 +365,11 @@ func (srv *Server) respond(ctx context.Context, conn net.Conn) {
 	h := srv.Handler
 	if h == nil {
 		w.WriteHeader(StatusNotFound, "Not found")
-		return
+		return w.Flush()
 	}
 
 	h.ServeGemini(ctx, w, req)
+	return w.Flush()
 }
 
 func (srv *Server) logf(format string, args ...interface{}) {

text.go

@@ -9,38 +9,39 @@ import (
 
 // Line represents a line of a Gemini text response.
 type Line interface {
+	// String formats the line for use in a Gemini text response.
 	String() string
 	line() // private function to prevent other packages from implementing Line
 }
 
-// A link line.
+// LineLink is a link line.
 type LineLink struct {
 	URL  string
 	Name string
 }
 
-// A preformatting toggle line.
+// LinePreformattingToggle is a preformatting toggle line.
 type LinePreformattingToggle string
 
-// A preformatted text line.
+// LinePreformattedText is a preformatted text line.
 type LinePreformattedText string
 
-// A first-level heading line.
+// LineHeading1 is a first-level heading line.
 type LineHeading1 string
 
-// A second-level heading line.
+// LineHeading2 is a second-level heading line.
 type LineHeading2 string
 
-// A third-level heading line.
+// LineHeading3 is a third-level heading line.
 type LineHeading3 string
 
-// An unordered list item line.
+// LineListItem is an unordered list item line.
 type LineListItem string
 
-// A quote line.
+// LineQuote is a quote line.
 type LineQuote string
 
-// A text line.
+// LineText is a text line.
 type LineText string
 
 func (l LineLink) String() string {

timeout.go

@@ -13,8 +13,6 @@ import (
 // if a call runs for longer than its time limit, the handler responds with a
 // 40 Temporary Failure error. After such a timeout, writes by h to its
 // ResponseWriter will return ErrHandlerTimeout.
-//
-// TimeoutHandler does not support the Hijacker or Flusher interfaces.
 func TimeoutHandler(h Handler, dt time.Duration) Handler {
 	return &timeoutHandler{
 		h:  h,
@@ -73,7 +71,7 @@ type timeoutWriter struct {
 	timedOut    bool
 }
 
-func (w *timeoutWriter) MediaType(mediatype string) {
+func (w *timeoutWriter) SetMediaType(mediatype string) {
 	w.mu.Lock()
 	defer w.mu.Unlock()
 	w.mediatype = mediatype
@@ -108,3 +106,7 @@ func (w *timeoutWriter) writeHeaderLocked(status Status, meta string) {
 	w.meta = meta
 	w.wroteHeader = true
 }
+
+func (w *timeoutWriter) Flush() error {
+	return nil
+}

tofu/tofu.go

@@ -217,7 +217,8 @@ type PersistentHosts struct {
 	writer *HostWriter
 }
 
-// NewPersistentHosts returns a new persistent set of known hosts.
+// NewPersistentHosts returns a new persistent set of known hosts that stores
+// known hosts in hosts and writes new hosts to writer.
 func NewPersistentHosts(hosts *KnownHosts, writer *HostWriter) *PersistentHosts {
 	return &PersistentHosts{
 		hosts,