cf

package
v0.47.0 Latest Latest
Warning

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

Go to latest
Published: Oct 11, 2026 License: Apache-2.0 Imports: 16 Imported by: 0

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

This section is empty.

Variables

View Source
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.

View Source
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.

View Source
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.

View Source
var ResolveZoneIDForDomainFn = ResolveZoneIDForDomain

ResolveZoneIDForDomainFn is the function used to resolve zone IDs from domain names. Override in tests to avoid real API calls.

View Source
var WranglerAuthTokenFn = runWranglerAuthToken

WranglerAuthTokenFn is the function used to run `wrangler auth token`. Override in tests to avoid needing a real wrangler installation.

View Source
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

func EmbeddedWorkerSource() fs.FS

EmbeddedWorkerSource returns the embedded Worker source filesystem for testing embed integrity.

func PEMSecretsFromRoles added in v0.36.0

func PEMSecretsFromRoles(agentPEMs map[string][]byte) map[string][]byte

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

func ResolveCloudflareAuth(ctx context.Context) (accountID string, err error)

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:

  1. CLOUDFLARE_API_TOKEN + CLOUDFLARE_ACCOUNT_ID env vars → use both
  2. CLOUDFLARE_API_TOKEN set, CLOUDFLARE_ACCOUNT_ID unset → error
  3. 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

func ResolveZoneIDForDomain(ctx context.Context, domain string) (string, error)

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

func ValidateHostname(s string) bool

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

func ValidatePreviewAlias(alias string) bool

ValidatePreviewAlias checks if a string is a valid CF preview alias.

func ValidateWorkerName

func ValidateWorkerName(name string) bool

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

func (c *LiveCloudflareAPIClient) LookupZoneID(ctx context.Context, domain string) (string, error)

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

func (r *LiveWranglerRunner) WorkerExists(ctx context.Context, workerName string) (bool, error)

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

func (p *Provisioner) Provision(ctx context.Context) (map[string]string, error)

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

func (p *Provisioner) StoreAgentPEM(ctx context.Context, role string, pemData []byte) error

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.

Jump to

Keyboard shortcuts

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