routing

package
v0.140.4 Latest Latest
Warning

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

 Go to latest Published: Oct 11, 2026 License: MIT Imports: 11 Imported by: 1

Documentation

Index

Constants

View Source 
const (
	RouteDomainSystem          = "system"
	RouteDomainInternalOps     = "internal_ops"
	RouteDomainAdminUI         = "admin_ui"
	RouteDomainAdminAPI        = "admin_api"
	RouteDomainProtectedAppUI  = "protected_app_ui"
	RouteDomainProtectedAppAPI = "protected_app_api"
	RouteDomainPublicAPI       = "public_api"
	RouteDomainPublicSite      = "public_site"
	RouteDomainStatic          = "static"
)
View Source 
const (
	FallbackModeDisabled          = "disabled"
	FallbackModePublicContentOnly = "public_content_only"
	FallbackModeExplicitPathsOnly = "explicit_paths_only"
)
View Source 
const (
	ManifestMethodUnknown = "UNKNOWN"
	ManifestDiffAdded     = "added"
	ManifestDiffRemoved   = "removed"
	ManifestDiffChanged   = "changed"
)
View Source 
const (
	SurfaceUI              = "ui"
	SurfaceAPI             = "api"
	SurfaceProtectedAppUI  = "protected_app_ui"
	SurfaceProtectedAppAPI = "protected_app_api"
	SurfacePublicAPI       = "public_api"
	SurfacePublicSite      = "public_site"
	SurfaceSystem          = "system"
	SurfaceInternalOps     = "internal_ops"
	SurfaceStatic          = "static"
)
View Source 
const (
	DefaultAdminAPIPrefix      = "api"
	DefaultPublicAPIPrefix     = "api"
	DefaultPublicAPIVersion    = "v1"
	DefaultProtectedAppRoot    = "/app"
	DefaultProtectedAppAPIRoot = "/app/api"
	SlugPattern                = "^[a-z][a-z0-9_-]{1,62}$"
)
View Source 
const (
	ConflictKindPathConflict       = "path_conflict"
	ConflictKindRouteNameConflict  = "route_name_conflict"
	ConflictKindOwnershipViolation = "ownership_violation"
	ConflictKindSlugViolation      = "slug_violation"
)

Variables

This section is empty.

Functions

func AdminAPIGroupPath 

func AdminAPIGroupPath(roots RootsConfig) string

func BuildAdapterWarnings 

func BuildAdapterWarnings(urls URLKitAdapter, router RouterAdapter) []string

func DefaultRouteDomainForSurface added in v0.36.0 

func DefaultRouteDomainForSurface(surface string) string

func DefaultRouteSurfaceForDomain added in v0.36.0 

func DefaultRouteSurfaceForDomain(domain string) string

func DefaultUIGroupPath 

func DefaultUIGroupPath() string

func FormatStartupReport 

func FormatStartupReport(report StartupReport) string

func IsReservedSlug 

func IsReservedSlug(slug string) bool

func JoinAbsolutePath 

func JoinAbsolutePath(base string, segments ...string) string

func NormalizeMountName added in v0.120.0 

func NormalizeMountName(value string) string

NormalizeMountName returns the canonical identifier used by module contracts, host configuration, routing contexts, and runtime router lookup.

func NormalizeRelativePath 

func NormalizeRelativePath(value string) string

func NormalizeRouteDomain added in v0.36.0 

func NormalizeRouteDomain(domain string) string

func NormalizeRouteNamePrefix 

func NormalizeRouteNamePrefix(prefix, slug string) string

func NormalizeRouteSurface added in v0.36.0 

func NormalizeRouteSurface(surface string) string

func OwnsRouteKey 

func OwnsRouteKey(slug, routeKey string) bool

func OwnsRouteName 

func OwnsRouteName(prefix, slug, routeName string) bool

func ProtectedAppAPIGroupPath added in v0.58.0 

func ProtectedAppAPIGroupPath(roots RootsConfig) string

func ProtectedAppUIGroupPath added in v0.58.0 

func ProtectedAppUIGroupPath() string

func PublicAPIGroupPath 

func PublicAPIGroupPath(roots RootsConfig) string

func ReservedSlugs 

func ReservedSlugs() []string

func RouteDomains added in v0.36.0 

