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
- func Accepts(ctx context.Context, mediaType string) bool
- func AdminOnly(ctx context.Context) error
- func BadRequestf(format string, a ...any) error
- func ChiPatterns(template string) []string
- func Denied(p kernel.Principal) error
- func Deref[T any](p *T) T
- func DerefSlice(p *[]string) []string
- func EncodeQuery(s string) string
- func EncodeUnreserved(s string) string
- func ErrorProfile(r *http.Request) apierror.Profile
- func ErrorProfiles(rules []ProfileRule) func(http.Handler) http.Handler
- func EscapePath(p string) string
- func EscapeQuoted(s string) string
- func FormatTime(t time.Time) string
- func NextLink(path, rawQuery, position, value string) string
- func NoteCause(ctx context.Context, err error)
- func NoteUser(ctx context.Context, name string)
- func OriginalContentType(ctx context.Context) string
- func Principal(ctx context.Context) (kernel.Principal, error)
- func PrintableASCII(s string) bool
- func ProfileFor(rules []ProfileRule, path string) apierror.Profile
- func PtrTo[T any](v T) *T
- func RawBody(ctx context.Context) []byte
- func RawSearchQuery(ctx context.Context) string
- func RequestIDFrom(ctx context.Context) string
- func WithAccept(ctx context.Context, accept string) context.Context
- func WithCause(ctx context.Context, slot *error) context.Context
- func WithOriginalContentType(ctx context.Context, mt string) context.Context
- func WithProfileRules(ctx context.Context, rules []ProfileRule) context.Context
- func WithRawBody(ctx context.Context, b []byte) context.Context
- func WithRequestID(ctx context.Context, id string) context.Context
- func WithSearchQuery(ctx context.Context, raw string) context.Context
- func WithUser(ctx context.Context, slot *string) context.Context
- func WriteErr(w http.ResponseWriter, r *http.Request, err error)
- func WriteJSON(w http.ResponseWriter, status int, v any)
- type Envelope
- type ListOptions
- type ListStream
- type ProfileRule
Constants ¶
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 AdminOnly ¶
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 ¶
BadRequestf returns a 400 whose message is format applied to a.
func ChiPatterns ¶
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 ¶
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 ¶
DerefSlice returns *p, or nil when p is nil.
func EncodeQuery ¶
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 ¶
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 ¶
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 ¶
EscapePath escapes each segment of the slash-separated path p for a URL path, keeping the slashes between segments.
func EscapeQuoted ¶
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 ¶
FormatTime renders t in Artifactory's ISO 8601 form with milliseconds, in UTC.
func NextLink ¶
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 ¶
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 ¶
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 ¶
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 ¶
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 ¶
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 RawSearchQuery ¶
RawSearchQuery returns the raw query WithSearchQuery kept, for the property search, whose parameters are property keys the generated binding drops.
func RequestIDFrom ¶
RequestIDFrom returns the correlation id WithRequestID stored, or "" for a context that never passed the request ID middleware.
func WithAccept ¶
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 ¶
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 ¶
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 ¶
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 ¶
WithRequestID returns ctx carrying the request's correlation id, which RequestIDFrom reads back for log lines.
func WithSearchQuery ¶
WithSearchQuery returns ctx carrying a request's raw query string.
func WithUser ¶
WithUser gives the access log's handlers a slot for the name of the user the request authenticated as.
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 ¶
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 ¶
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.
Source Files
¶
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. |