httpapi

package
v0.19.0 Latest Latest
Warning

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

Go to latest
Published: Mar 10, 2023 License: AGPL-3.0 Imports: 23 Imported by: 0

Documentation

Index

Constants

View Source
const (
	// XForwardedHostHeader is a header used by proxies to indicate the
	// original host of the request.
	XForwardedHostHeader = "X-Forwarded-Host"
)

Variables

View Source
var (
	UsernameValidRegex = regexp.MustCompile("^[a-zA-Z0-9]+(?:-[a-zA-Z0-9]+)*$")
)
View Source
var Validate *validator.Validate

Functions

func CompileHostnamePattern added in v0.10.0

func CompileHostnamePattern(pattern string) (*regexp.Regexp, error)

CompileHostnamePattern compiles a hostname pattern into a regular expression. A hostname pattern is a string that may contain a single wildcard character at the beginning. The wildcard character matches any number of hostname-safe characters excluding periods. The pattern is case-insensitive.

The supplied pattern:

  • must not start or end with a period
  • must contain exactly one asterisk at the beginning
  • must not contain any other wildcard characters
  • must not contain any other characters that are not hostname-safe (including whitespace)
  • must contain at least two hostname labels/segments (i.e. "foo" or "*" are not valid patterns, but "foo.bar" and "*.bar" are).

The returned regular expression will match an entire hostname with optional trailing periods and whitespace. The first submatch will be the wildcard match.

func ExecuteHostnamePattern added in v0.10.0

func ExecuteHostnamePattern(pattern *regexp.Regexp, hostname string) (string, bool)

ExecuteHostnamePattern executes a pattern generated by CompileHostnamePattern and returns the wildcard match. If the pattern does not match the hostname, returns false.

func Forbidden added in v0.5.10

func Forbidden(rw http.ResponseWriter)

func Heartbeat added in v0.9.3

func Heartbeat(ctx context.Context, conn *websocket.Conn)

Heartbeat loops to ping a WebSocket to keep it alive. Default idle connection timeouts are typically 60 seconds. See: https://docs.aws.amazon.com/elasticloadbalancing/latest/application/application-load-balancers.html#connection-idle-timeout

func HostnamesMatch added in v0.9.0

func HostnamesMatch(a, b string) bool

HostnamesMatch returns true if the hostnames are equal, disregarding capitalization, extra leading or trailing periods, and ports.

func InternalServerError added in v0.8.10

func InternalServerError(rw http.ResponseWriter, err error)

func IsWebsocketUpgrade added in v0.8.10

func IsWebsocketUpgrade(r *http.Request) bool

func NameValid added in v0.12.6

func NameValid(str string) error

NameValid returns whether the input string is a valid name. It is a generic validator for any name (user, workspace, template, etc.).

func ParseCustom added in v0.7.5

func ParseCustom[T any](parser *QueryParamParser, vals url.Values, def T, queryParam string, parseFunc func(v string) (T, error)) T

ParseCustom has to be a function, not a method on QueryParamParser because generics cannot be used on struct methods.

func ParseCustomList added in v0.18.1

func ParseCustomList[T any](parser *QueryParamParser, vals url.Values, def []T, queryParam string, parseFunc func(v string) (T, error)) []T

ParseCustomList is a function that handles csv query params.

func ParseEnum added in v0.18.1

func ParseEnum[T ValidEnum](term string) (T, error)

ParseEnum is a function that can be passed into ParseCustom that handles enum validation.

func Read

func Read(ctx context.Context, rw http.ResponseWriter, r *http.Request, value interface{}) bool

Read decodes JSON from the HTTP request into the value provided. It uses go-validator to validate the incoming request body. ctx is used for tracing and can be nil. Although tracing this function isn't likely too helpful, it was done to be consistent with Write.

func RequestHost added in v0.8.10

func RequestHost(r *http.Request) string

RequestHost returns the name of the host from the request. It prioritizes 'X-Forwarded-Host' over r.Host since most requests are being proxied.

func ResourceNotFound added in v0.7.0

func ResourceNotFound(rw http.ResponseWriter)

ResourceNotFound is intentionally vague. All 404 responses should be identical to prevent leaking existence of resources.

func RouteNotFound added in v0.9.0

func RouteNotFound(rw http.ResponseWriter)

func ServerSentEventSender added in v0.9.0

func ServerSentEventSender(rw http.ResponseWriter, r *http.Request) (sendEvent func(ctx context.Context, sse codersdk.ServerSentEvent) error, closed chan struct{}, err error)

func StripCoderCookies added in v0.8.6

func StripCoderCookies(header string) string

StripCoderCookies removes the session token from the cookie header provided.

func TemplateDisplayNameValid added in v0.12.6

func TemplateDisplayNameValid(str string) error

TemplateDisplayNameValid returns whether the input string is a valid template display name.

func UsernameFrom added in v0.8.2

func UsernameFrom(str string) string