func RouteDomains() []string

func RouteKeyOwnershipPrefix 

func RouteKeyOwnershipPrefix(slug string) string

func RouteNameOwnershipPrefix 

func RouteNameOwnershipPrefix(prefix, slug string) string

func ValidateSlug 

func ValidateSlug(slug string) error

Types

type Config 

type Config struct {
	Enabled                bool                    `json:"enabled"`
	EnforceRouteNamePolicy bool                    `json:"enforce_route_name_policy"`
	EnforceSlugPolicy      bool                    `json:"enforce_slug_policy"`
	ConflictPolicy         ConflictPolicy          `json:"conflict_policy"`
	ProtectedAppEnabled    bool                    `json:"protected_app_enabled,omitempty"`
	Roots                  RootsConfig             `json:"roots"`
	Modules                map[string]ModuleConfig `json:"modules"`
	Manifest               ManifestConfig          `json:"manifest"`
	ReservedPrefixes       []string                `json:"reserved_prefixes,omitempty"`
}

func DefaultConfig 

func DefaultConfig() Config

func NormalizeConfig 

func NormalizeConfig(cfg Config, input RootDerivationInput) Config

type Conflict 

type Conflict struct {
	Kind      string            `json:"kind"`
	Module    string            `json:"module,omitempty"`
	Method    string            `json:"method,omitempty"`
	Path      string            `json:"path,omitempty"`
	RouteName string            `json:"route_name,omitempty"`
	Existing  map[string]string `json:"existing,omitempty"`
	Incoming  map[string]string `json:"incoming,omitempty"`
	Message   string            `json:"message,omitempty"`
}

type ConflictError 

type ConflictError struct {
	Conflicts []Conflict `json:"conflicts"`
}

func (*ConflictError) Error 

func (e *ConflictError) Error() string

type ConflictPolicy 

type ConflictPolicy string
const (
	ConflictPolicyError   ConflictPolicy = "error"
	ConflictPolicyWarn    ConflictPolicy = "warn"
	ConflictPolicyReplace ConflictPolicy = "replace"
)

type FallbackDiffEntry added in v0.36.0 

type FallbackDiffEntry struct {
	Kind   string         `json:"kind"`
	Key    string         `json:"key"`
	Before *FallbackEntry `json:"before,omitempty"`
	After  *FallbackEntry `json:"after,omitempty"`
}

type FallbackEntry added in v0.36.0 

type FallbackEntry struct {
	Owner               string   `json:"owner"`
	Surface             string   `json:"surface"`
	Domain              string   `json:"domain,omitempty"`
	BasePath            string   `json:"base_path,omitempty"`
	Mode                string   `json:"mode"`
	AllowRoot           bool     `json:"allow_root"`
	AllowedMethods      []string `json:"allowed_methods,omitempty"`
	AllowedExactPaths   []string `json:"allowed_exact_paths,omitempty"`
	AllowedPathPrefixes []string `json:"allowed_path_prefixes,omitempty"`
	ReservedPrefixes    []string `json:"reserved_prefixes,omitempty"`
}

func NormalizeFallbackEntry added in v0.36.0 

func NormalizeFallbackEntry(entry FallbackEntry) FallbackEntry

type Manifest 

type Manifest struct {
	Entries   []ManifestEntry `json:"entries,omitempty"`
	Fallbacks []FallbackEntry `json:"fallbacks,omitempty"`
}

func NormalizeManifest 

func NormalizeManifest(manifest Manifest) Manifest

func (Manifest) SortedEntries 

func (m Manifest) SortedEntries() []ManifestEntry

type ManifestConfig 

type ManifestConfig struct {
	Enabled             bool `json:"enabled"`
	IncludeHostRoutes   bool `json:"include_host_routes"`
	IncludeModuleRoutes bool `json:"include_module_routes"`
	IncludeFallbacks    bool `json:"include_fallbacks"`
}

type ManifestDiff 

type ManifestDiff struct {
	Added           []ManifestDiffEntry `json:"added,omitempty"`
	Removed         []ManifestDiffEntry `json:"removed,omitempty"`
	Changed         []ManifestDiffEntry `json:"changed,omitempty"`
	FallbackAdded   []FallbackDiffEntry `json:"fallback_added,omitempty"`
	FallbackRemoved []FallbackDiffEntry `json:"fallback_removed,omitempty"`
	FallbackChanged []FallbackDiffEntry `json:"fallback_changed,omitempty"`
}

