Documentation
¶
Overview ¶
Package registry provides read-only observation types produced by adapters.
These types are designed to be consumed (e.g., by OpenAPI generators and tooling) and are not intended to be constructed by users.
Index ¶
Constants ¶
const SnapshotDTOFormatVersion = "1.0"
SnapshotDTOFormatVersion is the current JSON format version returned by RegistrySnapshot.SnapshotDTO().
Variables ¶
This section is empty.
Functions ¶
This section is empty.
Types ¶
type DocCarrier ¶
type DocCarrier interface {
DocMeta() RouteDocMeta
}
DocCarrier marks a middleware or annotation value that carries documentation metadata.
Note: This interface intentionally does not embed adapter.MW. The adapter package defines a richer DocCarrier that also requires MW. This keeps adapter/registry free of dependencies on the routing API.
type RouteDTO ¶
type RouteDTO struct {
Doc *RouteDocMetaDTO `json:"doc,omitempty"`
MethodRaw string `json:"methodRaw,omitempty"`
Method string `json:"method,omitempty"`
PathRaw string `json:"pathRaw,omitempty"`
Path string `json:"path,omitempty"`
FullPath string `json:"fullPath,omitempty"`
ErrorMessages []string `json:"errors,omitempty"`
Seq uint64 `json:"seq"`
ScopeID uint32 `json:"scopeId"`
Internal bool `json:"internal,omitempty"`
IsAny bool `json:"isAny,omitempty"`
}
type RouteDocMeta ¶
type RouteDocMeta struct {
// OperationID overrides the auto-generated operationId.
// Last non-empty value in the scope chain wins.
OperationID string
// Summary is a short human-readable description of the operation.
// Last non-empty value in the scope chain wins.
Summary string
// Tags groups operations for tooling (Swagger UI, code generators, etc.).
// Tags accumulate across scopes: Group tags + With tags + route tags compose additively.
// Duplicates are removed preserving first-seen order.
Tags []string
// Deprecated marks the operation as deprecated in the generated spec.
// True if any scope or route annotation sets it to true.
Deprecated bool
}
RouteDocMeta holds OpenAPI documentation metadata associated with a route or scope.
Values are collected from DocCarrier middlewares and merged through the scope hierarchy using the rules in MergeDocMeta.
The zero value is valid and means "no annotation".
func MergeDocMeta ¶
func MergeDocMeta(a, b RouteDocMeta) RouteDocMeta
MergeDocMeta merges b into a and returns the result.
Merge rules (per spec):
- OperationID: last non-empty wins (most-specific scope/route overrides)
- Summary: last non-empty wins
- Tags: append + deduplicate, first-seen order preserved across scopes
- Deprecated: true if either a or b is true (monotonic — never goes back to false)
type RouteDocMetaDTO ¶
type RouteRecord ¶
type RouteRecord struct {
MethodRaw string
Method string
PathRaw string
Path string
FullPath string
Errors []error
// Doc holds the merged OpenAPI metadata for this route, accumulated from
// DocCarrier MWs passed to Use/Group/With and per-route Handle calls.
// The zero value means no annotation was provided.
Doc RouteDocMeta
Seq uint64
ScopeID ScopeID
// Internal marks routes mounted for infrastructure purposes (e.g. OpenAPI JSON and docs UIs)
// that should be excluded from generated specifications.
Internal bool
IsAny bool
}
RouteRecord describes a single attempted route registration.
FullPath is the resolved path after group prefixes are applied. Path is the normalized, route-local pattern. Doc carries the merged documentation metadata from scope + route annotations.
func (RouteRecord) MarshalJSON ¶
func (RouteRecord) MarshalJSON() ([]byte, error)
MarshalJSON is intentionally disabled. Use RegistrySnapshot.SnapshotDTO() for JSON serialization.
type ScopeDTO ¶
type ScopeDTO struct {
Kind string `json:"kind"`
PrefixRaw string `json:"prefixRaw,omitempty"`
Prefix string `json:"prefix,omitempty"`
FullPath string `json:"fullPath,omitempty"`
ErrorMessages []string `json:"errors,omitempty"`
Seq uint64 `json:"seq"`
ID uint32 `json:"id"`
ParentID uint32 `json:"parentId"`
}
type ScopeID ¶
type ScopeID uint32
ScopeID identifies a scope in a RegistrySnapshot.
ScopeID values are stable only within a single process lifetime.
const NoParentScopeID ScopeID = 0
NoParentScopeID is the sentinel ScopeID used to indicate that a scope has no parent.
In RegistrySnapshot, the root scope has ParentID == NoParentScopeID.
type ScopeRecord ¶
type ScopeRecord struct {
PrefixRaw string
Prefix string
FullPath string
Errors []error
Seq uint64
ID ScopeID
// ParentID points to the parent scope, or NoParentScopeID for the root scope.
ParentID ScopeID
Kind ScopeKind
}
ScopeRecord describes a router scope produced by Group/With (or the root).
FullPath is the resolved prefix at this scope (after parent prefixes). Prefix is the normalized prefix delta applied by a Group (empty for Root/With).
func (ScopeRecord) MarshalJSON ¶
func (ScopeRecord) MarshalJSON() ([]byte, error)
MarshalJSON is intentionally disabled. Use RegistrySnapshot.SnapshotDTO() for JSON serialization.
type Snapshot ¶
type Snapshot struct {
Scopes []ScopeRecord
Routes []RouteRecord
}
Snapshot is an immutable copy of the adapter's registration state at a point in time.
The slices are safe to iterate without holding any locks and will not change after being returned.
Note: This package contains read-only observation types produced by adapters. They are not designed to be constructed by users.
func (Snapshot) SnapshotDTO ¶
func (s Snapshot) SnapshotDTO() SnapshotDTO
SnapshotDTO returns a JSON-serializable DTO for the snapshot.
The DTO is intended to be stable and versioned via SnapshotDTOFormatVersion.
type SnapshotDTO ¶
type SnapshotDTO struct {
FormatVersion string `json:"formatVersion"`
Scopes []ScopeDTO `json:"scopes"`
Routes []RouteDTO `json:"routes"`
}
SnapshotDTO is a JSON-serializable representation of a RegistrySnapshot.
This is the supported serialization surface for tooling and external consumers. Do NOT json.Marshal RegistrySnapshot / RouteRecord / ScopeRecord directly; use SnapshotDTO().
Source Files