catalog

package
v1.0.0 Latest Latest
Warning

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

 Go to latest Published: Jun 24, 2026 License: MIT Imports: 21 Imported by: 0

Documentation

Index

Constants

This section is empty.

Variables

This section is empty.

Functions

func ApplyBuiltInResources 

func ApplyBuiltInResources(overrides []BuiltInResource) error

ApplyBuiltInResources merges override entries into the default built-in name map.

func ApplyFieldOverrides 

func ApplyFieldOverrides(overrides []FieldOverride) error

ApplyFieldOverrides mutates the default volatile and write-only field maps.

func ApplyRelationshipOverrides 

func ApplyRelationshipOverrides(r *Registry, overrides []RelationshipOverride) error

ApplyRelationshipOverrides merges override entries into the registry. Entries with Disabled=true are removed; otherwise the entry is registered or updated.

func BuildDeleteOperation 

func BuildDeleteOperation(actual manifest.RelationshipOperation, kind RelationshipKind) (manifest.RelationshipOperation, error)

BuildDeleteOperation creates a delete operation for an existing relationship.

func DisplayNameOf 

func DisplayNameOf(resource manifest.Resource, identity ResourceIdentity) string

DisplayNameOf returns a display name, falling back to the identifier.

func DownwardLevels 

func DownwardLevels(graph map[string][]DownwardChild, roots []string, maxDepth int) [][]DownwardChild

DownwardLevels returns the children found at each successive level below the supplied roots in the downward graph. The returned slice index corresponds to depth - 1 (index 0 is one level below the roots). Cycles are broken by tracking visited types. A non-positive maxDepth returns nil.

func IdentifierOf 

func IdentifierOf(resource manifest.Resource, identity ResourceIdentity) string

IdentifierOf returns the best identifier value for a resource using its identity model.

func InstallDefaultBuiltInResources 

func InstallDefaultBuiltInResources(specPath string) error

InstallDefaultBuiltInResources loads built-in resource overrides from the directory containing the spec and wires the matcher into the manifest package. It is safe to call when no override file exists.

func InstallDefaultFieldOverrides 

func InstallDefaultFieldOverrides(specPath string) error

InstallDefaultFieldOverrides loads field overrides from the directory containing the spec. It is safe to call when no override file exists.

func InstallDefaultRegistry 

func InstallDefaultRegistry(specPath string) error

InstallDefaultRegistry loads relationship overrides from the directory containing the spec and wires the default registry into the manifest package. It is safe to call when no override file exists.

func InstallManifestRegistry 

func InstallManifestRegistry()

InstallManifestRegistry wires the default registry into the manifest package so relationship normalization can resolve parameter types from the registry instead of a hardcoded switch.

func InvertDependencyGraph 

func InvertDependencyGraph(graph map[string][]string) map[string][]string

InvertDependencyGraph returns a new graph where each edge A -> B is reversed to B -> A. The input graph is interpreted as "child depends on parent".

func NameOf 

func NameOf(resource manifest.Resource, identity ResourceIdentity) string

NameOf returns the human-readable name for a resource.

func RelationshipTemplatePattern 

func RelationshipTemplatePattern(template string) (string, error)

func RenderPath 

func RenderPath(path string, params map[string]string) string

RenderPath substitutes path placeholders with their values.

func ValidateRelationshipOperations 

func ValidateRelationshipOperations(spec *Spec, ops []manifest.RelationshipOperation) error

func ValidateResources 

func ValidateResources(spec *Spec, resources []manifest.Resource, deleteMode bool) error

Types

type BuiltInResource 

type BuiltInResource struct {
	Type  string   `yaml:"type"`
	Names []string `yaml:"names"`
}

BuiltInResource describes a resource type and the names that should be treated as built-in and ignored during round-trip comparison.

func LoadBuiltInResources 

func LoadBuiltInResources(path string) ([]BuiltInResource, error)

LoadBuiltInResources reads built-in resource overrides from a YAML file.

type BuiltInResourcesFile 

type BuiltInResourcesFile struct {
	Resources []BuiltInResource `yaml:"resources"`
}

BuiltInResourcesFile is the top-level shape of a built-in resources YAML file.

type DownwardChild 

type DownwardChild struct {
	ChildType string
	Path      string // GET collection path, e.g. /admin/realms/{realm}/clients/{client-uuid}/roles
}

DownwardChild describes a structural child resource type and the spec path used to list instances of that child under a parent instance.

type FieldOverride 

