http

package
v0.18.0 Latest Latest
Warning

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

 Go to latest Published: Feb 7, 2022 License: MIT Imports: 22 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

This section is empty.

Variables

View Source 
var MaxErrorStackDepth = 20

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)

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, even if output buffering is disabled.

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

func RegisterDrawFunc(pattern string, f DrawFunc)

RegisterDrawFunc registers a 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.

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.

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()

func SendBadRequestMessage 

func SendBadRequestMessage(message string)

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)

func SendForbidden 

func SendForbidden()

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

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()

func SendNotFoundMessage added in v0.17.2 

func SendNotFoundMessage(message string)

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 SetBufferedOutputManager 

func SetBufferedOutputManager(u User)

SetBufferedOutputManager injects the given manager as the global buffered output manager

func SetLocalPathMaker added in v0.18.0 

func SetLocalPathMaker(f LocalPathMaker)

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.

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.

Types

type BufferedResponseWriterI 

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

type DrawFunc added in v0.18.0 

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

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) 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 {
}

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

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
}

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 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

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 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

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

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.