UsernameFrom returns a best-effort username from the provided string.

It first attempts to validate the incoming string, which will be returned if it is valid. It then will attempt to extract the username from an email address. If no success happens during these steps, a random username will be returned.

func WebsocketCloseSprintf

func WebsocketCloseSprintf(format string, vars ...any) string

WebsocketCloseSprintf formats a websocket close message and ensures it is truncated to the maximum allowed length.

func Write

func Write(ctx context.Context, rw http.ResponseWriter, status int, response interface{})

Write outputs a standardized format to an HTTP response body. ctx is used for tracing and can be nil for tracing to be disabled. Tracing this function is helpful because JSON marshaling can sometimes take a non-insignificant amount of time, and could help us catch outliers. Additionally, we can enrich span data a bit more since we have access to the actual interface{} we're marshaling, such as the number of elements in an array, which could help us spot routes that need to be paginated.

Types

type ApplicationURL added in v0.8.15

type ApplicationURL struct {
	AppSlugOrPort string
	AgentName     string
	WorkspaceName string
	Username      string
}

ApplicationURL is a parsed application URL hostname.

func ParseSubdomainAppURL added in v0.8.15

func ParseSubdomainAppURL(subdomain string) (ApplicationURL, error)

ParseSubdomainAppURL parses an ApplicationURL from the given subdomain. If the subdomain is not a valid application URL hostname, returns a non-nil error. If the hostname is not a subdomain of the given base hostname, returns a non-nil error.

The base hostname should not include a scheme, leading asterisk or dot.

Subdomains should be in the form:

{PORT/APP_SLUG}--{AGENT_NAME}--{WORKSPACE_NAME}--{USERNAME}
(eg. https://8080--main--dev--dean.hi.c8s.io)

func (ApplicationURL) String added in v0.8.15

func (a ApplicationURL) String() string

String returns the application URL hostname without scheme. You will likely want to append a period and the base hostname.

type Duration added in v0.12.2

type Duration time.Duration

Duration wraps time.Duration and provides better JSON marshaling and unmarshalling. The default time.Duration marshals as an integer and only accepts integers when unmarshalling, which is not very user friendly as users cannot write durations like "1h30m".

This type marshals as a string like "1h30m", and unmarshals from either a string or an integer.

func (Duration) MarshalJSON added in v0.12.2

func (d Duration) MarshalJSON() ([]byte, error)

MarshalJSON implements json.Marshaler.

func (*Duration) UnmarshalJSON added in v0.12.2

func (d *Duration) UnmarshalJSON(b []byte) error

UnmarshalJSON implements json.Unmarshaler.

type QueryParamParser added in v0.7.0

type QueryParamParser struct {
	// Errors is the set of errors to return via the API. If the length
	// of this set is 0, there are no errors!.
	Errors []codersdk.ValidationError
	// Parsed is a map of all query params that were parsed. This is useful
	// for checking if extra query params were passed in.
	Parsed map[string]bool
}

QueryParamParser is a helper for parsing all query params and gathering all errors in 1 sweep. This means all invalid fields are returned at once, rather than only returning the first error

func NewQueryParamParser added in v0.7.0

func NewQueryParamParser() *QueryParamParser

func (*QueryParamParser) ErrorExcessParams added in v0.18.1

func (p *QueryParamParser) ErrorExcessParams(values url.Values)

ErrorExcessParams checks if any query params were passed in that were not parsed. If so, it adds an error to the parser as these values are not valid query parameters.

func (*QueryParamParser) Int added in v0.7.0

func (p *QueryParamParser) Int(vals url.Values, def int, queryParam string) int

func (*QueryParamParser) String added in v0.7.0

func (p *QueryParamParser) String(vals url.Values, def string, queryParam string) string

func (*QueryParamParser) Strings added in v0.7.5

func (p *QueryParamParser) Strings(vals url.Values, def []string, queryParam string) []string

func (*QueryParamParser) Time added in v0.18.1

func (p *QueryParamParser) Time(vals url.Values, def time.Time, queryParam string, format string) time.Time

func (*QueryParamParser) UUID added in v0.7.0

func (p *QueryParamParser) UUID(vals url.Values, def uuid.UUID, queryParam string) uuid.UUID

func (*QueryParamParser) UUIDorMe added in v0.7.0

func (p *QueryParamParser) UUIDorMe(vals url.Values, def uuid.UUID, me uuid.UUID, queryParam string) uuid.UUID

func (*QueryParamParser) UUIDs added in v0.7.0

func (p *QueryParamParser) UUIDs(vals url.Values, def []uuid.UUID, queryParam string) []uuid.UUID

type ValidEnum added in v0.18.1

type ValidEnum interface {
	database.ResourceType | database.AuditAction | database.BuildReason | database.UserStatus |
		database.WorkspaceStatus

	// Valid is required on the enum type to be used with ParseEnum.
	Valid() bool
}

ValidEnum parses enum query params. Add more to the list as needed.

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL