http

Documentation

Overview

Package http contains utilities to support traditional http server output and middleware from the goradd server.

In particular, the Muxer object here helps you point to files that you generate without the Page manager. Examples would be a REST api, and generated CSV, PDF and image files.

Index

• Variables
• func CacheBustedPath(url string) string
• func DisableOutputBuffering(ctx context.Context)
• func GetAssetUrl(location string) string
• func MakeLocalPath(p string) string
• func OutputLen(ctx context.Context) int
• func Redirect(location string, errCode int)
• func RegisterAppHandler(pattern string, handler http.Handler)
• func RegisterAppPrefixHandler(prefix string, handler http.Handler)
• func RegisterAssetDirectory(prefix string, fsys fs.FS)
• func RegisterDrawFunc(pattern string, f DrawFunc)
• func RegisterFileProcessor(extension string, processorFunc FileProcessorFunc)
• func RegisterHandler(pattern string, handler http.Handler)
• func RegisterPrefixHandler(prefix string, handler http.Handler)
• func ResetOutputBuffer(ctx context.Context) []byte
• func SendBadRequest()
• func SendBadRequestMessage(message string)
• func SendErrorCode(errCode int)
• func SendErrorMessage(message string, errCode int)
• func SendForbidden()
• func SendJsonAuthenticateError(errCode int, authScheme string, values map[string]string)
• func SendMethodNotAllowed(allowedMethods ...string)
• func SendNotFound()
• func SendNotFoundMessage(message string)
• func SendUnauthorized()
• func SendUnauthorizedMessage(message string)
• func SetBufferedOutputManager(u User)
• func SetLocalPathMaker(f LocalPathMaker)
• func StripCacheBusterPath(fPath string) string
• func UseAppMuxer(mux Muxer, next http.Handler) http.Handler
• func UseMuxer(mux Muxer, next http.Handler) http.Handler
• func UsePatternMuxer(mux Muxer, next http.Handler) http.Handler
• type BufferedResponseWriterI
• type DrawFunc
• type Error
  • func (e Error) Error() string
  • func (e Error) Send()
  • func (e Error) SetAuthenticateError(authScheme string, values map[string]string)
  • func (e *Error) SetResponseHeader(key, value string)
• type ErrorReporter
  • func (e ErrorReporter) Use(h http.Handler) http.Handler
• type FileProcessorFunc
• type FileSystemServer
  • func (f FileSystemServer) ServeHTTP(w http.ResponseWriter, r *http.Request)
• type LocalPathMaker
• type Muxer
• type ServerError
  • func NewServerError(err string, mode string, r *http.Request, skipFrames int, output string) *ServerError
  • func (s ServerError) Error() string
• type User
  • func BufferedOutputManager() User

Variables

var MaxErrorStackDepth = 20

MaxErrorStackDepth is the maximum stack depth reported to the error log when a panic happens.

Functions

func CacheBustedPath

func CacheBustedPath(url string) string

CacheBustedPath returns a path to an asset that was previously registered with the CacheBuster. The new path will contain a hash of the file that will change whenever the file changes, and cause the browser to reload the file. Since we are in control of serving these files, we will later remove the hash before serving it.

func DisableOutputBuffering

func DisableOutputBuffering(ctx context.Context)

DisableOutputBuffering turns off output buffering.

This function is useful if you want to stream large quantities of data to the response writer, and you want to avoid the memory allocation required for buffering. The default output buffer manager will not output what has been buffered so far. You should not try to re-enable output buffering.

func GetAssetUrl

func GetAssetUrl(location string) string

GetAssetUrl returns the url that corresponds to the asset at the given path.

This will add the cache-buster path, and the proxy path if there is one.

func MakeLocalPath

func MakeLocalPath(p string) string

MakeLocalPath turns a path that points to a resource on this computer into a path that will reach that resource from a browser. It takes into account a variety of settings that may affect the path and that will depend on how the app is deployed. You can inject your own local path maker using SetLocalPathMaker

func OutputLen

func OutputLen(ctx context.Context) int

OutputLen returns the number of bytes written to the output.

If output buffering is disabled, this will be the number of bytes actually written to the response writer. If output buffering is enabled, this is the number of bytes in the buffer waiting to be sent.

