reconcile

type BillingFeatureRef ¶ added in v0.114.0

type BillingFeatureRef struct {
	Name string `yaml:"name"`
}

BillingFeatureRef names a feature attached to a product. The feature is created if it does not exist yet.

type BillingPlanAPI ¶ added in v0.114.0

type BillingPlanAPI interface {
	ListAllPlans(context.Context, *connect.Request[frontierv1beta1.ListAllPlansRequest]) (*connect.Response[frontierv1beta1.ListAllPlansResponse], error)
	CreatePlan(context.Context, *connect.Request[frontierv1beta1.CreatePlanRequest]) (*connect.Response[frontierv1beta1.CreatePlanResponse], error)
	UpdatePlan(context.Context, *connect.Request[frontierv1beta1.UpdatePlanRequest]) (*connect.Response[frontierv1beta1.UpdatePlanResponse], error)
}

BillingPlanAPI is the API subset the billing plan reconciler needs. Plans live on the AdminService: reads come from ListAllPlans, which returns every plan (active and inactive) with its products, and writes go through CreatePlan and UpdatePlan. CreatePlan associates the referenced products by name; UpdatePlan changes only a plan's own fields (title, description, credits, trial days, state, metadata).

type BillingPlanProductRef ¶ added in v0.114.0

type BillingPlanProductRef struct {
	Name string `yaml:"name"`
}

BillingPlanProductRef names a product that belongs to the plan. The product is managed by the BillingProduct kind; the plan only references it by name.

type BillingPlanReconciler ¶ added in v0.114.0

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

BillingPlanReconciler makes billing plans match the desired spec. The plan name is the identity; title, description, on_start_credits, trial_days, and state are converged through UpdatePlan. Interval and the product set are create-only, so a change to either fails the plan. A plan missing from the file fails the plan, because there is no API to remove one.

func NewBillingPlanReconciler(client BillingPlanAPI, header string) *BillingPlanReconciler

func (r *BillingPlanReconciler) Export(ctx context.Context) (any, error)

func (r *BillingPlanReconciler) Kind() string

func (r *BillingPlanReconciler) Reconcile(ctx context.Context, spec []byte, dryRun bool) (Report, error)

func (r *BillingPlanReconciler) Validate(spec []byte) error

type BillingPlanSpec ¶ added in v0.114.0

type BillingPlanSpec struct {
	Name           string                  `yaml:"name"`
	Title          string                  `yaml:"title,omitempty"`
	Description    string                  `yaml:"description,omitempty"`
	Interval       string                  `yaml:"interval,omitempty"`
	OnStartCredits int64                   `yaml:"on_start_credits,omitempty"`
	TrialDays      int64                   `yaml:"trial_days,omitempty"`
	State          string                  `yaml:"state,omitempty"`
	Products       []BillingPlanProductRef `yaml:"products,omitempty"`
	Delete         bool                    `yaml:"delete,omitempty"`
}

BillingPlanSpec is one desired plan. The name is the identity and never changes. A plan groups products (referenced by name; the products themselves are managed by the BillingProduct kind). Title, description, on_start_credits, trial_days, and state are converged through UpdatePlan. Interval and the product set are create-only: UpdatePlan cannot change them, so a change to either fails the plan. A plan cannot be deleted through the API, so the delete flag is rejected. Metadata is out of scope: it is not stated in the file, not diffed, and not exported, but it is preserved on update (see the reconciler).

type BillingPriceSpec ¶ added in v0.114.0

type BillingPriceSpec struct {
	Name             string `yaml:"name"`
	Amount           int64  `yaml:"amount"`
	Currency         string `yaml:"currency,omitempty"`
	Interval         string `yaml:"interval,omitempty"`
	UsageType        string `yaml:"usage_type,omitempty"`
	BillingScheme    string `yaml:"billing_scheme,omitempty"`
	MeteredAggregate string `yaml:"metered_aggregate,omitempty"`
}

BillingPriceSpec is one desired price of a product. The name is the identity within the product. Amount and the other pricing fields are fixed once a price exists, so a change to them must be a new price under a new name.

