httpkit

package
v0.3.0 Latest Latest
Warning

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

Go to latest
Published: Nov 16, 2026 License: MIT Imports: 11 Imported by: 0

Documentation

Overview

Package httpkit holds the HTTP helpers every module's handlers share: the request context values the middleware leaves for handlers, the selection of an error response profile by ordered path rules, error and JSON writing, the caller checks handlers start with, and the conversion of OpenAPI path templates to chi patterns.

Role

platform layer, httpkit: the module-agnostic part of the HTTP surface. What an ecosystem or module decides, such as which paths answer in npm's or Docker's error envelope, reaches it as a value (a ProfileRule list) rather than an import, so that any module's HTTP adapter can call these helpers without importing the server or another module. Its subpackages are apierror (the envelopes), baseurl (the public base URL) and middleware (request IDs, logging, recovery and request shaping).

Inputs

  • Driving: the server's router, which installs ErrorProfiles with its rule list first, and the handlers and middleware that read and write the request context (WithRequestID and RequestIDFrom, WithAccept and Accepts, NoteCause, NoteUser and the rest of context.go).
  • The error profile rules: the server's ordered list, carried on each request's context (ErrorProfiles, or WithProfileRules for a test that calls a handler without the router).
  • Driven: none. It writes only to the response it is given and keeps no state of its own.

Outputs

  • Context: WithRequestID, RequestIDFrom, WithOriginalContentType, OriginalContentType, WithAccept, Accepts, WithRawBody, RawBody, WithCause, NoteCause, WithUser, NoteUser, WithSearchQuery and RawSearchQuery.
  • Error profiles: ProfileRule, ProfileFor, ErrorProfiles, ErrorProfile and WithProfileRules.
  • Writing: WriteErr, WriteJSON, EscapePath and FormatTime.
  • File names: EncodeQuery, EncodeUnreserved, EscapeQuoted and PrintableASCII, the encodings 7.x writes a downloaded file's name in (X-Artifactory-Filename, Content-Disposition).
  • Streamed lists: StreamList reads a list's first store page and returns a ListStream, whose Write sends the list page by page; ListOptions name its content type and Envelope, which ArrayEnvelope and EnvelopeOf build.
  • Callers: AdminOnly, Principal, Denied and BadRequestf, over the kernel's principal helpers.
  • Routes: ChiPatterns and NotAPI. Pointers: Deref, DerefSlice and PtrTo, for the optional fields of generated types.
  • Paging: NextLink, the Link header naming a list's next page (decision 0043, "Paging classes and the next pointer").

Invariants

  • The first rule that matches a path wins, so a narrower rule comes before a broader one with the same prefix; with no match, or no rules on the context, the profile is apierror.ProfileArtifactory, the same for unclaimed paths as for handled ones.
  • WriteErr sends the cause of an error that is not an *apierror.Error to the access log through NoteCause, because the client sees only a bare 500.
  • NoteCause and NoteUser do nothing on a context that never passed the access log, so a handler called on its own neither panics nor logs.
  • The caller checks answer with the kernel's typed errors (kernel.ErrUnauthenticated, kernel.ErrForbidden), which carry their status; AdminOnly wraps them as "repositories: %w", text clients have always seen.
  • A streamed list's bytes are those WriteJSON would send for the collected list: the same element encoding, envelope and trailing newline. It reads its first page before writing, so a store failure there answers as a collected list's would. A failure after the first byte aborts the response with http.ErrAbortHandler and notes the cause, and the closing bracket is never written, so no client takes a cut list for a whole one (decision 0043, "Streaming complete lists").
  • It imports no module, as the platform layer must not.

References

  • Decision 0002: docs/research/decisions/0002-spec-first-flat-crud-handwritten-item-paths.md (the error response profiles, which only their selection here changes).
  • Decision 0016: docs/research/decisions/0016-observability-and-health.md (request IDs, and the access log line that names the user, never the credential).
  • Decision 0043: docs/research/decisions/0043-api-reliability.md ("Streaming complete lists").
  • Decision 0044: docs/research/decisions/0044-modular-monolith-migration.md ("Dependency rules": the platform imports no module).
  • Target layout: docs/research/architecture-options/5-modular-monolith.md, lines 158 to 163 (platform/httpkit and its middleware) and lines 40 and 41 (dependency rule 4).
  • https://github.com/weaveplatform/artifactweave/issues/1069, https://github.com/weaveplatform/artifactweave/issues/1071 and https://github.com/weaveplatform/artifactweave/issues/1409 (streamed lists)

