apiurl

Documentation

Overview

Package apiurl is the single source of truth for all faros service path construction and URL parsing. All packages that build or decompose faros hub URLs should use the helpers here instead of hand-crafting strings.

Index

• Constants
• func EdgeAPIPath(cluster, edgeName string) string
• func EdgeAgentProxyPath(cluster, edgeName, subresource string) string
• func EdgeAgentProxyURL(hubBase, cluster, edgeName, subresource string) string
• func EdgeProviderCoordinates(edgeType string) (provider, group, resource string)
• func EdgeProxyPath(cluster, edgeName, subresource string) string
• func EdgeProxyURL(hubBase, cluster, edgeName, subresource string) string
• func EdgeServiceProxyPath(cluster, name, subresource string) string
• func EdgeServiceProxyURL(hubBase, cluster, name, subresource string) string
• func ExternalizeURL(edgeURL, hubBase string) (string, error)
• func HubServerURL(hubBase, cluster string) string
• func KCPClusterURL(kcpBase, cluster string) string
• func MCPServerPath(cluster, mcpServerName string) string
• func MCPServerURL(hubBase, cluster, mcpServerName string) string
• func ProviderAgentProxyPath(provider, group, resource, cluster, edgeName, subresource string) string
• func ProviderAgentProxyURL(hubBase, edgeType, cluster, edgeName, subresource string) string
• func SplitBaseAndCluster(rawURL string) (base, cluster string)

Constants

const (
	PathPrefixAgentProxy = "/services/agent-proxy"
	PathPrefixEdgesProxy = "/services/edges-proxy"
	// PathPrefixMCP + PathPrefixLinuxMCP were removed in the MCP
	// collapse refactor — both surfaces live behind PathPrefixMCPServer
	// (the aggregate endpoint) now.
	PathPrefixMCPServer      = "/services/mcpserver"
	PathPrefixProvidersUI    = "/ui/providers"
	PathPrefixProvidersProxy = "/services/providers"
	// PathPrefixAPIExportVW is kcp's APIExport virtual-workspace prefix, which
	// the hub forwards verbatim to kcp so a provider running OUTSIDE the
	// platform can watch its own APIExport. Shape:
	//
	//	/services/apiexport/{cluster}/{export}/clusters/{wildcard}/...
	//
	// Unlike the prefixes above, the hub does not own this path — it is kcp's,
	// and the segments are kcp's to interpret. The hub only authorizes and
	// relays. See docs/byo-providers.md.
	PathPrefixAPIExportVW = "/services/apiexport"
	PathAuthAuthorize     = "/auth/authorize"
	PathAuthCallback      = "/auth/callback"
	PathAuthRefresh       = "/auth/refresh"
	PathAuthTokenLogin    = "/auth/token-login"
	PathHealthz           = "/healthz"
	PathVersion           = "/version"
)

Path prefix constants for faros virtual-workspace services and auth endpoints. Hub-specific endpoints live under /services, /auth, /graphql — distinct from kcp's native /clusters, /apis/<group>, /api/v1 paths, which are forwarded straight to kcp.

Functions

func EdgeAPIPath

func EdgeAPIPath(cluster, edgeName string) string

EdgeAPIPath returns the kcp API path for an Edge resource, suitable for use as a client Host suffix or in kubeconfig server URLs.

Pattern: /clusters/{cluster}/apis/faros.sh/v1alpha1/edges/{name}

func EdgeAgentProxyPath

func EdgeAgentProxyPath(cluster, edgeName, subresource string) string

EdgeAgentProxyPath returns the URL path (relative to the hub base) for the agent-proxy virtual workspace endpoint.

Pattern: /services/agent-proxy/{cluster}/apis/faros.sh/v1alpha1/edges/{name}/{subresource}

func EdgeAgentProxyURL

func EdgeAgentProxyURL(hubBase, cluster, edgeName, subresource string) string

EdgeAgentProxyURL returns the full agent-proxy URL for use when dialling the hub tunnel endpoint.

func EdgeProviderCoordinates

func EdgeProviderCoordinates(edgeType string) (provider, group, resource string)

EdgeProviderCoordinates resolves an edge type ("kubernetes" | "server") to the owning provider's backend-proxy name, API group and resource. The edge plane is one provider `edges` holding both kinds under group edges.faros.sh; only the resource differs by type. Any value other than "server" defaults to kubernetes.

func EdgeProxyPath