type BillingProductAPI ¶ added in v0.114.0

type BillingProductAPI interface {
	ListProducts(context.Context, *connect.Request[frontierv1beta1.ListProductsRequest]) (*connect.Response[frontierv1beta1.ListProductsResponse], error)
	CreateProduct(context.Context, *connect.Request[frontierv1beta1.CreateProductRequest]) (*connect.Response[frontierv1beta1.CreateProductResponse], error)
	UpdateProduct(context.Context, *connect.Request[frontierv1beta1.UpdateProductRequest]) (*connect.Response[frontierv1beta1.UpdateProductResponse], error)
}

BillingProductAPI is the API subset the billing product reconciler needs. Billing products live on the FrontierService. Reads come from ListProducts (which returns each product with its prices and features), and writes go through CreateProduct and UpdateProduct. UpdateProduct converges a product's prices, so the reconciler sends the whole desired product and lets the server add, keep, or deactivate each price.

type BillingProductConfig ¶ added in v0.114.0

type BillingProductConfig struct {
	CreditAmount int64 `yaml:"credit_amount,omitempty"`
	SeatLimit    int64 `yaml:"seat_limit,omitempty"`
	MinQuantity  int64 `yaml:"min_quantity,omitempty"`
	MaxQuantity  int64 `yaml:"max_quantity,omitempty"`
}

BillingProductConfig is the behavior config of a product.

type BillingProductReconciler ¶ added in v0.114.0

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

BillingProductReconciler makes billing products match the desired spec. The product name is the identity; title, description, behavior, config, prices, and features are the managed fields. A product missing from the file fails the plan, because there is no API to remove a product.

func NewBillingProductReconciler(client BillingProductAPI, header string) *BillingProductReconciler

func (r *BillingProductReconciler) Export(ctx context.Context) (any, error)

func (r *BillingProductReconciler) Kind() string

func (r *BillingProductReconciler) Reconcile(ctx context.Context, spec []byte, dryRun bool) (Report, error)

func (r *BillingProductReconciler) Validate(spec []byte) error

type BillingProductSpec ¶ added in v0.114.0

type BillingProductSpec struct {
	Name        string               `yaml:"name"`
	Title       string               `yaml:"title,omitempty"`
	Description string               `yaml:"description,omitempty"`
	Behavior    string               `yaml:"behavior,omitempty"`
	Config      BillingProductConfig `yaml:"config,omitempty"`
	Prices      []BillingPriceSpec   `yaml:"prices,omitempty"`
	Features    []BillingFeatureRef  `yaml:"features,omitempty"`
	Delete      bool                 `yaml:"delete,omitempty"`
}

BillingProductSpec is one desired product. The name is the identity and never changes. A product is managed in full: its title, description, behavior, config, prices, and features all state the whole desired value. Prices are keyed by name within the product and converge on the server (a new name is added, an existing name keeps its immutable fields, and an active price the list no longer names is deactivated). A product cannot be deleted through the API, so the delete flag is rejected.

type MetaSchemaAPI ¶ added in v0.115.0

type MetaSchemaAPI interface {
	ListMetaSchemas(context.Context, *connect.Request[frontierv1beta1.ListMetaSchemasRequest]) (*connect.Response[frontierv1beta1.ListMetaSchemasResponse], error)
	CreateMetaSchema(context.Context, *connect.Request[frontierv1beta1.CreateMetaSchemaRequest]) (*connect.Response[frontierv1beta1.CreateMetaSchemaResponse], error)
	UpdateMetaSchema(context.Context, *connect.Request[frontierv1beta1.UpdateMetaSchemaRequest]) (*connect.Response[frontierv1beta1.UpdateMetaSchemaResponse], error)
}

MetaSchemaAPI is the API subset the metaschema reconciler needs. Every call lives on FrontierService; the caller provides one value that serves it. There is no delete: built-in metaschemas are values, reset but never removed.

type MetaSchemaReconciler ¶ added in v0.115.0

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

MetaSchemaReconciler makes the built-in metaschemas match the desired spec. The name is the identity; the JSON schema is the managed value. Built-ins are values: one left out of the file resets to its shipped default.

