Documentation
¶
Overview ¶
Package apiurl is the single source of truth for all railgrid service path construction and URL parsing. All packages that build or decompose railgrid hub URLs should use the helpers here instead of hand-crafting strings.
Index ¶
- Constants
- func EdgeAPIPath(cluster, edgeName string) string
- func EdgeProviderCoordinates(edgeType string) (provider, group, resource string)
- func EdgeServiceProxyPath(cluster, name, verb string) string
- func EdgeServiceProxyURL(hubBase, cluster, name, verb string) string
- func EdgeVerbPath(cluster, resource, name, verb string) string
- func EdgeVerbURL(hubBase, edgeType, cluster, name, verb 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, resource, cluster, edgeName, verb string) string
- func ProviderAgentProxyURL(hubBase, edgeType, cluster, edgeName, verb string) string
- func ProviderVerbPath(cluster, group, version, resource, name, verb string) string
- func ProviderVerbURL(base, cluster, group, version, resource, name, verb string) string
- func SplitBaseAndCluster(rawURL string) (base, cluster string)
Constants ¶
const ( // 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 railgrid virtual-workspace services and auth endpoints. Hub-specific endpoints live under /services and /auth — distinct from kcp's native /clusters, /apis/<group>, /api/v1 paths, which are forwarded straight to kcp.
const ( EdgesAPIGroup = "edges.railgrid.ai" EdgesAPIVersion = "v1alpha1" )
EdgesAPIGroup and EdgesAPIVersion are the edges provider's API coordinates, shared by every edge verb helper below.
Variables ¶
This section is empty.
Functions ¶
func EdgeAPIPath ¶
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/railgrid.ai/v1alpha1/edges/{name}
func EdgeProviderCoordinates ¶
EdgeProviderCoordinates resolves an edge type ("kubernetes" | "server" | "macos") to the owning provider's name, API group and resource. The edge plane is one provider `edges` holding all kinds under group edges.railgrid.ai; only the resource differs by type. Unknown values default to kubernetes for backwards compatibility with callers that omitted the edge type.
func EdgeServiceProxyPath ¶
EdgeServiceProxyPath returns the kube path of a verb on a Service published from an edge, served by the edges provider as a custom subresource.
verb is "proxy" (HTTP data plane) or "mcp".
Pattern: /clusters/{cluster}/apis/edges.railgrid.ai/v1alpha1/services/{name}/{verb}
func EdgeServiceProxyURL ¶
EdgeServiceProxyURL returns the full Service verb URL.
func EdgeVerbPath ¶ added in v0.2.7
EdgeVerbPath returns the kube path of a verb on an edge (a kubernetescluster, linuxserver or macosserver): its Kubernetes API ("k8s"), its SSH session ("ssh"), its MCP server ("mcp"), or an agent's own credential verbs ("agent-token", "ssh-credentials", "addon-credentials").
func EdgeVerbURL ¶ added in v0.2.7
EdgeVerbURL is EdgeVerbPath against a hub base URL, resolving the resource from the edge type.
func ExternalizeURL ¶
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 ¶
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 ¶
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 ¶
MCPServerPath returns the URL path for the unified MCPServer virtual workspace endpoint (aggregates kube + linux edges).
Pattern: /services/mcpserver/{cluster}/apis/railgrid.ai/v1alpha1/mcpservers/{name}/mcp
func MCPServerURL ¶
MCPServerURL returns the full MCPServer endpoint URL.
func ProviderAgentProxyPath ¶
ProviderAgentProxyPath returns the agent-ingress path for an edge provider's reverse-tunnel control connection: Pillar 2 route class (f), routed through the hub backend proxy to the provider Service. It is not a data-plane verb (the agent is not a kcp client; it authenticates with a join token or its edge ServiceAccount and holds a long-lived tunnel), so it is the one provider path that stays on the hub proxy. The provider sees the path unmodified.
Pattern: /services/providers/{provider}/agent/clusters/{cluster}/{resource}/{name}/proxy
func ProviderAgentProxyURL ¶
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 ProviderVerbPath ¶ added in v0.2.7
ProviderVerbPath returns the path of a provider data-plane verb: the kcp custom subresource "{resource}/{verb}" the provider publishes on its APIExport, addressed like any other kube API path on the front door the caller holds a credential for (the hub's /clusters/{id}). kcp authorizes SSAR "create" on the subresource with ordinary RBAC and reverse-proxies the request to the provider. There is no hub-side grammar for a verb: this is the only spelling.
Pattern: /clusters/{cluster}/apis/{group}/{version}/{resource}/{name}/{verb}
A verb on one component of a multi-component object carries the component as the "component" query parameter (provider-sdk/dataplane.ComponentQuery), which this helper leaves to the caller.
func ProviderVerbURL ¶ added in v0.2.7
ProviderVerbURL is ProviderVerbPath against a hub (or kcp front door) base URL.
func SplitBaseAndCluster ¶
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.
Types ¶
This section is empty.
Source Files