hub

package
v0.1.7 Latest Latest
Warning

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

Go to latest
Published: Aug 15, 2026 License: Apache-2.0 Imports: 73 Imported by: 0

Documentation

Overview

Package hub implements the faros hub server.

Index

Constants

This section is empty.

Variables

View Source
var ErrAnonymousProviderCaller = errors.New("anonymous caller")

ErrAnonymousProviderCaller is returned by the tenant resolver when the caller carries no bearer token. The backend proxy treats this as a non-error "forward without identity headers" so unauthenticated probes (health checks, smoke tests) work without provider auth.

Functions

func NewScheme

func NewScheme() *runtime.Scheme

NewScheme builds a runtime.Scheme containing all types needed by the multicluster manager: core k8s types, faros CRDs, tenancy CRDs, and the kcp SDK types required by multicluster-provider internals.

func WithPortalSecurityHeaders

func WithPortalSecurityHeaders(next http.Handler, frameSources ...string) http.Handler

WithPortalSecurityHeaders wraps a portal handler to set a Content-Security- Policy permitting provider iframes proxied through the hub. The policy allows same-origin frames (every /ui/providers/{name}/* path is hub-proxied, so same-origin from the browser's perspective) and optional platform-owned frame sources such as App Studio preview hosts.

Applied to both the embedded portal SPA and the --portal-dev-url proxy so the dev experience matches production.

Types

type Options

type Options struct {
	DataDir               string
	ListenAddr            string
	Kubeconfig            string
	ExternalKCPKubeconfig string
	IDPIssuerURL          string
	// IDPBrowserAuthURL optionally overrides only the OIDC authorization
	// endpoint placed in browser redirects. Discovery, token exchange, JWKS,
	// and issuer validation continue to use IDPIssuerURL.
	IDPBrowserAuthURL string
	IDPClientID       string
	// DisableTokenLogin removes the interactive static-token login: the
	// /auth/token-login endpoint is not registered and /healthz advertises
	// tokenLogin=false so the portal hides its token form. Static bearer
	// tokens keep authenticating API/MCP/CLI calls — only the browser login
	// path is disabled. Use with OIDC so humans sign in with a username and
	// password at the IdP.
	DisableTokenLogin bool
	// PublishedAppsDomain is the DNS zone published template instances are
	// served under (e.g. "apps.faros.example"). When set, the hub mounts the
	// login-time published-app authorize/exchange endpoints and only ever
	// redirects sign-ins back to hosts directly under this zone. Empty
	// disables published-app auth entirely.
	PublishedAppsDomain string
	// IDPCAFile is a path to a PEM-encoded CA bundle used to verify the IdP's
	// TLS certificate. Required when IDPIssuerURL is https and uses a cert
	// not signed by a system trust anchor (e.g. the dev Dex deployment).
	IDPCAFile       string
	ServingCertFile string
	ServingKeyFile  string
	HubExternalURL  string
	HubInternalURL  string // Internal URL for kcp mount resolution (avoids CDN/proxy loops)
	// ProviderInternalURL, when set, is the server URL baked into the minted
	// provider kubeconfig instead of HubExternalURL. Use it when provider pods
	// reach the hub front-proxy at a different address than browsers do — e.g.
	// a kind pod dialing https://host.docker.internal:9443 while browsers use
	// https://localhost:9443.
	ProviderInternalURL string
	DevMode             bool
	StaticAuthTokens    []string

	// AdminUsers is the allowlist of platform-admin identities permitted to
	// reach the /api/admin/* surface and the portal's /bonkers area. Each entry
	// matches a User CR by name, email, or rbacIdentity (case-insensitive).
	// Empty disables the admin surface entirely.
	AdminUsers []string

	// Providers is the list of first-party builtin providers to materialize
	// into root:faros:providers at bootstrap. The flag accepts a comma-
	// separated list or repeats; see cmd/faros-hub/main.go for the default.
	// Empty/nil enables every known builtin (kcp.BuiltinProviderNames()).
	// Dependencies between builtins are validated at hub startup — see
	// pkg/hub/kcp.builtinEntries[].Requires.
	Providers []string

	// GraphQLAddr is the address of an external GraphQL gateway to proxy /graphql/ requests to.
	// If empty and EmbeddedGraphQL is false, the graphql proxy is disabled.
	GraphQLAddr string

	// EmbeddedGraphQL runs the GraphQL listener+gateway in-process alongside the hub.
	// When true, GraphQLAddr is ignored.
	EmbeddedGraphQL bool

	// GraphQL listener options (used when EmbeddedGraphQL is true).
	GraphQLAPIExportSliceName      string // APIExportEndpointSlice name (default: "core.faros.sh")
	GraphQLAPIExportLogicalCluster string // logical cluster of that endpointslice (default: "root:faros:providers")
	GraphQLGRPCAddr                string // in-process gRPC address (default: "localhost:50051")
	GraphQLPlayground              bool   // enable playground UI
	GraphQLPort                    int    // port for the embedded GraphQL HTTP server; 0 = serve via hub mux only

	// PortalDevURL, when set, reverse-proxies /ui/* to this URL (typically
	// a Vite dev server, e.g. http://localhost:3000). Takes precedence over the
	// embedded portal dist (if built with -tags portal_embed).
	PortalDevURL string
	// PortalFrameSources are additional CSP frame-src source expressions allowed
	// by the portal. Keep this narrow; provider UIs are still same-origin through
	// the hub, while platform-owned preview hosts can be added explicitly.
	PortalFrameSources []string

	// Embedded kcp options
	EmbeddedKCP         bool   // Enable embedded kcp server
	KCPRootDir          string // Root directory for kcp data (default: <DataDir>/kcp)
	KCPSecurePort       int    // Secure port for kcp API server (default: 6443)
	KCPBindAddress      string // Bind address for kcp API server (default: "127.0.0.1")
	KCPBatteriesInclude string // Comma-separated list of batteries to include (default: "admin,user")
	KCPTLSCertFile      string // TLS certificate file for kcp API server
	KCPTLSKeyFile       string // TLS key file for kcp API server
	// KCPShardExternalURL is the URL kcp publishes into APIExportEndpointSlice
	// and CachedResourceEndpointSlice statuses for outside consumers to dial.
	// Empty defaults to kcp's auto-detected external address, which for an
	// embedded kcp bound to 127.0.0.1 is "https://127.0.0.1:6443" — fine for
	// host-side clients, broken for clients running in a kind pod (they
	// resolve 127.0.0.1 to the pod itself). Override with e.g.
	// "https://host.docker.internal:6443" for kind-based dev setups.
	KCPShardExternalURL string
	// KCPShardVirtualWorkspaceURL must be set alongside KCPShardExternalURL.
	// The two URLs cover different slots in Shard.spec — externalURL feeds
	// generic outside-clients discovery, virtualWorkspaceURL is what
	// APIExportEndpointSlice / CachedResourceEndpointSlice publish in their
	// status.endpoints[]. For a single-shard embedded dev setup both want
	// the same value.
	KCPShardVirtualWorkspaceURL string
}

Options holds configuration for the hub server.

func NewOptions

func NewOptions() *Options

NewOptions returns default Options.

type Server

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

Server is the faros hub server orchestrator.

func NewServer

func NewServer(opts *Options) (*Server, error)

NewServer creates a new hub server.

func (*Server) Run

func (s *Server) Run(ctx context.Context) error

Run starts the hub server and blocks until the context is cancelled.

Directories

Path Synopsis
Package admin implements the platform-admin surface mounted at /api/admin/* and surfaced in the portal's gated /bonkers area.
Package admin implements the platform-admin surface mounted at /api/admin/* and surfaced in the portal's gated /bonkers area.
Package appauth is the hub's login-time authorization endpoint for published applications.
Package appauth is the hub's login-time authorization endpoint for published applications.
Package bootstrap embeds bootstrap resources for hub initialization.
Package bootstrap embeds bootstrap resources for hub initialization.
controllers
mcpserver
Package mcpserver reconciles MCPServer objects.
Package mcpserver reconciles MCPServer objects.
membershipindex
Package membershipindex implements the UMI invariant reconciler: a controller that watches UserMembershipIndex CRs in root:faros:users and repairs rows that strand a user.
Package membershipindex implements the UMI invariant reconciler: a controller that watches UserMembershipIndex CRs in root:faros:users and repairs rows that strand a user.
organization
Package organization implements the bootstrap controller that gives every User a personal Organization on creation (per docs/organizations.md §Personal Org).
Package organization implements the bootstrap controller that gives every User a personal Organization on creation (per docs/organizations.md §Personal Org).
softdelete
Package softdelete implements roadmap step 8: the soft-delete reconciler that honours the 30-day grace window from docs/organizations.md decisions O-8 (User delete) and O-13 (Org + Workspace delete).
Package softdelete implements roadmap step 8: the soft-delete reconciler that honours the 30-day grace window from docs/organizations.md decisions O-8 (User delete) and O-13 (Org + Workspace delete).
Package kcp bootstraps kcp API resources.
Package kcp bootstraps kcp API resources.
Package leaderelection gates the hub's singleton controllers so a hub scaled to multiple replicas still reconciles each object exactly once.
Package leaderelection gates the hub's singleton controllers so a hub scaled to multiple replicas still reconciles each object exactly once.
Package mcpaggregate serves the hub's always-on aggregate MCP endpoint.
Package mcpaggregate serves the hub's always-on aggregate MCP endpoint.
Package providers backs the hub's pluggable-provider extension surface: an in-memory routing table, reverse proxies for /ui/providers/{name}/* and /services/providers/{name}/*, and the controller that keeps the table in sync with ProviderCatalogEntry resources.
Package providers backs the hub's pluggable-provider extension surface: an in-memory routing table, reverse proxies for /ui/providers/{name}/* and /services/providers/{name}/*, and the controller that keeps the table in sync with ProviderCatalogEntry resources.
Package quota implements the quota checks pinned by decisions O-5 (Org quota = soft cap, admin-overridable per User; default 10) and O-6 (Workspace quota = soft cap, admin-overridable per Org; default 50) in docs/organizations.md.
Package quota implements the quota checks pinned by decisions O-5 (Org quota = soft cap, admin-overridable per User; default 10) and O-6 (Workspace quota = soft cap, admin-overridable per Org; default 50) in docs/organizations.md.
Package restapi implements roadmap step 10: the hub-mediated REST surface for Org / Workspace / Membership / User CRUD per docs/organizations.md decision O-10 ("Org workspaces are hub-mediated only"), plus the undelete actions wired to PR #212's soft-delete reconciler, the self-leave / role PATCH from O-12, and the ?cascade=true shortcut from O-9.
Package restapi implements roadmap step 10: the hub-mediated REST surface for Org / Workspace / Membership / User CRUD per docs/organizations.md decision O-10 ("Org workspaces are hub-mediated only"), plus the undelete actions wired to PR #212's soft-delete reconciler, the self-leave / role PATCH from O-12, and the ?cascade=true shortcut from O-9.
Package serviceaccounts implements roadmap step 9 (O-14): bot identity for child Workspaces via native kube `core/v1.ServiceAccount`s marked with faros annotations.
Package serviceaccounts implements roadmap step 9 (O-14): bot identity for child Workspaces via native kube `core/v1.ServiceAccount`s marked with faros annotations.
Package sharedstore is the hub's cross-replica key/value store for short-lived login state: browser sessions and published-app authorization codes.
Package sharedstore is the hub's cross-replica key/value store for short-lived login state: browser sessions and published-app authorization codes.
Package tenant implements the hub-side tenant middleware described in docs/organizations.md §Switch the active context.
Package tenant implements the hub-side tenant middleware described in docs/organizations.md §Switch the active context.
Package workloadidentity owns the production provider-action workload capability exchange.
Package workloadidentity owns the production provider-action workload capability exchange.

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL