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 ¶
- Variables
- func DefaultWorkerSourceDir() string
- func EmbeddedWorkerSource() fs.FS
- 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 ValidateCloudflareEnv() errordeprecated
- func ValidateHostname(s string) bool
- func ValidatePreviewAlias(alias string) bool
- 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) Teardown(ctx context.Context) error
- type StatusGitHubAuth
- type WranglerRunner
Constants ¶
This section is empty.
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 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 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 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
}
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) 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 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.