type FieldOverride struct {
	Type            string   `yaml:"type"`
	AddVolatile     []string `yaml:"addVolatile,omitempty"`
	RemoveVolatile  []string `yaml:"removeVolatile,omitempty"`
	AddWriteOnly    []string `yaml:"addWriteOnly,omitempty"`
	RemoveWriteOnly []string `yaml:"removeWriteOnly,omitempty"`
}

FieldOverride describes per-resource-type additions or removals to the volatile and write-only field sets used for normalization and apply.

func LoadFieldOverrides 

func LoadFieldOverrides(path string) ([]FieldOverride, error)

LoadFieldOverrides reads field overrides from a YAML file.

type FieldOverridesFile 

type FieldOverridesFile struct {
	Overrides []FieldOverride `yaml:"overrides"`
}

FieldOverridesFile is the top-level shape of a field overrides YAML file.

type OperationContract 

type OperationContract struct {
	Path                  string
	Method                string
	Summary               string
	Deprecated            bool
	Parameters            []ParameterContract
	RequestBodyRequired   bool
	RequestBodySchema     *base.SchemaProxy
	RequestBodySchemaName string
	ResponseSchema        *base.SchemaProxy
	ResponseSchemaName    string
}

type OperationShape 

type OperationShape int

OperationShape controls which kind of endpoint the resolver should pick. 

const (
	OperationAny OperationShape = iota
	OperationCollection
	OperationSingle
)

type ParameterContract 

type ParameterContract struct {
	Name        string
	In          string
	Description string
	Required    bool
	SchemaName  string
	Schema      *base.SchemaProxy
}

type Registry 

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

Registry holds known relationship kinds indexed by name, read path, and write template.

func DefaultRegistry 

func DefaultRegistry() *Registry

DefaultRegistry returns the built-in relationship registry bundled with the CLI. It is safe for read-only use; callers that need overrides should build a registry with NewRegistry and merge overrides on top.

func NewRegistry 

func NewRegistry() *Registry

NewRegistry creates an empty relationship registry.

func (*Registry) ByName 

func (r *Registry) ByName(name string) (RelationshipKind, bool)

ByName returns a kind by its canonical name.

func (*Registry) ByPath 

func (r *Registry) ByPath(path string) (RelationshipKind, bool)

ByPath looks up a relationship kind by its read path.

func (*Registry) ByWriteTemplate 

func (r *Registry) ByWriteTemplate(template string) (RelationshipKind, bool)

ByWriteTemplate looks up a relationship kind by its write template.

func (*Registry) Kinds 

func (r *Registry) Kinds() []RelationshipKind

Kinds returns all registered relationship kinds sorted by name.

func (*Registry) ParamTypes 

func (r *Registry) ParamTypes(kindName string) map[string]string

ParamTypes returns the path-parameter to resource-type mapping for a kind.

func (*Registry) Register 

func (r *Registry) Register(kind RelationshipKind)

Register adds a relationship kind to the registry.

type RelationshipKind 

type RelationshipKind struct {
	Name               string
	ResourceA          string
	ResourceB          string
	Direction          string
	ReadMethod         string
	ReadPath           string
	WriteMethod        string
	WriteTemplate      string
	DeleteMethod       string
	DeleteTemplate     string
	DeleteItemParam    string
	DeletePayloadField string
	ItemParamName      string
	PayloadField       string
	BulkPayload        bool
	ParamTypes         map[string]string
	// contains filtered or unexported fields
}

RelationshipKind describes a family of Keycloak relationships discovered from the OpenAPI spec or supplied through an override file.

func (RelationshipKind) ParamTypesFor 

func (k RelationshipKind) ParamTypesFor(param string) string

ParamTypesFor returns the resource types corresponding to path parameters for this relationship kind.

func (RelationshipKind) Pattern 

func (k RelationshipKind) Pattern() RelationshipOperationPattern

Pattern returns the read-side pattern used by the relationship fetcher.

type RelationshipOperationPattern 

type RelationshipOperationPattern struct {
	Kind                 string
	Method               string
	Path                 string
	PathParams           []string
	ResourceA            string // First resource type in relationship
	ResourceB            string // Second resource type in relationship
	Direction            string // "one-way" or "bidirectional"
	RelationshipTemplate string // Template for the relationship operation
	RelationshipMethod   string // HTTP method for the relationship operation
	ItemParamName        string // Item field to extract for leaf path param; empty if none
	PayloadField         string // Item field to use as payload; empty means use the whole item
	BulkPayload          bool   // True if the entire collection is sent as one operation
}