func DiffManifests 

func DiffManifests(before, after Manifest) ManifestDiff

func (ManifestDiff) HasChanges 

func (m ManifestDiff) HasChanges() bool

type ManifestDiffEntry 

type ManifestDiffEntry struct {
	Kind   string         `json:"kind"`
	Key    string         `json:"key"`
	Before *ManifestEntry `json:"before,omitempty"`
	After  *ManifestEntry `json:"after,omitempty"`
}

type ManifestEntry 

type ManifestEntry struct {
	Owner     string `json:"owner"`
	Surface   string `json:"surface"`
	Domain    string `json:"domain,omitempty"`
	RouteKey  string `json:"route_key"`
	RouteName string `json:"route_name"`
	Method    string `json:"method"`
	Path      string `json:"path"`
	GroupPath string `json:"group_path"`
}

type ModuleConfig 

type ModuleConfig struct {
	Mount  ModuleMountOverride           `json:"mount"`
	Mounts map[string]NamedMountOverride `json:"mounts,omitempty"`
}

type ModuleContext 

type ModuleContext struct {
	Contract        ModuleContract               `json:"contract"`
	Resolved        ResolvedModule               `json:"resolved"`
	UIRoutes        map[string]string            `json:"ui_routes,omitempty"`
	APIRoutes       map[string]string            `json:"api_routes,omitempty"`
	PublicAPIRoutes map[string]string            `json:"public_api_routes,omitempty"`
	MountRoutes     map[string]map[string]string `json:"mount_routes,omitempty"`
}

func BuildModuleContext 

func BuildModuleContext(contract ModuleContract, resolved ResolvedModule) ModuleContext

func (ModuleContext) GroupPath 

func (c ModuleContext) GroupPath(surface string) string

func (ModuleContext) Mount added in v0.119.0 

func (c ModuleContext) Mount(name string) (ResolvedMount, bool)

func (ModuleContext) MountRoutePath added in v0.119.0 

func (c ModuleContext) MountRoutePath(name, routeKey string) string

func (ModuleContext) RoutePath 

func (c ModuleContext) RoutePath(surface, routeKey string) string

type ModuleContract 

type ModuleContract struct {
	Slug            string            `json:"slug"`
	UIRoutes        map[string]string `json:"ui_routes,omitempty"`
	APIRoutes       map[string]string `json:"api_routes,omitempty"`
	PublicAPIRoutes map[string]string `json:"public_api_routes,omitempty"`
	// Typed declarations are preferred for new modules because they enable
	// exact method/path conflict detection and runtime reconciliation. The
	// path-only fields remain source compatible and normalize to UNKNOWN.
	UIRouteDeclarations        map[string]RouteDeclaration `json:"ui_route_declarations,omitempty"`
	APIRouteDeclarations       map[string]RouteDeclaration `json:"api_route_declarations,omitempty"`
	PublicAPIRouteDeclarations map[string]RouteDeclaration `json:"public_api_route_declarations,omitempty"`
	RouteNamePrefix            string                      `json:"route_name_prefix,omitempty"`
	// Mounts declares additional named route sets. The host must authorize each
	// name with a surface and absolute base in Config.Modules[slug].Mounts.
	Mounts map[string]NamedMountContract `json:"mounts,omitempty"`
}

func NormalizeModuleContract 

func NormalizeModuleContract(contract ModuleContract) ModuleContract

type ModuleMountOverride 

type ModuleMountOverride struct {
	UIBase        string `json:"ui_base,omitempty"`
	APIBase       string `json:"api_base,omitempty"`
	PublicAPIBase string `json:"public_api_base,omitempty"`
}

func NormalizeMountOverride 

func NormalizeMountOverride(cfg ModuleMountOverride) ModuleMountOverride

type NamedMountContract added in v0.119.0 

type NamedMountContract struct {
	Routes            map[string]string           `json:"routes,omitempty"`
	RouteDeclarations map[string]RouteDeclaration `json:"route_declarations,omitempty"`
}

type NamedMountOverride added in v0.119.0 

