http

package
v0.31.10 Latest Latest
Warning

This package is not in the latest version of its module.

 Go to latest Published: Feb 12, 2024 License: MIT Imports: 23 Imported by: 0

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

Constants

View Source 
const BrotliSuffix = ".br"
View Source 
const GZipSuffix = ".gz"

Variables

View Source 
var MaxErrorStackDepth = 20

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

Functions

func CacheBustedPath added in v0.18.0 

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 added in v0.18.0 

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 added in v0.18.0 

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 added in v0.18.0 

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 ParseAuthorizationHeader added in v0.27.0 

func ParseAuthorizationHeader(auth string) (scheme, params string)

ParseAuthorizationHeader will parse an authorization header into its scheme and params

func ParseJsonBody added in v0.27.4 

func ParseJsonBody(w http.ResponseWriter, r *http.Request, maxBytes int64, dest any) error

ParseJsonBody will look for json in the request, parse it into the given dest, and handle errors.

The dest should be a pointer to a structure or some other value you want filled with the data. Errors will result in an appropriate error response written to the response writer, and an error response. If maxBytes is reached, it will close the connection and error.

func ParseValueAndParams added in v0.25.2 

func ParseValueAndParams(in string) (value string, params map[string]string)

ParseValueAndParams returns the value and param map for Content-Type and Content-Disposition header values

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.

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 added in v0.18.0 

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 added in v0.18.0 

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 added in v0.18.0 

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 RegisterContentType added in v0.23.2 

func RegisterContentType(extension string, contentType string)

RegisterContentType registers a content type that associates a file extension with a specific content type. You do not need to do this for all content served, as Go's http handler will try to guess the content type by the name of the file or the content itself. This is for those situations where Go's default is not working.

The extension must begin with a dot and have only one dot in it.

func RegisterDrawFunc added in v0.18.0 

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 added in v0.18.0 

func RegisterFileProcessor(extension string, processorFunc FileProcessorFunc)

RegisterFileProcessor registers a processor function for static files that have a particular extension. Do this at init time. The extension must begin with a dot and only have one dot in it.

func RegisterHandler added in v0.18.0 

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 added in v0.18.0 

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 added in v0.18.0 

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 SendForbiddenMessage added in v0.27.3 

func SendForbiddenMessage(m string)

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

func SendJsonAuthenticateError added in v0.20.0 

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

SendJsonAuthenticateError sends a WWW-Authenticate error encoding the values into both the WWW-Authenticate header 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 added in v0.17.2 

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 added in v0.20.0 

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 added in v0.18.0 

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 added in v0.18.0 

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 added in v0.18.0 

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.

Note that the default Go Muxer is NOT recommended, as it improperly handles redirects if this is behind a reverse proxy.

func UsePatternMuxer added in v0.18.0 

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.

func ValidateHeader added in v0.31.10 

func ValidateHeader(header http.Header) bool

ValidateHeader confirms that the given header's values only contains ASCII characters.

Types

type BufferedResponseWriterI 

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

BufferedResponseWriterI is the interface for a BufferedResponseWriter.

type DrawFunc added in v0.18.0 

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 added in v0.18.0 

func (e Error) Error() string

func (Error) Send added in v0.20.0 

func (e Error) Send()

func (Error) SetAuthenticateError added in v0.20.0 

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 added in v0.18.0 

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 added in v0.18.0 

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 added in v0.18.0 

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 added in v0.18.0 

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
}

func (FileSystemServer) ServeHTTP added in v0.18.0 

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

ServeHTTP will serve the file system.

type LocalPathMaker added in v0.18.0 

type LocalPathMaker func(string) string

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

type Mux added in v0.27.0 

type Mux struct {
	// contains filtered or unexported fields
}

Mux is the default muxer for Goradd.

Mux was written to fix the following problems with the Go default muxer: - It cannot work behind a reverse proxy because of its rewrite rules - Its algorithm for finding a handler gets slow the more handlers you give it - It does read locks, which is unnecessary in our case since goradd does not modify the mux after startup

If you register a path with a slash at the end of it, that handler will be redirected to the path with the slash at the end. To change this behavior, register for both paths, one with the slash, and one without.

Once you use the mux, you cannot add entries to it. This prevents race condition problems if the mux is being changed and accessed at the same time from two different go routines.

func NewMux added in v0.27.0 

func NewMux() *Mux

func (*Mux) Handle added in v0.27.0 

func (mux *Mux) Handle(pattern string, handler http.Handler)

Handle registers the handler for the given pattern. If a handler already exists for pattern, Handle panics.

func (*Mux) HandleFunc added in v0.27.0 

func (mux *Mux) HandleFunc(pattern string, handler func(http.ResponseWriter, *http.Request))

HandleFunc registers the handler function for the given pattern.

func (*Mux) Handler added in v0.27.0 

func (mux *Mux) Handler(r *http.Request) (h http.Handler, pattern string)

Handler returns the handler to use for the given request r.URL.Path. The incoming path must be cleaned before being sent here.

If the path cannot be found, but its equivalent path with an ending slash is found, the handler for the slashed path will be returned.

The path and host are used unchanged for CONNECT requests.

Handler also returns the registered pattern that matches the request or, in the case of internally-generated redirects, the pattern that will match after following the redirect.

If there is no registered handler that applies to the request, Handler returns a “page not found” handler and an empty pattern.

func (*Mux) ServeHTTP added in v0.27.0 

func (mux *Mux) ServeHTTP(w http.ResponseWriter, r *http.Request)

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 muxer here with a 3rd party mux, like the Gorilla mux.

However, beware. The default Go muxer will do redirects. If this goradd application is behind a reverse proxy that is rewriting the url, the Go muxer will not correctly do rewrites because it will not include the reverse proxy path in the rewrite rule, and things will break.

If you create your own mux and you want to do redirects, use MakeLocalPath to create the redirect url. See also maps.SafeMap for a map you can use if you are modifying paths while using the 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 added in v0.18.0 

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 added in v0.18.0 

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

NewServerError creates a new ServerError.

func (ServerError) Error added in v0.18.0 

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.

Source Files

View all Source files

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.