DiscoverRelationshipOperations scans the spec for GET endpoints that return relationship/mapping collections and generates corresponding RelationshipOperation patterns. These patterns can be used to fetch and apply relationships.

func (RelationshipOperationPattern) ParentResourceTypes 

func (p RelationshipOperationPattern) ParentResourceTypes(placeholderMap map[string]string) ([]string, error)

ParentResourceTypes maps each path placeholder to its resource type using the placeholderToResourceType map. It returns an error if a placeholder is unknown.

type RelationshipOverride 

type RelationshipOverride struct {
	Name           string            `yaml:"name"`
	ResourceA      string            `yaml:"resourceA"`
	ResourceB      string            `yaml:"resourceB"`
	Direction      string            `yaml:"direction"`
	ReadPath       string            `yaml:"readPath"`
	WriteTemplate  string            `yaml:"writeTemplate"`
	WriteMethod    string            `yaml:"writeMethod"`
	DeleteTemplate string            `yaml:"deleteTemplate,omitempty"`
	DeleteMethod   string            `yaml:"deleteMethod,omitempty"`
	ItemParamName  string            `yaml:"itemParamName,omitempty"`
	PayloadField   string            `yaml:"payloadField,omitempty"`
	BulkPayload    bool              `yaml:"bulkPayload,omitempty"`
	ParamTypes     map[string]string `yaml:"paramTypes,omitempty"`
	Disabled       bool              `yaml:"disabled,omitempty"`
}

RelationshipOverride describes a single override entry in a relationship overrides YAML file.

func LoadRelationshipOverrides 

func LoadRelationshipOverrides(path string) ([]RelationshipOverride, error)

LoadRelationshipOverrides reads relationship overrides from a YAML file.

type RelationshipOverridesFile 

type RelationshipOverridesFile struct {
	Overrides []RelationshipOverride `yaml:"overrides"`
}

RelationshipOverridesFile is the top-level shape of an override file.

type RelationshipTemplate 

type RelationshipTemplate struct {
	Template       string
	Method         string
	Summary        string
	Body           map[string]interface{}
	RequiresBody   bool
	PathParamNames []string
}

func CollectRelationshipTemplates 

func CollectRelationshipTemplates(spec *Spec) ([]RelationshipTemplate, error)

type RequestValidation 

type RequestValidation struct {
	PathParams   map[string]string
	QueryParams  map[string]string
	HeaderParams map[string]string
	CookieParams map[string]string
	Body         interface{}
}

type Resolver 

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

Resolver resolves spec operations and path parameters for resources.

func (*Resolver) ParentReferenceFieldNames 

func (r *Resolver) ParentReferenceFieldNames(resourceType string, op OperationContract) []string

ParentReferenceFieldNames returns the data field names that identify parent resources for a nested operation path. These fields are needed to render path parameters but should not be sent in the request body.

func (*Resolver) ParentReferenceFieldTypes 

func (r *Resolver) ParentReferenceFieldTypes(resourceType string, op OperationContract) map[string]string

ParentReferenceFieldTypes returns the data field names that identify parent resources for a nested operation path, mapped to the parent resource type. These fields are needed to render path parameters but should not be sent in the request body.

func (*Resolver) ParentReferenceFields 

func (r *Resolver) ParentReferenceFields(childPath, parentType string, parent manifest.Resource) map[string]string

ParentReferenceFields returns child data field names and values that identify the parent resource for a nested operation path. When a child is fetched from a path such as /admin/realms/{realm}/client-scopes/{client-scope-id}/protocol-mappers/models, the returned map contains {"clientScopeId": "<parent-scope-id>"} so the child can be applied independently as a top-level resource.

func (*Resolver) PathParams 

func (r *Resolver) PathParams(resource manifest.Resource, op OperationContract) (map[string]string, error)

PathParams extracts path parameters for a resource given an operation contract.

func (*Resolver) ResolveResourceOperation 

func (r *Resolver) ResolveResourceOperation(resourceType, parentType, method string, shape OperationShape) (OperationContract, error)

ResolveResourceOperation finds the best operation for a resource type and method. parentType disambiguates multi-location types (e.g. protocolmapper under clientscope vs client) by matching the parent segment in the path.

func (*Resolver) ResolveResourcePath 

func (r *Resolver) ResolveResourcePath(resource manifest.Resource, method string, shape OperationShape) (string, OperationContract, map[string]string, error)

ResolveResourcePath resolves the operation for the resource and renders the path by substituting path parameters from resource.Data and resource.Realm.

type ResourceContract 