Status

Implemented P0 to P9c, as the server root's helpers: the context values and JSON and error writing from the baseline, the access log's cause and user slots and the property search's raw query in later phases. P9d (WEB-03) moved them here and turned the server's error-profile switch into ordered rules carried on the request context; WEB-07 added the caller checks, #1408 NextLink and PAGE-02 (#1409) the streamed lists.

Testing

The router's guards in app and the route suites under test/server reach these helpers through the router; TestAccP8ErrorProfiles and TestAccStubsAndEnvelopes check the profiles the rules choose. The unit tests here cover the branches those suites do not reach: rule order and the default, a request without rules, the context values on a bare context, the pointers' nil cases, the route patterns and each caller check's answers. TestUnitNextLink holds the next page's target to the client's path and parameters, only the position changed. stream_test.go holds a streamed list to the bytes WriteJSON sends for the same list, empty, short and over several pages, filtered and enveloped, and covers a failure before the first byte, after it, an expired deadline between pages and a failed write.

Index

Constants

View Source
const NotAPI = `(?:[^a/][^/]*|a(?:[^p/][^/]*)?|ap(?:[^i/][^/]*)?|api[^/]+)`

NotAPI is a chi pattern regular expression that matches one path segment other than the literal "api", the key Artifactory reserves.

Variables

This section is empty.

Functions

func Accepts

func Accepts(ctx context.Context, mediaType string) bool

Accepts reports whether the Accept header WithAccept kept names mediaType.

func AdminOnly

func AdminOnly(ctx context.Context) error

AdminOnly refuses a caller who is not an administrator (kernel.RequireAdmin) with the kernel's typed error wrapped as "repositories: %w". The wrap keeps the typed error, so the response carries its status: kernel.ErrUnauthenticated (401) without a user, and kernel.ErrForbidden (403) for a user who is not an administrator.

func BadRequestf

func BadRequestf(format string, a ...any) error

BadRequestf returns a 400 whose message is format applied to a.

func ChiPatterns

func ChiPatterns(template string) []string

ChiPatterns converts an OpenAPI path template to chi patterns. A trailing parameter is registered twice, once as a single segment and once as a wildcard, because Artifactory item paths ({itemPath}, {repoPath}) span segments and OpenAPI cannot say so.

func Denied

func Denied(p kernel.Principal) error

Denied refuses a read: anonymous is told to authenticate (kernel.ErrUnauthenticated), a user that they lack the right (kernel.ErrForbidden).

func Deref

func Deref[T any](p *T) T

Deref returns *p, or the zero value when p is nil, for the optional fields of generated request types.

func DerefSlice

func DerefSlice(p *[]string) []string

DerefSlice returns *p, or nil when p is nil.

func EncodeQuery

func EncodeQuery(s string) string

EncodeQuery percent-encodes s as Artifactory's BasicHttpUtils.encodeQuery writes a file's name into X-Artifactory-Filename and into the item route's filename* (7.161.26, URIUtil.encodeQuery in UTF-8): queryAllowed stay, and every other byte, a space, '"', '%' and each byte of a character outside ASCII among them, becomes %XX in upper-case hex. It keeps '@', which RTFACT-25859 (7.17.11) shows raw in filename*, and the sub-delimiters url.PathEscape encodes, so pkg(1).zip stays pkg(1).zip.

func EncodeUnreserved

func EncodeUnreserved(s string) string

EncodeUnreserved percent-encodes every byte of s but RFC 3986's unreserved characters, in upper-case hex, as Spring's UriUtils.encode does for a URI component. 7.161.26's RequestResponseHelper.setHeaderForNonAscii writes a name outside printable ASCII into filename* so; url.PathEscape keeps sub-delimiters such as '+' and '&', which UriUtils.encode encodes.

func ErrorProfile

func ErrorProfile(r *http.Request) apierror.Profile

ErrorProfile returns the error response profile of r's path under the rules on r's context. A request that never passed ErrorProfiles or WithProfileRules gets apierror.ProfileArtifactory.

func ErrorProfiles

func ErrorProfiles(rules []ProfileRule) func(http.Handler) http.Handler

ErrorProfiles is middleware that carries rules on each request's context, so that WriteErr and the middleware choose the error profile without knowing which ecosystem a path belongs to. It must be installed first, ahead of any middleware that can answer with an error.