type NamedMountOverride struct {
	Surface   string `json:"surface"`
	Base      string `json:"base"`
	GroupPath string `json:"group_path,omitempty"`
}

type Planner 

type Planner interface {
	RegisterModule(contract ModuleContract) error
	RegisterHostRoutes(entries ...ManifestEntry) error
	RegisterFallback(entry FallbackEntry) error
	ResolvedModule(slug string) (ResolvedModule, bool)
	Validate() error
	Manifest() Manifest
	Report() StartupReport
}

func NewPlanner 

func NewPlanner(cfg Config, urls URLKitAdapter) (Planner, error)

type Registry 

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

func NewRegistry 

func NewRegistry() *Registry

func (*Registry) Conflicts 

func (r *Registry) Conflicts() []Conflict

func (*Registry) TrackManifestEntry 

func (r *Registry) TrackManifestEntry(entry ManifestEntry) []Conflict

func (*Registry) TrackRouterRoute 

func (r *Registry) TrackRouterRoute(owner, module string, route router.RouteDefinition) []Conflict

type ResolvedModule 

type ResolvedModule struct {
	Slug               string                   `json:"slug"`
	UIMountBase        string                   `json:"ui_mount_base,omitempty"`
	APIMountBase       string                   `json:"api_mount_base,omitempty"`
	PublicAPIMountBase string                   `json:"public_api_mount_base,omitempty"`
	UIGroupPath        string                   `json:"ui_group_path,omitempty"`
	APIGroupPath       string                   `json:"api_group_path,omitempty"`
	PublicAPIGroupPath string                   `json:"public_api_group_path,omitempty"`
	Mounts             map[string]ResolvedMount `json:"mounts,omitempty"`
}

type ResolvedMount added in v0.119.0 

type ResolvedMount struct {
	Name      string `json:"name"`
	Surface   string `json:"surface"`
	Base      string `json:"base"`
	GroupPath string `json:"group_path"`
}

type RootDerivationInput 

type RootDerivationInput struct {
	BasePath            string    `json:"base_path"`
	URLs                URLConfig `json:"urls"`
	ProtectedAppEnabled bool      `json:"protected_app_enabled,omitempty"`
}

type RootsConfig 

type RootsConfig struct {
	AdminRoot           string `json:"admin_root,omitempty"`
	APIRoot             string `json:"api_root,omitempty"`
	PublicAPIRoot       string `json:"public_api_root,omitempty"`
	ProtectedAppRoot    string `json:"protected_app_root,omitempty"`
	ProtectedAppAPIRoot string `json:"protected_app_api_root,omitempty"`
}

func DeriveDefaultRoots 

func DeriveDefaultRoots(input RootDerivationInput) RootsConfig

func MergeRoots 

func MergeRoots(defaults, overrides RootsConfig) RootsConfig

func NormalizeRoots 

func NormalizeRoots(cfg RootsConfig) RootsConfig

type RouteDeclaration added in v0.120.0 

type RouteDeclaration struct {
	Method router.HTTPMethod `json:"method"`
	Path   string            `json:"path"`
}

type RouteSummary 

type RouteSummary struct {
	TotalRoutes    int            `json:"total_routes"`
	HostRoutes     int            `json:"host_routes"`
	ModuleRoutes   int            `json:"module_routes"`
	FallbackRoutes int            `json:"fallback_routes"`
	Modules        []string       `json:"modules,omitempty"`
	Domains        []string       `json:"domains,omitempty"`
	DomainCounts   map[string]int `json:"domain_counts,omitempty"`
}

type RouterAdapter 

type RouterAdapter interface {
	Routes() []router.RouteDefinition
	ValidateRoutes() []error
}

type RouterCapabilities 

type RouterCapabilities struct {
	NativeRouteNamePolicy bool `json:"native_route_name_policy"`
	NativeOwnershipChecks bool `json:"native_ownership_checks"`
	NativeManifest        bool `json:"native_manifest"`
}

func DetectRouterCapabilities 

func DetectRouterCapabilities(adapter RouterAdapter) RouterCapabilities

type RouterCapabilityProvider 

type RouterCapabilityProvider interface {
	RoutingRouterCapabilities() RouterCapabilities
}

type RuntimeReport added in v0.119.0 