func Redirect

func Redirect(location string, errCode int)

Redirect will error such that the server will attempt to access the resource at a new location.

This will set the Location header to point to the new location.

Be sure to call http.MakeLocalPath() if the resource is pointing to a location on this server.

errCode should be a 3XX error, like one of the following:

StatusMovedPermanently  = 301 // RFC 7231, 6.4.2
StatusFound             = 302 // RFC 7231, 6.4.3
StatusSeeOther          = 303 // RFC 7231, 6.4.4
StatusTemporaryRedirect = 307 // RFC 7231, 6.4.7
StatusPermanentRedirect = 308 // RFC 7538, 3

func RegisterAppHandler

func RegisterAppHandler(pattern string, handler http.Handler)

RegisterAppHandler registers a handler for the given pattern.

Use this when registering a handler to a specific path. Use RegisterAppPrefixHandler if registering a handler for a whole subdirectory of a path.

The given handler is served near the end of the application handler stack, so you will have access to session management and any other middleware handlers in the application stack.

You may call this from an init() function.

func RegisterAppPrefixHandler

func RegisterAppPrefixHandler(prefix string, handler http.Handler)

RegisterAppPrefixHandler registers a handler for the given directory prefix.

The handler will be called at the end of the application handler middleware stack.

The handler will be called with the prefix stripped away. When the prefix is stripped, a rooted path will be passed along. In other words, if the prefix is /api, and the path being served is /api/file, the called handler will receive /file.

Note that you CAN register a handler for the root directory.

If the handler is presented a URL that it does not recognize, it should return an HTTP error to the ResponseWriter.

You may call this from an init() function.

func RegisterAssetDirectory

func RegisterAssetDirectory(prefix string, fsys fs.FS)

RegisterAssetDirectory maps a file system to a URL path in the application.

The files in the path are registered with the cache buster, so that when you edit the file a new URL will be generated forcing the browser to reload the asset. This is much better than using a cache control header.

If the browser attempts to access a file in the file system that does not exist, a 404 NotFound error will be sent back to the browser.

func RegisterDrawFunc

func RegisterDrawFunc(pattern string, f DrawFunc)

RegisterDrawFunc registers an output function for the given pattern.

This could be used to register template output with a path, for example. See the renderResource template macro and the configure.tpl.got file in the welcome application for an example.

The file name extension will be used first to determine the Content-Type. If that fails, then the content will be inspected to determine the Content-Type.

Registered handlers are served by the AppMuxer.

func RegisterFileProcessor

func RegisterFileProcessor(extension string, processorFunc FileProcessorFunc)

RegisterFileProcessor registers a processor function for static files that have a particular extension. Do this at init time.

func RegisterHandler

func RegisterHandler(pattern string, handler http.Handler)

RegisterHandler registers a handler for the given pattern.

Use this when registering a handler to a specific path. Use RegisterPrefixHandler if registering a handler for a whole subdirectory of a path.

The given handler is served immediately by the application without going through the application handler stack. If you need session management, HSTS protection, authentication, etc., use RegisterAppHandler.

You may call this from an init() function.

func RegisterPrefixHandler

func RegisterPrefixHandler(prefix string, handler http.Handler)

RegisterPrefixHandler registers a handler for the given directory prefix.

The handler will be called immediately based on the path and will not be sent through the application handler middleware stack. Use RegisterAppPrefixHandler for the equivalent function processed at the end of the application handler stack.

The handler will be called with the prefix stripped away. When the prefix is stripped, a rooted path will be passed along. In other words, if the prefix is /api, and the path being served is /api/file, the called handler will receive /file.

Note that you CAN register a handler for the root directory.

If the handler is presented a URL that it does not recognize, it should return an HTTP error to the ResponseWriter.

You may call this from an init() function.

func ResetOutputBuffer

func ResetOutputBuffer(ctx context.Context) []byte

ResetOutputBuffer returns the current output buffer and resets the output buffer to nothing.

func SendBadRequest

func SendBadRequest()

SendBadRequest sends a StatusBadRequest code to the output.

func SendBadRequestMessage

func SendBadRequestMessage(message string)

SendBadRequestMessage sends a StatusBadRequest code to the output with a message.