func EdgeProxyPath(cluster, edgeName, subresource string) string

EdgeProxyPath returns the URL path (relative to the hub base) for the edges-proxy virtual workspace endpoint.

Pattern: /services/edges-proxy/clusters/{cluster}/apis/faros.sh/v1alpha1/edges/{name}/{subresource}

func EdgeProxyURL

func EdgeProxyURL(hubBase, cluster, edgeName, subresource string) string

EdgeProxyURL returns the full edges-proxy URL, combining the hub base URL with the EdgeProxyPath.

func EdgeServiceProxyPath

func EdgeServiceProxyPath(cluster, name, subresource string) string

EdgeServiceProxyPath returns the consumer-egress path for a subresource on an EdgeService, routed through the hub backend proxy to the edges provider. The provider StripPrefixes /services/providers/edges/edgeproxy so its handler sees /clusters/{cluster}/apis/edges.faros.sh/v1alpha1/services/{name}/{subresource}.

subresource is "proxy" (HTTP data plane) or "mcp".

Pattern: /services/providers/edges/edgeproxy/clusters/{cluster}/apis/edges.faros.sh/v1alpha1/services/{name}/{subresource}

func EdgeServiceProxyURL

func EdgeServiceProxyURL(hubBase, cluster, name, subresource string) string

EdgeServiceProxyURL returns the full EdgeService subresource URL.

func ExternalizeURL

func ExternalizeURL(edgeURL, hubBase string) (string, error)

ExternalizeURL replaces the scheme and host in edgeURL with those from hubBase, making an internal edge-proxy URL routable through the public hub.

If edgeURL does not start with /services/ it is returned unchanged.

func HubServerURL

func HubServerURL(hubBase, cluster string) string

HubServerURL returns a URL with a /clusters/<cluster> suffix, suitable for both user-facing kubeconfigs (routed via the hub) and internal kcp client configurations. The hub forwards /clusters/* paths straight to kcp, so the same URL form works for both purposes.

If hubBase already contains a /clusters/ path it is replaced.

Example: HubServerURL("https://hub:9443", "abc123") → "https://hub:9443/clusters/abc123"

func KCPClusterURL

func KCPClusterURL(kcpBase, cluster string) string

KCPClusterURL is an alias for HubServerURL. In earlier iterations the hub had a prefix (/api or /apis) that the router stripped before forwarding to kcp, which required distinguishing "external hub" vs "internal kcp" URL forms. That distinction is gone; /clusters/ goes straight through.

func MCPServerPath

func MCPServerPath(cluster, mcpServerName string) string

MCPServerPath returns the URL path for the unified MCPServer virtual workspace endpoint (aggregates kube + linux edges).

Pattern: /services/mcpserver/{cluster}/apis/faros.sh/v1alpha1/mcpservers/{name}/mcp

func MCPServerURL

func MCPServerURL(hubBase, cluster, mcpServerName string) string

MCPServerURL returns the full MCPServer endpoint URL.

func ProviderAgentProxyPath

func ProviderAgentProxyPath(provider, group, resource, cluster, edgeName, subresource string) string

ProviderAgentProxyPath returns the agent-ingress path for an edge provider's reverse-tunnel control connection, routed through the hub backend proxy to the provider Service. The provider StripPrefixes /services/providers/{provider}/agent so its tunnel handler sees /{cluster}/apis/{group}/v1alpha1/{resource}/{name}/{subresource}.

Pattern: /services/providers/{provider}/agent/{cluster}/apis/{group}/v1alpha1/{resource}/{name}/{subresource}

func ProviderAgentProxyURL

func ProviderAgentProxyURL(hubBase, edgeType, cluster, edgeName, subresource string) string

ProviderAgentProxyURL returns the full agent-ingress URL for use when dialling the hub from the agent, resolving the provider coordinates from the edge type.

func SplitBaseAndCluster

func SplitBaseAndCluster(rawURL string) (base, cluster string)

SplitBaseAndCluster splits a URL that contains a /clusters/<name> path into a base URL (scheme+host only, no trailing slash) and the kcp cluster name.

Examples:

"https://hub:9443/clusters/abc123"            → ("https://hub:9443", "abc123")
"https://hub:9443/clusters/abc123/extra/path" → ("https://hub:9443", "abc123")
"https://hub:9443"                            → ("https://hub:9443", "default")
"https://hub:9443/"                           → ("https://hub:9443", "default")

Returns (trimmed url, "default") on parse error.