type ResourceContract struct {
	Type          string
	SchemaName    string
	Schema        *base.SchemaProxy
	Operations    map[string]OperationContract   // highest-priority endpoint per method
	AllOperations map[string][]OperationContract // all endpoints per method for multi-location types
}

type ResourceIdentity 

type ResourceIdentity struct {
	Type             string
	IDParam          string
	PrimaryKey       string
	IdentifierFields []string
	DisplayField     string
}

ResourceIdentity describes how a resource type is identified in manifests and URLs.

type Spec 

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

func NewSpec 

func NewSpec(path string) (*Spec, error)

func NewSpecFromBytes 

func NewSpecFromBytes(data []byte) (*Spec, error)

func WrapSpec 

func WrapSpec(loaded *internal.Spec) *Spec

WrapSpec exposes an already-loaded internal spec for tests that embed a fixture.

func (*Spec) BuildDependencyGraph 

func (s *Spec) BuildDependencyGraph() (map[string][]string, error)

BuildDependencyGraph constructs a dependency graph from the spec contracts. An edge from A to B means "A depends on B" (B must be created before A).

func (*Spec) BuildDownwardGraph 

func (s *Spec) BuildDownwardGraph() (map[string][]DownwardChild, error)

BuildDownwardGraph returns a map from parent resource type to the resource types that can be created directly underneath it in the Keycloak object hierarchy. Edges represent structural containment discovered from the spec POST paths. Relationship/mapping endpoints are excluded so the graph only describes object ownership, not associations.

func (*Spec) DependencyPriorityMap 

func (s *Spec) DependencyPriorityMap() (map[string]int, error)

DependencyPriorityMap computes a topological sort of the dependency graph and returns a map from resource type to priority (lower = created first).

func (*Spec) DiscoverRelationshipPatterns 

func (s *Spec) DiscoverRelationshipPatterns() ([]RelationshipOperationPattern, error)

DiscoverRelationshipPatterns scans the spec for relationship endpoints.

func (*Spec) ForEachOperation 

func (s *Spec) ForEachOperation(visitor func(path, method string, operation *v3.Operation, item *v3.PathItem))

func (*Spec) GetSchemas 

func (s *Spec) GetSchemas() (map[string]*base.SchemaProxy, error)

func (*Spec) Operation 

func (s *Spec) Operation(path, method string) (*v3.Operation, *v3.PathItem, error)

func (*Spec) OperationContract 

func (s *Spec) OperationContract(path, method string) (OperationContract, error)

func (*Spec) PathParameters 

func (s *Spec) PathParameters(path, method string) ([]string, error)

func (*Spec) PlaceholderToResourceType 

func (s *Spec) PlaceholderToResourceType() (map[string]string, error)

PlaceholderToResourceType maps path-parameter placeholders to their resource types.

func (*Spec) Resolver 

func (s *Spec) Resolver() *Resolver

Resolver returns a new Resolver backed by the spec's resource contracts.

func (*Spec) ResourceContracts 

func (s *Spec) ResourceContracts() (map[string]ResourceContract, error)

func (*Spec) ResourceIdentities 

func (s *Spec) ResourceIdentities() (map[string]ResourceIdentity, error)

ResourceIdentities derives identity metadata for every discovered resource type.

func (*Spec) ValidateManifest 

func (s *Spec) ValidateManifest(resources []manifest.Resource, relationships []manifest.RelationshipOperation, deleteMode bool) error

ValidateManifest validates both resources and relationship operations in a single call. It returns a joined error containing all validation failures.

func (*Spec) ValidateOperationRequest 

func (s *Spec) ValidateOperationRequest(path, method string, input RequestValidation) error

func (*Spec) ValidateOperationResponse 

func (s *Spec) ValidateOperationResponse(path, method string, body interface{}) error

func (*Spec) ValidateResource 

func (s *Spec) ValidateResource(resource manifest.Resource, method string) error

func (*Spec) ValidateSchema 

func (s *Spec) ValidateSchema(name string, value interface{}) error

func (*Spec) VolatileFields 

func (s *Spec) VolatileFields(resourceType string) ([]string, error)

VolatileFields returns server-managed fields that should be stripped before applying or comparing.

func (*Spec) WriteOnlyFields 

func (s *Spec) WriteOnlyFields(resourceType string) ([]string, error)

WriteOnlyFields returns fields that should never be exposed in fetched output.

Source Files

View all Source files

Directories

Path Synopsis
Package internal is an implementation detail of the catalog module.
 Package internal is an implementation detail of the catalog module.

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.