func SendErrorCode

func SendErrorCode(errCode int)

SendErrorCode will cause the page to error with the given http error code.

func SendErrorMessage

func SendErrorMessage(message string, errCode int)

SendErrorMessage sends the error message with the http code to the browser.

func SendForbidden

func SendForbidden()

SendForbidden will tell the user that he/she does not have authorization to access the given resource. The user should be known.

func SendJsonAuthenticateError

func SendJsonAuthenticateError(errCode int, authScheme string, values map[string]string)

SendJsonAuthenticateError sends a WWW-Authenticate error encoding the values into both the WWW-Authenticate and as a json response

func SendMethodNotAllowed

func SendMethodNotAllowed(allowedMethods ...string)

SendMethodNotAllowed will tell the user that the server is not able to perform the http method being asked. allowedMethods is a list of the allowed methods.

func SendNotFound

func SendNotFound()

SendNotFound sends a StatsNotFound error to the output.

func SendNotFoundMessage

func SendNotFoundMessage(message string)

SendNotFoundMessage sends a StatusNotFound with a message.

func SendUnauthorized

func SendUnauthorized()

SendUnauthorized will send an error code indicating that the user is not authenticated (yes, even though the title is "authorized", it really means "authenticated", i.e. not logged in.) If serving HTML, you likely should redirect to the login page instead.

func SendUnauthorizedMessage

func SendUnauthorizedMessage(message string)

SendUnauthorizedMessage will send an error code indicating that the user is not authenticated (yes, even though the title is "authorized", it really means "authenticated", i.e. not logged in.) If serving HTML, you likely should redirect to the login page instead.

func SetBufferedOutputManager

func SetBufferedOutputManager(u User)

SetBufferedOutputManager injects the given manager as the global buffered output manager. Call this to change it to your own version.

Your custom version should create a BufferedResponseWriterI object and attach it to the goradd.BufferContext value in the context. See defaultBufferedOutputManager.Use for an example.

func SetLocalPathMaker

func SetLocalPathMaker(f LocalPathMaker)

SetLocalPathMaker sets the local path maker to the given one.

The default local path maker will prepend config.ProxyPath to all local paths.

func StripCacheBusterPath

func StripCacheBusterPath(fPath string) string

StripCacheBusterPath removes the hash of the asset file from the path to the asset.

func UseAppMuxer

func UseAppMuxer(mux Muxer, next http.Handler) http.Handler

UseAppMuxer is called by the framework at application startup to place the application muxer at the end of the application handler stack

next specifies a handler that will be used if the AppMuxer is presented a URL that it does not recognize.

func UseMuxer

func UseMuxer(mux Muxer, next http.Handler) http.Handler

UseMuxer serves a muxer such that if a handler cannot be found, or the found handler does not respond, control is past to the next handler.

func UsePatternMuxer

func UsePatternMuxer(mux Muxer, next http.Handler) http.Handler

UsePatternMuxer is called by the framework at application startup to place the pattern mux in the handler stack.

All previously registered pattern handlers will be put in the given muxer. The muxer will be remembered so that future registrations will go to that muxer.

next specifies a handler that will be used if the muxer processes a URL that it does not recognize.

Types

type BufferedResponseWriterI

type BufferedResponseWriterI interface {
	http.ResponseWriter
	Disable()
	OutputBuffer() *bytes.Buffer
	Len() int
}

BufferedResponseWriterI is the interface for a BufferedResponseWriter.

type DrawFunc

type DrawFunc func(ctx context.Context, w io.Writer) (err error)

A DrawFunc sends output to the Writer. goradd uses this signature in its template functions.

type Error

type Error struct {
	Message string
	Headers map[string]string
	ErrCode int
}

Error represents an error response to an http request.

See http.Status* codes for status code constants

func (Error) Error

func (e Error) Error() string

func (Error) Send

func (e Error) Send()

func (Error) SetAuthenticateError

func (e Error) SetAuthenticateError(authScheme string, values map[string]string)

SetAuthenticateError sets the WWW-Authenticate with the given authScheme and values.

func (*Error) SetResponseHeader

func (e *Error) SetResponseHeader(key, value string)

SetResponseHeader sets a key-value in the header response.