func NewMetaSchemaReconciler(client MetaSchemaAPI, header string) *MetaSchemaReconciler

func (r *MetaSchemaReconciler) Export(ctx context.Context) (any, error)

func (r *MetaSchemaReconciler) Kind() string

func (r *MetaSchemaReconciler) Reconcile(ctx context.Context, spec []byte, dryRun bool) (Report, error)

func (r *MetaSchemaReconciler) Validate(spec []byte) error

type MetaSchemaSpec ¶ added in v0.115.0

type MetaSchemaSpec struct {
	Name   string `yaml:"name"`
	Schema string `yaml:"schema"`
}

MetaSchemaSpec is one desired metaschema. Name is a built-in metaschema name the server knows; Schema is the JSON schema as a string.

type Op ¶

type Op struct {
	Action   opAction
	Type     string
	Ref      string
	Relation string
}

Op is a single planned change to one (principal, relation). Ref is the desired entry's ref for an add (email or id) and the current principal's id for a remove.

func (o Op) String() string

type PermissionAPI ¶ added in v0.110.0

type PermissionAPI interface {
	ListPermissions(context.Context, *connect.Request[frontierv1beta1.ListPermissionsRequest]) (*connect.Response[frontierv1beta1.ListPermissionsResponse], error)
	CreatePermission(context.Context, *connect.Request[frontierv1beta1.CreatePermissionRequest]) (*connect.Response[frontierv1beta1.CreatePermissionResponse], error)
	DeletePermission(context.Context, *connect.Request[frontierv1beta1.DeletePermissionRequest]) (*connect.Response[frontierv1beta1.DeletePermissionResponse], error)
}

PermissionAPI is the API subset the permission reconciler needs. Reads live on FrontierService, writes on AdminService; the caller provides one value that serves both.

type PermissionReconciler ¶ added in v0.110.0

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

PermissionReconciler makes custom permissions match the desired spec. Base-schema permissions (app namespaces) are server-managed and ignored.

func NewPermissionReconciler(client PermissionAPI, header string) *PermissionReconciler

func (r *PermissionReconciler) Export(ctx context.Context) (any, error)

func (r *PermissionReconciler) Kind() string

func (r *PermissionReconciler) Reconcile(ctx context.Context, spec []byte, dryRun bool) (Report, error)

func (r *PermissionReconciler) Validate(spec []byte) error

type PermissionSpec ¶ added in v0.110.0

type PermissionSpec struct {
	Namespace string `yaml:"namespace"`
	Name      string `yaml:"name"`
	Delete    bool   `yaml:"delete,omitempty"`
}

PermissionSpec is one desired permission. A permission is identity only (namespace + name): it is added or deleted, never updated. Deleting needs the explicit flag; a permission that just disappears from the file fails the plan instead.

func (s PermissionSpec) String() string

type PlatformUserAPI ¶

type PlatformUserAPI interface {
	ListPlatformUsers(context.Context, *connect.Request[frontierv1beta1.ListPlatformUsersRequest]) (*connect.Response[frontierv1beta1.ListPlatformUsersResponse], error)
	AddPlatformUser(context.Context, *connect.Request[frontierv1beta1.AddPlatformUserRequest]) (*connect.Response[frontierv1beta1.AddPlatformUserResponse], error)
	RemovePlatformUser(context.Context, *connect.Request[frontierv1beta1.RemovePlatformUserRequest]) (*connect.Response[frontierv1beta1.RemovePlatformUserResponse], error)
}

PlatformUserAPI is the subset of the admin API the platform-user reconciler needs. frontierv1beta1connect.AdminServiceClient satisfies it.

type PlatformUserReconciler ¶

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

PlatformUserReconciler makes platform admins and members match the desired spec.

func NewPlatformUserReconciler(client PlatformUserAPI, header string) *PlatformUserReconciler

func (r *PlatformUserReconciler) Export(ctx context.Context) (any, error)

func (r *PlatformUserReconciler) Kind() string

func (r *PlatformUserReconciler) Reconcile(ctx context.Context, spec []byte, dryRun bool) (Report, error)

