handler

README

Handler

A collection of HTTP handlers for use with the Go net/http package.

Use

(Exposition forthcoming)

Motivation

(Exposition forthcoming)

Contributing

Please see the contributing guidelines.

License

Handler is released under the BSD license. See the LICENSE file for more detail.

Documentation

Overview

Package handler provides a collection of HTTP handlers for use with the net/http package.

Index

• func ExtractSession(r *http.Request) (s *sessions.Session, ok bool)
• func ExtractSessionNamed(name string, r *http.Request) (s *sessions.Session, ok bool)
• func MustExtractSession(r *http.Request) *sessions.Session
• func MustExtractSessionNamed(name string, r *http.Request) *sessions.Session
• func WithSession(name string, s SessionSource, h http.Handler, ...) http.Handler
• func WithSessionsNamed(names []string, s SessionSource, h http.Handler, ...) http.Handler
• type SessionSource

Examples

• WithSession
• WithSessionsNamed

Functions

func ExtractSession

func ExtractSession(r *http.Request) (s *sessions.Session, ok bool)

ExtractSession retrieves the singular session most recently bound to this request via WithSession, together with a boolean indicating whether such a session is available.

func ExtractSessionNamed

func ExtractSessionNamed(name string, r *http.Request) (s *sessions.Session, ok bool)

ExtractSessionNamed retrieves the session most recently bound to this request with the given name via WithSessionsNamed, together with a boolean indicating whether such a session is available.

func MustExtractSession

func MustExtractSession(r *http.Request) *sessions.Session

MustExtractSession retrieves the singular session most recently bound to this request via WithSession, or panics if no such session is available.

func MustExtractSessionNamed

func MustExtractSessionNamed(name string, r *http.Request) *sessions.Session

MustExtractSessionNamed retrieves the session most recently bound to this request with the given name via WithSessionsNamed, or panics if no such session is available.

func WithSession

func WithSession(name string, s SessionSource, h http.Handler, onError func(w http.ResponseWriter, r *http.Request, err error)) http.Handler

WithSession returns an HTTP handler that binds a session with the given name to each submitted request, delegating further request processing to the supplied HTTP handler, which can then retrieve this bound session with either ExtractSession or MustExtractSession. It panics if either the supplied SessionSource or handler is nil. If the SessionSource yields an error instead of a session, it delegates further request processing to the onError handler. If no such onError handler is supplied and an error arises acquiring a session, it will respond with HTTP status code 500 with no body.

Note that even though this bound session has a name, supplied for consumption by the SessionSource, WithSession binds at most one session to a given request (as an anonymous singleton, shadowing any prior sessions bound similarly), making storage and later retrieval of the session more efficient than the multiple sessions that the similar WithSessionsNamed binds. To bind multiple sessions with different names to a given request, use WithSessionsNamed instead.

Example

package main

import (
	"fmt"
	"net/http"

	"github.com/seh/handler"
)

func consumeSession(w http.ResponseWriter, r *http.Request) {
	session := handler.MustExtractSession(r)
	converseIn(w, "text/plain")
	fmt.Fprintf(w, "Hello, session %q!\n", session.Name())
}

func main() {
	onError := func(w http.ResponseWriter, r *http.Request, err error) {
		w.WriteHeader(http.StatusInternalServerError)
		converseIn(w, "text/plain")
		fmt.Fprintf(w, "Failed to allocate a session for this request: %v\n", err)
	}

	wrapped := handler.WithSession("s", makeStore(), http.HandlerFunc(consumeSession), onError)
	serveRequestAndPrintResponseBody(wrapped)
}

Output:

Hello, session "s"!

func WithSessionsNamed

func WithSessionsNamed(names []string, s SessionSource, h http.Handler, onError func(w http.ResponseWriter, r *http.Request, name string, err error)) http.Handler

WithSessionsNamed returns an HTTP handler that binds any number of sessions with the given set of names to each submitted request, delegating further request processing to the supplied HTTP handler, which can then retrieve these bound sessions with either ExtractSessionNamed or MustExtractSessionNamed. It panics if either the supplied SessionSource or handler is nil. If the SessionSource yields an error instead of a session, it delegates further request processing to the onError handler. If no such onError handler is supplied and an error arises acquiring a session, it will respond with HTTP status code 500 with no body.

It reduces the sequence of names supplied to a set, with no duplicate entries, but it does not mutate the supplied slice in place. If no names are supplied, it returns the supplied HTTP handler.

To bind only a single session to a given request, consider using WithSession instead.

Example

package main

import (
	"fmt"
	"net/http"

	"github.com/seh/handler"
)

var sessionNames = []string{"s1", "s2"}

func consumeSessions(w http.ResponseWriter, r *http.Request) {
	converseIn(w, "text/plain")
	for _, name := range sessionNames {
		session := handler.MustExtractSessionNamed(name, r)
		fmt.Fprintf(w, "Session registered with name %q is named %q.\n", name, session.Name())
	}
}

func main() {
	onError := func(w http.ResponseWriter, r *http.Request, name string, err error) {
		w.WriteHeader(http.StatusInternalServerError)
		converseIn(w, "text/plain")
		fmt.Fprintf(w, "Failed to allocate a session named %q for this request: %v\n", name, err)
	}

	wrapped := handler.WithSessionsNamed(sessionNames, makeStore(), http.HandlerFunc(consumeSessions), onError)
	serveRequestAndPrintResponseBody(wrapped)
}

Output:

Session registered with name "s1" is named "s1".
Session registered with name "s2" is named "s2".

Types

type SessionSource

type SessionSource interface {
	// New creates a new session, or returns an error if unable to do so successfully.
	New(r *http.Request, name string) (*sessions.Session, error)
}

SessionSource supplies fresh sessions on demand.

Note that it's an intentional subset of the gorilla/sessions.Store interface; any Store is a SessionSource.