Documentation
¶
Overview ¶
Package problem renders the error responses of the Reporting API: RFC 9457 documents served as application/problem+json. Every error the API returns goes through Write, so clients see one shape whatever failed.
It is a subpackage rather than part of httpapi so that the packages httpapi itself imports, such as authentication, can render problems without an import cycle.
The normative specification is roadmap/00-conventions.md section 7.
Index ¶
Constants ¶
const ( // TypeValidation marks a request the OpenAPI contract rejects. TypeValidation = "urn:tally:error:validation" TypeUnauthorized = "urn:tally:error:unauthorized" // TypeForbidden marks an authenticated caller that may not do this. TypeForbidden = "urn:tally:error:forbidden" // TypeNotFound marks a path or resource that does not exist. TypeNotFound = "urn:tally:error:not_found" // TypeMethodNotAllowed marks a known path addressed with the wrong method. TypeMethodNotAllowed = "urn:tally:error:method_not_allowed" // TypeConflict marks a write that collides with existing state, such as a // project whose (cloud, external_id) is already registered or a relation // triple that is already active. TypeConflict = "urn:tally:error:conflict" // TypePayloadTooLarge marks a request that carries more than the endpoint // takes at once, such as an event batch above the item limit. TypePayloadTooLarge = "urn:tally:error:payload_too_large" // TypeHistoryTooLong marks a resource or project whose stored history is // longer than the unpaginated per-resource reads answer at once. TypeHistoryTooLong = "urn:tally:error:history_too_long" // TypeResultTooLarge marks a query whose answer would be larger than this // API serves unpaginated, such as an event grouping over too wide a window. TypeResultTooLarge = "urn:tally:error:result_too_large" // TypeNotImplemented marks a parameter or a capability a later phase // delivers, such as counting resources at a historic instant. TypeNotImplemented = "urn:tally:error:not_implemented" // TypeRelationCycle marks a relation creation that would close a cycle over // the relation types that attribute cost. TypeRelationCycle = "urn:tally:error:relation_cycle" // TypeInternal marks a failure the caller cannot do anything about. TypeInternal = "urn:tally:error:internal" TypeUnavailable = "urn:tally:error:unavailable" )
The problem types this API uses. A client matches on these URNs rather than on the status code, which is why they are part of the contract.
const ContentType = "application/problem+json"
ContentType is the media type of every problem response.
Variables ¶
This section is empty.
Functions ¶
func Write ¶
func Write(w http.ResponseWriter, status int, typ, title, detail string, errs ...FieldError)
Write renders one problem: it sets the content type, sends status, and writes the document. The status is repeated inside the body, as RFC 9457 asks, so a problem stays self-describing once it is logged or forwarded.
Callers pass field errors only for validation failures.
Types ¶
type FieldError ¶
type FieldError struct {
// Loc is where the value sits, for example body.resource_id.
Loc string `json:"loc"`
// Msg says what is wrong with the value at that location.
Msg string `json:"msg"`
}
FieldError points at one offending value inside a rejected request.
Source Files