func (r *PlatformUserReconciler) Validate(spec []byte) error

type PlatformUserSpec ¶

type PlatformUserSpec struct {
	Type     string `yaml:"type"`     // "user" | "serviceuser"
	Ref      string `yaml:"ref"`      // email or uuid for a user; id for a service user
	Relation string `yaml:"relation"` // "admin" | "member"
}

PlatformUserSpec is one desired platform-user entry from the YAML spec. Relation is "admin" or "member" — a SpiceDB relation, not an RBAC "role" (a separate concept in Frontier), hence the field name.

type PreferenceAPI ¶ added in v0.110.0

type PreferenceAPI interface {
	ListPreferences(context.Context, *connect.Request[frontierv1beta1.ListPreferencesRequest]) (*connect.Response[frontierv1beta1.ListPreferencesResponse], error)
	DescribePreferences(context.Context, *connect.Request[frontierv1beta1.DescribePreferencesRequest]) (*connect.Response[frontierv1beta1.DescribePreferencesResponse], error)
	CreatePreferences(context.Context, *connect.Request[frontierv1beta1.CreatePreferencesRequest]) (*connect.Response[frontierv1beta1.CreatePreferencesResponse], error)
}

PreferenceAPI is the API subset the preference reconciler needs. The reads live on different services (platform preferences on AdminService, the trait list on FrontierService); the caller provides one value that serves both.

type PreferenceReconciler ¶ added in v0.110.0

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

PreferenceReconciler makes platform preferences match the desired spec. A preference is a name and a value; a missing entry resets to the trait default, because settings always have a default to fall back to.

func NewPreferenceReconciler(client PreferenceAPI, header string) *PreferenceReconciler

func (r *PreferenceReconciler) Export(ctx context.Context) (any, error)

func (r *PreferenceReconciler) Kind() string

func (r *PreferenceReconciler) Reconcile(ctx context.Context, spec []byte, dryRun bool) (Report, error)

func (r *PreferenceReconciler) Validate(spec []byte) error

type PreferenceSpec ¶ added in v0.110.0

type PreferenceSpec struct {
	Name  string `yaml:"name"`
	Value string `yaml:"value"`
}

PreferenceSpec is one desired platform preference. Name is a trait name the server knows; value is the string value to set. Preferences are strings end to end, so a boolean-like trait is "true" or "false".

type Reconciler ¶

type Reconciler interface {
	Kind() string
	Validate(spec []byte) error
	Reconcile(ctx context.Context, spec []byte, dryRun bool) (Report, error)
	Export(ctx context.Context) (spec any, err error)
}

Reconciler makes a single resource kind match its desired-state spec. Validate checks a spec without touching the server or applying anything, so the whole file can be checked before the first change is made. Export is the reverse direction and is part of the contract: it reads the current server state and returns it as a spec value, ready to be marshalled into a desired-state document. Reconciling an exported document must plan no changes.

type Report ¶

type Report struct {
	Kind    string
	DryRun  bool
	Planned []string // the plan, human-readable
	Applied int      // number actually applied (0 when dryRun)
}

Report summarises what a reconcile did, or would do when dryRun.

func Run(ctx context.Context, registry map[string]Reconciler, data []byte, dryRun bool) ([]Report, error)

type RoleAPI ¶ added in v0.110.0

type RoleAPI interface {
	ListRoles(context.Context, *connect.Request[frontierv1beta1.ListRolesRequest]) (*connect.Response[frontierv1beta1.ListRolesResponse], error)
	CreateRole(context.Context, *connect.Request[frontierv1beta1.CreateRoleRequest]) (*connect.Response[frontierv1beta1.CreateRoleResponse], error)
	UpdateRole(context.Context, *connect.Request[frontierv1beta1.UpdateRoleRequest]) (*connect.Response[frontierv1beta1.UpdateRoleResponse], error)
	DeleteRole(context.Context, *connect.Request[frontierv1beta1.DeleteRoleRequest]) (*connect.Response[frontierv1beta1.DeleteRoleResponse], error)
}