func EscapePath

func EscapePath(p string) string

EscapePath escapes each segment of the slash-separated path p for a URL path, keeping the slashes between segments.

func EscapeQuoted

func EscapeQuoted(s string) string

EscapeQuoted escapes a quote or a backslash in s as a quoted pair, so that s can go inside a quoted-string whole. 7.x writes a file's name into filename="..." as it is, but its PathValidator refuses a path that holds either character, so it never writes one; here such a name cannot end the quoted string early.

func FormatTime

func FormatTime(t time.Time) string

FormatTime renders t in Artifactory's ISO 8601 form with milliseconds, in UTC.

func NextLink(path, rawQuery, position, value string) string

NextLink is the value of a Link header naming the next page of a list, `<target>; rel="next"` (RFC 8288), built as decision 0043 settles it: the target is path with the query the client sent, every parameter kept as sent, in its order, and only position set to value. A query without position gets it appended; one that repeats it keeps the first, set to value, and drops the rest, so the next request reads one position. Bytes a URI may not hold, such as a space or the angle brackets around the target, are percent-encoded, so a raw query a server accepted cannot end the target early.

func NoteCause

func NoteCause(ctx context.Context, err error)

NoteCause leaves err for the access log to log with the request. Without it an untyped error that apierror.Write hides reaches no log at all.

func NoteUser

func NoteUser(ctx context.Context, name string)

NoteUser leaves the user the middleware authenticated for the access log, which runs outside it and so never sees the principal. It records the user that any credential named, an X-NuGet-ApiKey's included, and never the credential.

func OriginalContentType

func OriginalContentType(ctx context.Context) string

OriginalContentType returns the vendor media type a client sent before the content-type middleware rewrote it, or "" when the client sent a plain type.

func Principal

func Principal(ctx context.Context) (kernel.Principal, error)

Principal returns the caller of a read, or kernel.ErrUnauthenticated when ctx carries none. The middleware lets a request without one through only to public routes, so none here means a router built without authentication, which is refused as unauthenticated.

func PrintableASCII

func PrintableASCII(s string) bool

PrintableASCII reports whether every byte of s is printable ASCII, ' ' to '~', as commons-lang's StringUtils.isAsciiPrintable decides for the file names 7.x's setHeaderForNonAscii leaves in their quoted form.

func ProfileFor

func ProfileFor(rules []ProfileRule, path string) apierror.Profile

ProfileFor returns the profile of the first rule in rules that matches path, or apierror.ProfileArtifactory when none does. Unclaimed paths take the same default as handled ones so that clients can read their 404s.

func PtrTo

func PtrTo[T any](v T) *T

PtrTo returns a pointer to a copy of v, for the optional fields of generated response types.

func RawBody

func RawBody(ctx context.Context) []byte

RawBody returns the request body WithRawBody kept, or nil.

func RawSearchQuery

func RawSearchQuery(ctx context.Context) string

RawSearchQuery returns the raw query WithSearchQuery kept, for the property search, whose parameters are property keys the generated binding drops.

func RequestIDFrom

func RequestIDFrom(ctx context.Context) string

RequestIDFrom returns the correlation id WithRequestID stored, or "" for a context that never passed the request ID middleware.

func WithAccept

func WithAccept(ctx context.Context, accept string) context.Context

WithAccept keeps the Accept header for strict handlers, which see only their decoded request: several operations answer with a vendor media type when the client asks for one, and their specs do not declare Accept.

func WithCause

func WithCause(ctx context.Context, slot *error) context.Context

WithCause gives the access log's handlers a slot for the error behind a 500 that the client sees only as "internal error".

func WithOriginalContentType

func WithOriginalContentType(ctx context.Context, mt string) context.Context

WithOriginalContentType returns ctx carrying the vendor media type a client sent before the content-type middleware rewrote it to application/json.

func WithProfileRules

func WithProfileRules(ctx context.Context, rules []ProfileRule) context.Context

WithProfileRules returns ctx carrying rules for ErrorProfile. A test that calls a handler without the router passes its rules through it.

func WithRawBody

func WithRawBody(ctx context.Context, b []byte) context.Context

WithRawBody returns ctx carrying a request body as read before the generated binding decoded it, for a handler that needs the bytes as sent.

func WithRequestID

func WithRequestID(ctx context.Context, id string) context.Context

WithRequestID returns ctx carrying the request's correlation id, which RequestIDFrom reads back for log lines.

