util

Documentation

Index

• Variables
• func ErrorHandler(c *gin.Context, errWithCode gtserror.WithCode, ...)
• func NegotiateAccept(c *gin.Context, offers ...MIME) (string, error)
• func NotFoundHandler(c *gin.Context, ...)
• func OAuthErrorHandler(c *gin.Context, errWithCode gtserror.WithCode)
• func TransferSignatureContext(c *gin.Context) context.Context
• type MIME

Variables

var ActivityPubAcceptHeaders = []MIME{
	AppActivityJSON,
	AppActivityLDJSON,
}

ActivityPubAcceptHeaders represents the Accept headers mentioned here:

var HTMLAcceptHeaders = []MIME{
	TextHTML,
}

HTMLAcceptHeaders is a slice of offers that just contains text/html types.

var HTMLOrActivityPubHeaders = []MIME{
	TextHTML,
	AppActivityJSON,
	AppActivityLDJSON,
}

HTMLOrActivityPubHeaders matches text/html first, then activitypub types. This is useful for user URLs that a user might go to in their browser. https://www.w3.org/TR/activitypub/#retrieving-objects

var HTMLOrJSONAcceptHeaders = []MIME{
	TextHTML,
	AppJSON,
}

HTMLOrJSONAcceptHeaders is a slice of offers that prefers TextHTML and will fall back to JSON if necessary. This is useful for error handling, since it can be used to serve a nice HTML page if the caller accepts that, or just JSON if not.

var JSONAcceptHeaders = []MIME{
	AppJSON,
}

JSONAcceptHeaders is a slice of offers that just contains application/json types.

Functions

func ErrorHandler

func ErrorHandler(c *gin.Context, errWithCode gtserror.WithCode, instanceGet func(ctx context.Context) (*apimodel.InstanceV1, gtserror.WithCode))

ErrorHandler takes the provided gin context and errWithCode and tries to serve a helpful error to the caller. It will do content negotiation to figure out if the caller prefers to see an html page with the error rendered there. If not, or if something goes wrong during the function, it will recover and just try to serve an appropriate application/json content-type error.

func NegotiateAccept

func NegotiateAccept(c *gin.Context, offers ...MIME) (string, error)

NegotiateAccept takes the *gin.Context from an incoming request, and a slice of Offers, and performs content negotiation for the given request with the given content-type offers. It will return a string representation of the first suitable content-type, or an error if something goes wrong or a suitable content-type cannot be matched.

For example, if the request in the *gin.Context has Accept headers of value [application/json, text/html], and the provided offers are of value [application/json, application/xml], then the returned string will be 'application/json', which indicates the content-type that should be returned.

If the length of offers is 0, then an error will be returned, so this function should only be called in places where format negotiation is actually needed.

If there are no Accept headers in the request, then the first offer will be returned, under the assumption that it's better to serve *something* than error out completely.

Callers can use the offer slices exported in this package as shortcuts for often-used Accept types.

See https://developer.mozilla.org/en-US/docs/Web/HTTP/Content_negotiation#server-driven_content_negotiation

func NotFoundHandler

func NotFoundHandler(c *gin.Context, instanceGet func(ctx context.Context) (*apimodel.InstanceV1, gtserror.WithCode), accept string)

NotFoundHandler serves a 404 html page through the provided gin context, if accept is 'text/html', or just returns a json error if 'accept' is empty or application/json.

When serving html, NotFoundHandler calls the provided InstanceGet function to fetch the apimodel representation of the instance, for serving in the 404 header and footer.

If an error is returned by InstanceGet, the function will panic.

func OAuthErrorHandler

func OAuthErrorHandler(c *gin.Context, errWithCode gtserror.WithCode)

OAuthErrorHandler is a lot like ErrorHandler, but it specifically returns errors that are compatible with https://datatracker.ietf.org/doc/html/rfc6749#section-5.2, but serializing errWithCode.Error() in the 'error' field, and putting any help text from the error in the 'error_description' field. This means you should be careful not to pass any detailed errors (that might contain sensitive information) into the errWithCode.Error() field, since the client will see this. Use your noggin!

func TransferSignatureContext

func TransferSignatureContext(c *gin.Context) context.Context

TransferSignatureContext transfers a signature verifier and signature from a gin context to a go context.

Types

type MIME

type MIME string

MIME represents a mime-type.

const (
	AppJSON           MIME = `application/json`
	AppXML            MIME = `application/xml`
	AppRSSXML         MIME = `application/rss+xml`
	AppActivityJSON   MIME = `application/activity+json`
	AppActivityLDJSON MIME = `application/ld+json; profile="https://www.w3.org/ns/activitystreams"`
	AppForm           MIME = `application/x-www-form-urlencoded`
	MultipartForm     MIME = `multipart/form-data`
	TextXML           MIME = `text/xml`
	TextHTML          MIME = `text/html`
	TextCSS           MIME = `text/css`
)

MIME type