type ErrorReporter

type ErrorReporter struct {
}

ErrorReporter is a middleware that will catch panics and other errors and convert them to http output messages. It also logs panics to the error logger.

func (ErrorReporter) Use

func (e ErrorReporter) Use(h http.Handler) http.Handler

Use wraps the given handler in a default HTTP error handler that will respond appropriately to any panics that happen within the given handler.

Panic with an http.Error value to get a specific kind of http error to be output. Otherwise, errors will be sent to the log.Error logger.

type FileProcessorFunc

type FileProcessorFunc func(r io.Reader, w http.ResponseWriter, req *http.Request) error

FileProcessorFunc processes a static file and outputs it to the response writer.

type FileSystemServer

type FileSystemServer struct {
	// Fsys is the file system being served.
	Fsys fs.FS

	// SendModTime will send the modification time of the file when it is served. Generally, you want
	// to do this for files that can be bookmarked, like html files, since there really is no other way
	// to try to get the server to reload the file when it is changed. However, for asset files that are
	// using the cache buster, you should not do this, since cache busting will take care of notifying
	// the user the file is changed.
	SendModTime bool

	// UseCacheBuster will look for cache buster paths and fix them.
	UseCacheBuster bool

	// Hide is a slice of file endings that will be blocked from being served. These endings do not have to just
	// be file extensions, but any string. So if you specify an ending of "_abc.txt", any file ending in the
	// string will NOT be shown.
	Hide []string
}

FileSystemServer serves a file system as an http.Handler.

The file system contained can point to compressed versions of http resources, and those compressed version will be served when possible. In fact, you may only store compressed versions, and if the browser does not support compression, the compressed file will be decompressed here before serving the file. This lets you save space by only storing a compressed file, at the cost of some speed. Since most browsers support compression, this should not be a big deal.

The files in Fsys must implement the io.ReaderSeeker interface. Both embed and traditional OS file systems do this.

Files found will be sent to any registered file processors if the extension matches one of the processors (see RegisterFileProcessor).

func (FileSystemServer) ServeHTTP

func (f FileSystemServer) ServeHTTP(w http.ResponseWriter, r *http.Request)

ServeHTTP will serve the file system.

type LocalPathMaker

type LocalPathMaker func(string) string

LocalPathMaker converts an HTTP path rooted to the application, to a path accessible by the server.

type Muxer

type Muxer interface {
	// Handle associates a handler with the given pattern in the url path
	Handle(pattern string, handler http.Handler)

	// Handler returns the handler associate with the request, if one exists. It
	// also returns the actual path registered to the handler
	Handler(r *http.Request) (h http.Handler, pattern string)

	// ServeHTTP sends a request to the MUX, to be forwarded on to the registered handler,
	// or responded with an unknown resource error.
	ServeHTTP(w http.ResponseWriter, r *http.Request)
}

Muxer represents the typical functions available in a mux and allows you to replace the default Golang muxer here with a 3rd party mux, like the Gorilla mux.

var AppMuxer Muxer

AppMuxer is the application muxer that lets you do traditional http handling from behind the application facilities of session management, output buffering, etc. It is automatically loaded during app startup.

var PatternMuxer Muxer

PatternMuxer is the muxer that immediately routes handlers based on the path without going through the application handlers. It is automatically loaded during app startup.

type ServerError

type ServerError struct {
	// the error string
	Err string
	// Mode indicates whether we are serving ajax or not
	Mode string
	// the time the error occurred
	Time    time.Time
	Request *http.Request
	// Output will replace what gets written to the output
	Output string
	// How much additional to unwind the stack trace
	StackDepth int
}

ServerError represents an error caused by an unexpected panic

func NewServerError

func NewServerError(err string, mode string, r *http.Request, skipFrames int, output string) *ServerError

NewServerError creates a new ServerError.

func (ServerError) Error

func (s ServerError) Error() string

Error returns the string that is sent to the logger

type User

type User interface {
	// Use wraps the given handler.
	Use(http.Handler) http.Handler
}

User is the interface for http managers that can be injected into the handler stack.

func BufferedOutputManager

func BufferedOutputManager() User

BufferedOutputManager returns the buffered output manager.