func WithSearchQuery

func WithSearchQuery(ctx context.Context, raw string) context.Context

WithSearchQuery returns ctx carrying a request's raw query string.

func WithUser

func WithUser(ctx context.Context, slot *string) context.Context

WithUser gives the access log's handlers a slot for the name of the user the request authenticated as.

func WriteErr

func WriteErr(w http.ResponseWriter, r *http.Request, err error)

WriteErr renders err with the error response profile ErrorProfile gives r. An error that is not an *apierror.Error reaches the client as a bare 500, so its cause goes to the access log (NoteCause).

func WriteJSON

func WriteJSON(w http.ResponseWriter, status int, v any)

WriteJSON writes v as a JSON body with status. The status line is out once v is encoding, so an encoding failure can only cut the body short.

Types

type Envelope

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

Envelope is the JSON a streamed list is written inside: the bytes before its first element and the bytes after its last.

func ArrayEnvelope

func ArrayEnvelope() Envelope

ArrayEnvelope is the envelope of a list answered as a top-level array.

func EnvelopeOf

func EnvelopeOf(doc any, key string) (Envelope, error)

EnvelopeOf is the envelope of doc, a JSON object whose member key holds the list. doc is given with that member an empty array and is marshalled as the collected answer's encoder would marshal it, then split between the brackets, so the members around the list keep their order, their escaping and their omissions. Writing the elements between head and tail gives the collected answer's bytes.

type ListOptions

type ListOptions struct {
	// ContentType is the answer's media type; "" is application/json.
	ContentType string
	// Envelope holds the list; the zero value is ArrayEnvelope.
	Envelope Envelope
}

ListOptions shape a streamed list's 200.

type ListStream

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

ListStream is a complete list answered from store pages (decision 0043, "Streaming complete lists"): it is written element by element as the pages are read, never built whole in memory, and its bytes are the collected answer's, json.Encoder's with its default settings: the same order, HTML escaping and trailing newline. StreamList builds one after reading the first page; Write answers with it.

func StreamList

func StreamList[S, T any](
	ctx context.Context,
	pages *kernel.Pages[S],
	render func(S) (T, bool, error),
	opts ListOptions,
) (*ListStream, error)

StreamList starts a streamed list over pages. render turns each row into the element written for it and is the caller's visibility filter: a row it does not keep is left out. Before anything is written, StreamList reads and renders pages until one keeps an element or the list ends, so a store failure there, or a list with nothing to show, still answers a normal error: its error is the store's or render's, unwrapped.

func (*ListStream) Empty

func (l *ListStream) Empty() bool

Empty reports that the list keeps no element at all: StreamList read every page and render kept none.

func (*ListStream) Seen

func (l *ListStream) Seen() bool

Seen reports whether the pages StreamList read held any row, kept or not, which tells an empty list from one the caller may see nothing of.

func (*ListStream) Write

func (l *ListStream) Write(w http.ResponseWriter) error

Write answers 200 with the list. It writes one page at a time without flushing, so net/http frames an answer that fits its buffer with Content-Length and a larger one in chunks, as it frames the collected answer. Once the status is out it cannot change: a failed read or an expired deadline notes the cause for the access log and aborts the handler (http.ErrAbortHandler), so the closing bracket is never written and no client takes a shorter list for the whole one. A write the client no longer reads ends the answer quietly. It returns nil: the generated servers would answer a returned error with a second status.

type ProfileRule

type ProfileRule struct {
	Match   func(path string) bool
	Profile apierror.Profile
}

ProfileRule names the error response profile of the paths Match accepts. Rules form an ordered list: a narrower rule must come before a broader one that also matches its paths, as the JFrog operations beside the npm registry come before the registry's own prefix.

Directories

Path Synopsis
Package apierror renders errors with the response profile each client expects.
Package apierror renders errors with the response profile each client expects.
Package baseurl resolves the public base URL a response must embed.
Package baseurl resolves the public base URL a response must embed.
Package middleware holds the HTTP middleware that no module owns: request IDs, the access log, panic recovery, the management body limit, vendor media type normalisation, trailing-slash collection paths, a HEAD answered through its GET route, and the error handler of the generated strict servers.
Package middleware holds the HTTP middleware that no module owns: request IDs, the access log, panic recovery, the management body limit, vendor media type normalisation, trailing-slash collection paths, a HEAD answered through its GET route, and the error handler of the generated strict servers.

Jump to

Keyboard shortcuts

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