Documentation
¶
Index ¶
- Constants
- type APIRequest
- func (comm *APIRequest) GetUUID() (string, error)
- func (req *APIRequest) Prepare(signer *crypto.Signer, meta *Metadata, body []byte) error
- func (req *APIRequest) Respond(signer *crypto.Signer, meta *Metadata, body []byte) (*APIResponse, error)
- func (req *APIRequest) Verify(signer *crypto.Signer) (bool, error)
- type APIResponse
- type ApiHeader
- type FlowViolation
- type IncompatibleModeError
- type LifecycleViolation
- type Metadata
- type ProtocolViolation
- type StandardMismatch
Constants ¶
const STANDARD_VERSION string = "2.0"
STANDARD_VERSION defines the latest supported API standard implemented by this library. It is compared against incoming traffic to detect mismatches.
Variables ¶
This section is empty.
Functions ¶
This section is empty.
Types ¶
type APIRequest ¶ added in v0.9.0
APIRequest wraps http.Request with helpers that add API metadata, perform signing, and enforce invariants such as UUID management.
func (*APIRequest) GetUUID ¶ added in v0.10.0
GetUUID returns the UUID stored in the communication helper or fails if the caller did not run Prepare/Sanitize beforehand.
func (*APIRequest) Prepare ¶ added in v0.9.0
Prepare finalizes an outbound request by generating a UUID, attaching API metadata, and optionally signing the payload with the provided signer.
func (*APIRequest) Respond ¶ added in v0.9.0
func (req *APIRequest) Respond(signer *crypto.Signer, meta *Metadata, body []byte) (*APIResponse, error)
Respond builds a response that matches the inbound request, attaches the proper metadata, and signs the payload when a signer is provided.
type APIResponse ¶ added in v0.9.0
APIResponse wraps http.Response with the same helper logic used by APIRequest, allowing a symmetric workflow on both sides.
func (*APIResponse) GetUUID ¶ added in v0.10.0
GetUUID returns the UUID stored in the communication helper or fails if the caller did not run Prepare/Sanitize beforehand.
func (*APIResponse) Prepare ¶ added in v0.9.0
Prepare mutates the response headers/body with metadata and an optional signature. It must be called before sending the response to the client.
func (*APIResponse) Verify ¶ added in v0.9.0
func (res *APIResponse) Verify(signer *crypto.Signer, req *APIRequest) (bool, error)
Verify ensures a response matches the originating request, checks metadata, and validates the signature produced by the remote signer.
type ApiHeader ¶
type ApiHeader string
ApiHeader identifies the HTTP header key used for the API control plane. Header values communicate metadata such as the API version, signature data, or transport specific IDs.
const ( // SIGNATURE_PUBKEY carries the base64 encoded public key expected to verify // a request or response signature. SIGNATURE_PUBKEY ApiHeader = "X-API-SIG-PUB" // SIGNATURE carries the detached signature that authenticates the payload. SIGNATURE ApiHeader = "X-API-SIG" // VERSION tells the remote side which API implementation version produced // the request or response. VERSION ApiHeader = "X-API-VER" // PROJECT communicates the logical project or tenant identifier used to // route or audit the API call. PROJECT ApiHeader = "X-API-PROJ" // STANDARD communicates which API standard revision the payload follows. STANDARD ApiHeader = "X-API-STD" // REQUEST_UUID uniquely identifies a specific in-flight request so both // sides can correlate responses without ambiguity. REQUEST_UUID ApiHeader = "X-API-UUID" )
type FlowViolation ¶ added in v0.10.1
type FlowViolation error
FlowViolation captures mismatches between paired objects, such as a response referencing a different request UUID than the originating call.
type IncompatibleModeError ¶ added in v0.10.1
type IncompatibleModeError error
IncompatibleModeError signals that the caller attempted an operation, such as signature verification, that is unsupported in the configured transport mode (e.g. mTLS only).
type LifecycleViolation ¶ added in v0.10.1
type LifecycleViolation error
LifecycleViolation communicates that an API object was used out of sequence, for example calling Prepare twice.
type Metadata ¶
type Metadata struct {
// Version is the application specific version to surface to API peers.
Version string
// ProjectID is a scoped identifier assigned to the calling system.
ProjectID uint64
}
Metadata bundles attributes that travel with each API request/response. Callers should fill these fields once and pass the struct to helper methods.
Source Files
¶
- Communication.go
- Errors.go
- Headers.go
- Metadata.go