type RuntimeReport struct {
	Available          bool                     `json:"available"`
	Reconciled         bool                     `json:"reconciled"`
	State              router.RegistrationState `json:"state,omitempty"`
	Revision           uint64                   `json:"revision,omitempty"`
	DeclaredRoutes     int                      `json:"declared_routes"`
	MountedRoutes      int                      `json:"mounted_routes"`
	MissingRoutes      []RuntimeRouteIssue      `json:"missing_routes,omitempty"`
	UnverifiableRoutes []RuntimeRouteIssue      `json:"unverifiable_routes,omitempty"`
	Shadows            []router.RouteShadow     `json:"shadows,omitempty"`
}

func BuildRuntimeReport added in v0.119.0 

func BuildRuntimeReport(manifest Manifest, snapshot router.RegistrationSnapshot) RuntimeReport

type RuntimeRouteIssue added in v0.119.0 

type RuntimeRouteIssue struct {
	Owner     string `json:"owner,omitempty"`
	RouteName string `json:"route_name,omitempty"`
	Method    string `json:"method"`
	Path      string `json:"path"`
	Reason    string `json:"reason"`
}

type StartupReport 

type StartupReport struct {
	EffectiveRoots RootsConfig      `json:"effective_roots"`
	Modules        []ResolvedModule `json:"modules,omitempty"`
	RouteSummary   RouteSummary     `json:"route_summary"`
	Fallbacks      []FallbackEntry  `json:"fallbacks,omitempty"`
	Conflicts      []Conflict       `json:"conflicts,omitempty"`
	Warnings       []string         `json:"warnings,omitempty"`
	Runtime        *RuntimeReport   `json:"runtime,omitempty"`
}

func BuildStartupReport 

func BuildStartupReport(roots RootsConfig, modules []ResolvedModule, manifest Manifest, conflicts []Conflict, warnings []string) StartupReport

func CloneStartupReport added in v0.120.0 

func CloneStartupReport(report StartupReport) StartupReport

CloneStartupReport returns an immutable-by-convention copy suitable for concurrent caches and diagnostics callers.

type URLConfig 

type URLConfig struct {
	Admin  URLNamespaceConfig `json:"admin"`
	Public URLNamespaceConfig `json:"public"`
}

type URLKitAdapter 

type URLKitAdapter interface {
	EnsureGroup(path string) error
	AddRoutes(path string, routes map[string]string) error
	RoutePath(group, route string) (string, error)
	RouteTemplate(group, route string) (string, error)
}

type URLKitCapabilities 

type URLKitCapabilities struct {
	NativeStrictMutations bool `json:"native_strict_mutations"`
	NativeManifest        bool `json:"native_manifest"`
}

func DetectURLKitCapabilities 

func DetectURLKitCapabilities(adapter URLKitAdapter) URLKitCapabilities

type URLKitCapabilityProvider 

type URLKitCapabilityProvider interface {
	RoutingURLKitCapabilities() URLKitCapabilities
}

type URLNamespaceConfig 

type URLNamespaceConfig struct {
	BasePath   string `json:"base_path"`
	APIPrefix  string `json:"api_prefix"`
	APIVersion string `json:"api_version"`
}

type Validator 

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

func NewValidator 

func NewValidator(roots RootsConfig) *Validator

func (*Validator) Conflicts 

func (v *Validator) Conflicts() []Conflict

func (*Validator) PreflightRouter 

func (v *Validator) PreflightRouter(owner, module string, routes []router.RouteDefinition) error

func (*Validator) PreflightURLKit 

func (v *Validator) PreflightURLKit(entries []ManifestEntry, urls URLKitAdapter) error

func (*Validator) ReconcileRouter 

func (v *Validator) ReconcileRouter(manifest Manifest, adapter RouterAdapter) error

func (*Validator) ValidateFallbacks added in v0.36.0 

func (v *Validator) ValidateFallbacks(entries []ManifestEntry, fallbacks []FallbackEntry) error

func (*Validator) ValidateHostRoutes added in v0.36.0 

func (v *Validator) ValidateHostRoutes(entries []ManifestEntry) error

func (*Validator) ValidateModule 

func (v *Validator) ValidateModule(contract ModuleContract, resolved ResolvedModule, entries []ManifestEntry) error

Source Files

View all Source files

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.