Documentation
¶
Overview ¶
Package cf implements the dispatch.Dispatcher interface using a Cloudflare Worker as the token mint. The Worker runs the mintcore WASM module compiled from cmd/mint-wasm, with a thin TypeScript adapter (workersrc/) handling I/O. Credentials are read from env vars (CLOUDFLARE_ACCOUNT_ID, CLOUDFLARE_API_TOKEN) — no secrets are passed as CLI flags.
Index ¶
- Constants
- Variables
- func DefaultWorkerSourceDir() string
- func EmbeddedWorkerSource() fs.FS
- func NewTraceHeadersSecretName() (string, error)
- func PEMSecretsFromRoles(agentPEMs map[string][]byte) map[string][]byte
- func ResolveCloudflareAuth(ctx context.Context) (accountID string, err error)
- func ResolveZoneIDForDomain(ctx context.Context, domain string) (string, error)
- func TraceDeploymentName(workerName, previewAlias string) string
- func ValidateCloudflareEnv() errordeprecated
- func ValidateHostname(s string) bool
- func ValidatePreviewAlias(alias string) bool
- func ValidateTraceEndpoint(endpoint string) error
- func ValidateWorkerName(name string) bool
- type CloudflareAPIClient
- type Config
- type DeployMode
- type LiveCloudflareAPIClient
- func (c *LiveCloudflareAPIClient) AttachCustomDomain(ctx context.Context, accountID, workerName, zoneID, hostname string) error
- func (c *LiveCloudflareAPIClient) LookupZoneID(ctx context.Context, domain string) (string, error)
- func (c *LiveCloudflareAPIClient) RemoveCustomDomain(ctx context.Context, accountID, hostname string) error
- type LiveWranglerRunner
- func (r *LiveWranglerRunner) Delete(ctx context.Context, workerName string) error
- func (r *LiveWranglerRunner) Deploy(ctx context.Context, sourceDir, workerName string, previewAlias string, ...) (string, error)
- func (r *LiveWranglerRunner) PutSecret(ctx context.Context, workerName, secretName string, value []byte) error
- func (r *LiveWranglerRunner) WorkerExists(ctx context.Context, workerName string) (bool, error)
- type Provisioner
- func (p *Provisioner) Name() string
- func (p *Provisioner) OrgSecretNames() []string
- func (p *Provisioner) OrgVariableNames() []string
- func (p *Provisioner) Provision(ctx context.Context) (map[string]string, error)
- func (p *Provisioner) SetCloudflareAPI(client CloudflareAPIClient)
- func (p *Provisioner) StoreAgentPEM(ctx context.Context, role string, pemData []byte) error
- func (p *Provisioner) StoreTraceHeaders(ctx context.Context, headers []byte) error
- func (p *Provisioner) Teardown(ctx context.Context) error
- type StatusGitHubAuth
- type TracingStamp
- type WranglerRunner
Constants ¶
const TraceHeadersSecretName = "MINT_OTLP_HEADERS"
TraceHeadersSecretName is the default Worker secret holding OTLP collector authentication headers. cmd/mint-wasm reads it through the getEnv callback when a traces endpoint is stamped. Previews use this name; durable deploys stamp a unique per-build name instead (see TracingStamp.HeadersSecret).
Variables ¶
var BuildWASMFn = buildWASM
BuildWASMFn is the function used to compile mintcore.wasm from cmd/mint-wasm. Override in tests to avoid requiring a full Go toolchain and the mint-wasm source tree. Version, commit, and status auth config are stamped into the binary via -ldflags, mirroring how writeVersionGoToZip works for GCF deploys.
var CopyWASMExecFn = copyWASMExec
CopyWASMExecFn is the function used to copy wasm_exec.js from the Go toolchain into the Worker source directory. Override in tests.
var ResolveWorkersSubdomainFn = resolveWorkersSubdomain
ResolveWorkersSubdomainFn is the function used to resolve the workers.dev subdomain for a Cloudflare account. Override in tests to avoid real API calls.
var ResolveZoneIDForDomainFn = ResolveZoneIDForDomain
ResolveZoneIDForDomainFn is the function used to resolve zone IDs from domain names. Override in tests to avoid real API calls.
var WranglerAuthTokenFn = runWranglerAuthToken
WranglerAuthTokenFn is the function used to run `wrangler auth token`. Override in tests to avoid needing a real wrangler installation.
var WranglerWhoamiFn = runWranglerWhoami
WranglerWhoamiFn is the function used to run `wrangler whoami`. Override in tests to avoid needing a real wrangler installation.
Functions ¶
func DefaultWorkerSourceDir ¶
func DefaultWorkerSourceDir() string
DefaultWorkerSourceDir returns the default path to the Worker source directory. This assumes the CLI is run from the repository root.
func EmbeddedWorkerSource ¶
EmbeddedWorkerSource returns the embedded Worker source filesystem for testing embed integrity.
func NewTraceHeadersSecretName ¶ added in v0.49.0
NewTraceHeadersSecretName returns a unique Worker secret name for the collector headers of one durable deploy.
func PEMSecretsFromRoles ¶ added in v0.36.0
PEMSecretsFromRoles converts a role-keyed PEM map (e.g. "coder" → PEM data) into a Cloudflare secret-name-keyed map (e.g. "CODER_APP_PEM" → PEM data) suitable for passing as Config.Secrets during deploy.
func ResolveCloudflareAuth ¶ added in v0.36.0
ResolveCloudflareAuth resolves Cloudflare authentication and returns the account ID. It prefers explicit environment variables when set, but falls back to a Wrangler OAuth session (from 'wrangler login') when CLOUDFLARE_API_TOKEN is absent.
Resolution order:
- CLOUDFLARE_API_TOKEN + CLOUDFLARE_ACCOUNT_ID env vars → use both
- CLOUDFLARE_API_TOKEN set, CLOUDFLARE_ACCOUNT_ID unset → error
- CLOUDFLARE_API_TOKEN unset → check for Wrangler session via whoami a. If CLOUDFLARE_ACCOUNT_ID is set → use it b. If whoami output contains exactly one account → use its ID c. Otherwise → error with guidance
func ResolveZoneIDForDomain ¶ added in v0.37.0
ResolveZoneIDForDomain is a convenience function that creates a CloudflareAPIClient and resolves the zone ID for a domain. It resolves the API token from CLOUDFLARE_API_TOKEN or wrangler auth token (via resolveAPIToken, which cfAPIRequest also uses). This is intended for CLI-level use before building the provisioner config.
func TraceDeploymentName ¶ added in v0.49.0
TraceDeploymentName returns the deployment identity recorded on spans: the Worker name, with "@<alias>" appended for preview versions.
func ValidateCloudflareEnv
deprecated
func ValidateCloudflareEnv() error
ValidateCloudflareEnv checks that required Cloudflare environment variables are set. Returns an error listing all missing variables.
Deprecated: Use ResolveCloudflareAuth which also accepts Wrangler OAuth sessions as an alternative to CLOUDFLARE_API_TOKEN.
func ValidateHostname ¶ added in v0.37.0
ValidateHostname checks whether s is a syntactically valid DNS hostname suitable for use as a Workers Custom Domain value. It does not verify that the domain exists or is reachable.
func ValidatePreviewAlias ¶ added in v0.34.0
ValidatePreviewAlias checks if a string is a valid CF preview alias.
func ValidateTraceEndpoint ¶ added in v0.49.0
ValidateTraceEndpoint checks that endpoint is an absolute https URL without embedded credentials, and that it contains no whitespace, quotes or backslashes, so it can be stamped safely through -ldflags. Plain http is rejected: the Worker sends collector headers and trace payloads to this URL, and a Cloudflare Worker cannot reach a local-development collector anyway.
func ValidateWorkerName ¶
ValidateWorkerName checks if a string is a valid CF Worker name.
Types ¶
type CloudflareAPIClient ¶ added in v0.37.0
type CloudflareAPIClient interface {
// AttachCustomDomain registers a custom domain for a Worker via
// the Cloudflare Workers Custom Domains API. If the domain is
// already attached, this is a no-op.
AttachCustomDomain(ctx context.Context, accountID, workerName, zoneID, hostname string) error
// RemoveCustomDomain removes a Worker's custom domain binding
// by hostname.
RemoveCustomDomain(ctx context.Context, accountID, hostname string) error
// LookupZoneID resolves the Cloudflare zone ID for a given domain
// name by walking up the domain hierarchy. For example, given
// "mint.fullsend.sh", it tries "mint.fullsend.sh" then "fullsend.sh"
// until a matching zone is found. Returns an error if the zone is
// not in the account.
LookupZoneID(ctx context.Context, domain string) (string, error)
}
CloudflareAPIClient abstracts direct Cloudflare API calls for operations not covered by wrangler: custom domain attachment. Implementations must be safe for concurrent use from multiple goroutines.
type Config ¶
type Config struct {
// AccountID is the Cloudflare account ID. Read from
// CLOUDFLARE_ACCOUNT_ID env var.
AccountID string
// WorkerName is the Worker script name (e.g. "fullsend-mint",
// "fullsend-mint-test"). Defaults to "fullsend-mint".
WorkerName string
// DeployMode controls whether the Worker is deployed as a durable
// production Worker or an ephemeral preview.
DeployMode DeployMode
// SourceDir overrides the embedded Worker source with a local
// directory. When set, the provisioner uses this path directly
// instead of extracting embedded files. If mintcore.wasm and
// wasm_exec.js are not present, the provisioner copies the
// source to a temp directory and auto-builds them.
SourceDir string
// PreviewAlias is the Wrangler preview alias for preview deploys.
// When set (and DeployMode is DeployPreview), the provisioner uses
// `wrangler versions upload --preview-alias=<alias>` instead of
// `wrangler deploy`. The preview mint URL includes the account's
// workers.dev subdomain:
// https://<alias>-<worker-name>.<subdomain>.workers.dev
PreviewAlias string
// EnvVars are non-secret environment variables to set on the Worker
// (e.g. ROLE_APP_IDS, PER_REPO_WIF_REPOS).
EnvVars map[string]string
// Secrets are secret values to bind to the Worker during deploy.
// When non-empty, Deploy writes them to a temporary JSON file and
// passes --secrets-file to wrangler versions upload. Use this for
// preview deploys where wrangler secret put cannot scope secrets
// to a preview version.
Secrets map[string][]byte
// Version is the fullsend semver stamped on the deployed Worker.
Version string
// Commit is the git SHA stamped on the deployed Worker.
Commit string
// ZoneID is the Cloudflare zone ID for the custom domain.
// Required when CustomDomain is set. The zone must already exist
// in the Cloudflare account.
ZoneID string
// CustomDomain is the hostname to attach to the Worker as a
// Cloudflare Workers Custom Domain (e.g. "mint.fullsend.sh").
// When set for a durable deploy, the provisioner attaches the
// domain via the Cloudflare API. Ignored for preview deploys
// (which use bare workers.dev hostnames).
CustomDomain string
// StatusGitHub holds the GitHub status auth config stamped into
// the WASM binary via ldflags (same mechanism as Version/Commit).
StatusGitHub StatusGitHubAuth
// Tracing holds the nonsecret tracing settings stamped into the
// WASM binary via ldflags. Collector header values are never
// stamped: they are stored in a Worker secret (Secrets for previews,
// StoreTraceHeaders for durable).
Tracing TracingStamp
}
Config holds the inputs for CF Worker mint provisioning.
type DeployMode ¶
type DeployMode int
DeployMode controls Worker deployment behavior.
const ( // DeployDurable deploys a persistent, production Worker. DeployDurable DeployMode = iota // DeployPreview deploys an ephemeral preview Worker for testing. DeployPreview )
type LiveCloudflareAPIClient ¶ added in v0.37.0
type LiveCloudflareAPIClient struct {
// contains filtered or unexported fields
}
LiveCloudflareAPIClient implements CloudflareAPIClient using the Cloudflare REST API. Authentication is resolved via resolveAPIToken: CLOUDFLARE_API_TOKEN env var first, then wrangler auth token fallback.
func NewLiveCloudflareAPIClient ¶ added in v0.37.0
func NewLiveCloudflareAPIClient() *LiveCloudflareAPIClient
NewLiveCloudflareAPIClient creates a client that calls the Cloudflare REST API.
func (*LiveCloudflareAPIClient) AttachCustomDomain ¶ added in v0.37.0
func (c *LiveCloudflareAPIClient) AttachCustomDomain(ctx context.Context, accountID, workerName, zoneID, hostname string) error
AttachCustomDomain registers a custom domain for a Worker via PUT /accounts/{account_id}/workers/domains.
func (*LiveCloudflareAPIClient) LookupZoneID ¶ added in v0.37.0
LookupZoneID resolves the Cloudflare zone ID for a domain by walking up the domain hierarchy. For "mint.fullsend.sh" it tries "mint.fullsend.sh", then "fullsend.sh". Returns an error if no matching zone is found.
func (*LiveCloudflareAPIClient) RemoveCustomDomain ¶ added in v0.37.0
func (c *LiveCloudflareAPIClient) RemoveCustomDomain(ctx context.Context, accountID, hostname string) error
RemoveCustomDomain removes a Worker's custom domain binding by first looking up the domain ID, then deleting it.
type LiveWranglerRunner ¶
type LiveWranglerRunner struct {
// AccountID is passed to wrangler via CLOUDFLARE_ACCOUNT_ID.
AccountID string
}
LiveWranglerRunner executes wrangler commands via the CLI.
func NewLiveWranglerRunner ¶
func NewLiveWranglerRunner(accountID string) *LiveWranglerRunner
NewLiveWranglerRunner creates a runner that uses the real wrangler CLI.
func (*LiveWranglerRunner) Delete ¶
func (r *LiveWranglerRunner) Delete(ctx context.Context, workerName string) error
Delete removes a Worker deployment via wrangler delete.
func (*LiveWranglerRunner) Deploy ¶
func (r *LiveWranglerRunner) Deploy(ctx context.Context, sourceDir, workerName string, previewAlias string, envVars map[string]string, secrets map[string][]byte) (string, error)
Deploy deploys a Worker from sourceDir using wrangler.
When previewAlias is non-empty, uses `wrangler versions upload` with `--preview-alias=<alias>` for a preview deploy. The preview URL includes the account's workers.dev subdomain: https://<alias>-<workerName>.<subdomain>.workers.dev
When previewAlias is empty, uses `wrangler deploy` for a durable production deploy.
When secrets is non-empty, writes them to a temporary JSON file and passes --secrets-file. This is the only way to attach secrets to a preview version, since wrangler secret put does not support --preview-alias.
func (*LiveWranglerRunner) PutSecret ¶
func (r *LiveWranglerRunner) PutSecret(ctx context.Context, workerName, secretName string, value []byte) error
PutSecret stores a secret value on the durable Worker via wrangler secret put. This command does not support --preview-alias; for preview deploys, pass secrets through Deploy's secrets parameter instead.
func (*LiveWranglerRunner) WorkerExists ¶ added in v0.36.0
WorkerExists checks whether a Worker script with the given name exists by running `npx wrangler versions list --name <workerName>`. If the command succeeds, the Worker exists. If it fails with a "not found" error, the Worker does not exist.
type Provisioner ¶
type Provisioner struct {
// contains filtered or unexported fields
}
Provisioner creates Cloudflare Worker infrastructure for token minting.
func NewProvisioner ¶
func NewProvisioner(cfg Config, wrangler WranglerRunner) *Provisioner
NewProvisioner creates a new CF Provisioner with defaults applied.
func (*Provisioner) Name ¶
func (p *Provisioner) Name() string
Name returns the dispatcher identifier.
func (*Provisioner) OrgSecretNames ¶
func (p *Provisioner) OrgSecretNames() []string
OrgSecretNames returns nil — PEM secrets are stored as Worker secrets.
func (*Provisioner) OrgVariableNames ¶
func (p *Provisioner) OrgVariableNames() []string
OrgVariableNames returns the org variables this dispatcher manages.
func (*Provisioner) Provision ¶
Provision deploys the Cloudflare Worker mint and returns the Worker URL as FULLSEND_MINT_URL.
func (*Provisioner) SetCloudflareAPI ¶ added in v0.37.0
func (p *Provisioner) SetCloudflareAPI(client CloudflareAPIClient)
SetCloudflareAPI sets the Cloudflare API client used for custom domain attachment. When nil (the default), a LiveCloudflareAPIClient is created lazily if CustomDomain is configured.
func (*Provisioner) StoreAgentPEM ¶
StoreAgentPEM stores a role's PEM key as a Cloudflare Worker secret via wrangler secret put. Secret names follow the convention <ROLE>_APP_PEM (e.g. CODER_APP_PEM).
This method is intended for durable (non-preview) deploys. For preview deploys, pass secrets via Config.Secrets so they are included in the wrangler versions upload --secrets-file call, because wrangler secret put does not support --preview-alias.
func (*Provisioner) StoreTraceHeaders ¶ added in v0.49.0
func (p *Provisioner) StoreTraceHeaders(ctx context.Context, headers []byte) error
StoreTraceHeaders stores OTLP collector authentication headers via wrangler secret put, under the secret name stamped into this build (Config.Tracing.HeadersSecret, default TraceHeadersSecretName). Only the build stamped with that name reads the secret, so the headers are bound to this deploy's endpoint even if another deploy replaces the Worker concurrently. Like StoreAgentPEM it is for durable deploys only; preview deploys pass the secret via Config.Secrets so it is scoped to the preview version.
func (*Provisioner) Teardown ¶
func (p *Provisioner) Teardown(ctx context.Context) error
Teardown cleans up a Worker deployment.
For preview deploys (DeployPreview): abandons the preview alias without deleting the durable Worker script, which is shared with production. The alias is simply left unrouted.
For durable deploys (DeployDurable): deletes the Worker script and all associated bindings/secrets via `wrangler delete`.
type StatusGitHubAuth ¶ added in v0.37.0
type StatusGitHubAuth struct {
// Group is the ORG/TEAM slug for the GitHub status validator.
Group string
}
StatusGitHubAuth bundles the GitHub status auth configuration passed through provisioner and build functions.
type TracingStamp ¶ added in v0.49.0
type TracingStamp struct {
// Endpoint is the full OTLP/HTTP traces URL.
Endpoint string
// Deployment identifies the deployment on exported spans
// (fullsend.mint.deployment).
Deployment string
// HeadersSecret is the name of the Worker secret this build reads
// its collector headers from. Empty keeps the default
// (TraceHeadersSecretName). Durable deploys set a unique name per
// build so that two overlapping deploys can never bind one
// collector's credentials to the other's endpoint.
HeadersSecret string
}
TracingStamp is the nonsecret tracing configuration compiled into the mint WASM binary. An empty Endpoint disables tracing.
type WranglerRunner ¶
type WranglerRunner interface {
// Deploy deploys a Worker from sourceDir. Returns the Worker URL.
// When previewAlias is non-empty, the runner uses
// `wrangler versions upload --preview-alias=<alias>` instead of
// the production `wrangler deploy`. An empty previewAlias triggers
// a durable production deploy.
//
// When secrets is non-empty, the runner writes them to a temporary
// JSON file and passes --secrets-file to wrangler. This is required
// for preview deploys because wrangler secret put does not support
// --preview-alias.
Deploy(ctx context.Context, sourceDir, workerName string, previewAlias string, envVars map[string]string, secrets map[string][]byte) (url string, err error)
// PutSecret stores a secret value on the durable Worker via
// wrangler secret put. This command does not support --preview-alias;
// for preview deploys, pass secrets through Deploy instead.
PutSecret(ctx context.Context, workerName, secretName string, value []byte) error
// Delete removes a Worker deployment.
Delete(ctx context.Context, workerName string) error
// WorkerExists checks whether a Worker script with the given name
// already exists. Used to determine whether a bootstrap durable
// deploy is needed before a preview deploy.
WorkerExists(ctx context.Context, workerName string) (bool, error)
}
WranglerRunner abstracts wrangler CLI operations for testing.