RoleAPI is the API subset the role reconciler needs. Reads live on FrontierService, writes on AdminService; the caller provides one value that serves both.

type RoleReconciler ¶ added in v0.110.0

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

RoleReconciler makes platform-level roles match the desired spec. The role name is the identity; title, permissions, and scopes are the managed fields.

func NewRoleReconciler(client RoleAPI, header string) *RoleReconciler

func (r *RoleReconciler) Export(ctx context.Context) (any, error)

func (r *RoleReconciler) Kind() string

func (r *RoleReconciler) Reconcile(ctx context.Context, spec []byte, dryRun bool) (Report, error)

func (r *RoleReconciler) Validate(spec []byte) error

type RoleSpec ¶ added in v0.110.0

type RoleSpec struct {
	Name        string    `yaml:"name"`
	Title       *string   `yaml:"title,omitempty"`
	Description *string   `yaml:"description,omitempty"`
	Permissions *[]string `yaml:"permissions,omitempty"`
	Scopes      *[]string `yaml:"scopes,omitempty"`
	Delete      bool      `yaml:"delete,omitempty"`
}

RoleSpec is one desired platform-level role. Name is the identity and never changes. Every other field uses presence tracking: a pointer is nil when the field is omitted, and non-nil when the file lists it (including an explicit empty value like `title: ""` or `scopes: []`).

A present field is the whole desired value for that field. An omitted field takes the role's default: empty for a custom role, and the shipped definition's value for a predefined role. So custom and predefined roles run through the same rule; they differ only in their defaults and in that a predefined role is never created or deleted by this flow.

type WebhookAPI ¶ added in v0.111.0

type WebhookAPI interface {
	ListWebhooks(context.Context, *connect.Request[frontierv1beta1.ListWebhooksRequest]) (*connect.Response[frontierv1beta1.ListWebhooksResponse], error)
	CreateWebhook(context.Context, *connect.Request[frontierv1beta1.CreateWebhookRequest]) (*connect.Response[frontierv1beta1.CreateWebhookResponse], error)
	UpdateWebhook(context.Context, *connect.Request[frontierv1beta1.UpdateWebhookRequest]) (*connect.Response[frontierv1beta1.UpdateWebhookResponse], error)
	DeleteWebhook(context.Context, *connect.Request[frontierv1beta1.DeleteWebhookRequest]) (*connect.Response[frontierv1beta1.DeleteWebhookResponse], error)
}

WebhookAPI is the API subset the webhook reconciler needs. Every webhook operation lives on the admin service.

type WebhookReconciler ¶ added in v0.111.0

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

WebhookReconciler makes webhook endpoints match the desired spec. The URL is the identity; description, subscribed events, and state are the managed fields. A missing endpoint fails the plan, and deletion needs an explicit delete flag.

func NewWebhookReconciler(client WebhookAPI, header string) *WebhookReconciler

func (r *WebhookReconciler) Export(ctx context.Context) (any, error)

func (r *WebhookReconciler) Kind() string

func (r *WebhookReconciler) Reconcile(ctx context.Context, spec []byte, dryRun bool) (Report, error)

func (r *WebhookReconciler) Validate(spec []byte) error

type WebhookSpec ¶ added in v0.111.0

type WebhookSpec struct {
	URL              string   `yaml:"url"`
	Description      string   `yaml:"description,omitempty"`
	SubscribedEvents []string `yaml:"subscribed_events"`
	State            string   `yaml:"state,omitempty"`
	Delete           bool     `yaml:"delete,omitempty"`
}

WebhookSpec is one desired webhook endpoint. The URL is the identity and never changes. Every other field states the whole desired value under the one field model: a field written in the file is used as-is, and an omitted field takes its default, nothing is merged from the server. Subscribed events are the full desired set: an empty list (or none) means the endpoint receives every event, which is the server's own default, and export always writes the field so an all-events endpoint reads as an explicit `subscribed_events: []`. Description defaults to empty, so omitting it clears any description on the server. State defaults to enabled, the state the server gives a new endpoint, so omitting it converges the endpoint to enabled. Signing secrets are server-owned: the server generates one on create and never returns it on read, so they are not part of the spec.