codefly

package module
v0.1.65 Latest Latest
Warning

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

 Go to latest Published: Jul 25, 2026 License: MIT Imports: 28 Imported by: 1

README

workflow Go Report Card Go Reference

codefly + go = sdk-go

Documentation

Index

Constants

View Source 
const (
	// WorkContextHeaderName is the only HTTP carrier for a signed Work Context.
	// Product code should call AttachWorkContext instead of naming this header.
	WorkContextHeaderName = "x-codefly-work-context"

	WorkContextType      = "codefly.work-context/v1"
	WorkContextAlgorithm = "Ed25519"

	WorkContextReplayIdempotent = "idempotent"
	WorkContextReplaySingleUse  = "single-use"

	WorkContextMaxActorDepth = 16
	WorkContextMaxTokenBytes = 32 * 1024
)

Variables

View Source 
var (
	WorkContextDefaultTTL = 5 * time.Minute
	WorkContextMaxTTL     = 15 * time.Minute
	WorkContextClockSkew  = time.Minute

	ErrWorkContextInvalid = errors.New("invalid Codefly Work Context")
	ErrWorkContextDenied  = errors.New("Codefly Work Context scope denied")
)

Functions

func AttachWorkContext added in v0.1.51 

func AttachWorkContext(request *http.Request, token WorkContextToken) error

AttachWorkContext installs a token without exposing the carrier name to application code.

func CatchPanic added in v0.0.7 

func CatchPanic(ctx context.Context)

func Context added in v0.1.42 

func Context() context.Context

Context returns the provider-injected context built by Init (so wool.Get sees the SDK provider), or context.Background() before Init has run.

func Environment added in v0.1.46 

func Environment() string

Environment returns the Codefly environment selected for this process. The representation is owned by the SDK; product code must not read its carrier.

func Fixture added in v0.1.46 

func Fixture() string

Fixture returns the fixture selected by the Codefly runtime. Product code must not depend on the runtime's environment-variable representation.

func GetLogLevel added in v0.0.11 

func GetLogLevel() wool.Loglevel

func Init added in v0.0.11 

func Init(ctx context.Context) (*wool.Provider, error)

func InjectConfigurations added in v0.1.65 

func InjectConfigurations(configurations ...*basev0.Configuration) error

InjectConfigurations replaces the SDK's in-process configuration carrier without mutating the process environment. This is the library boundary for an embedded Codefly flow: resolved configuration enters the same immutable snapshot queried by For. Calling it with no configurations clears the prior injected configuration values.

func InjectEndpoints added in v0.1.65 

func InjectEndpoints(endpoints ...*resources.EndpointAccess) error

InjectEndpoints replaces the SDK's in-process endpoint carrier without mutating the process environment. Calling it with no endpoints clears the prior injected endpoint values. Invalid endpoint access is rejected before the live snapshot changes.

func IsLocal added in v0.1.46 

func IsLocal() bool

IsLocal reports whether the current Codefly environment is local.

func LoadEnvironmentVariables added in v0.0.7 

func LoadEnvironmentVariables() error

func LoadRuntimeEnvironmentFile added in v0.1.52 

func LoadRuntimeEnvironmentFile(path string) error

LoadRuntimeEnvironmentFile imports one Codefly-generated --output-env artifact into the process environment. It must be called before Init.

The file is data, not a shell script: values are preserved byte-for-byte after the first '=' and are never evaluated. Only CODEFLY__ carriers are accepted. Because the artifact can contain service secrets, group or world-accessible files are rejected.

func RequireWorkContextScope added in v0.1.55 

func RequireWorkContextScope(
	claims *basev0.WorkContextV1,
	requirement WorkContextScopeRequirement,
) error

RequireWorkContextScope evaluates the current actor's effective scope. The authority scopes apply to a direct owner call; when actors are present, only the final actor's monotonically attenuated granted scopes are effective.

Call this only after signature, time, issuer, and audience verification. The claims are structurally validated again so a caller cannot accidentally authorize from a hand-constructed or mutated protobuf.

func ScopedAuthSecret added in v0.1.46 

func ScopedAuthSecret() string

ScopedAuthSecret returns the host-issued plugin authentication secret. This legacy carrier remains encapsulated here until scoped auth moves to a typed capability; product code must not read it directly.

func ServiceVersion added in v0.1.39 

func ServiceVersion() string

func WithFixture added in v0.1.32 

func WithFixture(fixture string) bool

func WithGRPCExecutionContext added in v0.1.53 

func WithGRPCExecutionContext(
	ctx context.Context,
	execution ExecutionContext,
) (context.Context, error)

WithGRPCExecutionContext attaches one execution context to outgoing gRPC metadata while preserving unrelated metadata. Existing carrier values are rejected rather than overwritten or joined.

func Workspace added in v0.1.58 

func Workspace(ctx context.Context) (string, error)

Workspace returns the Codefly workspace identity for the current process. A runtime-injected identity is authoritative. Local tools that are not launched as a service fall back to the enclosing workspace resource, keeping product code independent from Codefly's environment-variable carriers.

Types

type ExchangeWorkContextAudienceInput added in v0.1.63 

type ExchangeWorkContextAudienceInput struct {
	Audience         string
	ReplayPolicy     string
	TTL              time.Duration
	AttenuatedScopes []*basev0.WorkScopeV1
}

ExchangeWorkContextAudienceInput reissues one verified Work Context for a different consumer. Immutable work and delegation identity is preserved. AttenuatedScopes, when non-nil, replaces the effective scopes and must be a subset of the parent's effective scopes.

type ExecutionContext added in v0.1.53 

type ExecutionContext struct {
	// contains filtered or unexported fields
}

ExecutionContext is the opaque authority and stable logical-operation identity carried to a Codefly execution boundary.

Callers construct it through NewExecutionContext and attach it through WithGRPCExecutionContext. Carrier names remain SDK-owned.

func GRPCExecutionContextFromIncoming added in v0.1.53 

func GRPCExecutionContextFromIncoming(ctx context.Context) (ExecutionContext, error)

GRPCExecutionContextFromIncoming extracts an opaque execution context from incoming gRPC metadata. It validates carrier cardinality and wire shape but does not verify Work Context trust.

func GRPCExecutionContextFromIncomingIfPresent added in v0.1.53 

func GRPCExecutionContextFromIncomingIfPresent(
	ctx context.Context,
) (execution ExecutionContext, present bool, err error)

GRPCExecutionContextFromIncomingIfPresent supports compatibility boundaries where execution attribution is optional. No carrier returns present=false; a partial or duplicate carrier is still an error.

func NewExecutionContext added in v0.1.53 

func NewExecutionContext(
	workContext WorkContextToken,
	operationID string,
) (ExecutionContext, error)

NewExecutionContext validates and freezes one Work Context/operation pair.

func (ExecutionContext) OperationID added in v0.1.53 

func (execution ExecutionContext) OperationID() string

OperationID returns the caller-stable logical operation identifier.

func (ExecutionContext) WorkContext added in v0.1.53 

func (execution ExecutionContext) WorkContext() WorkContextToken

WorkContext returns the opaque signed capability. Trust decisions still require WorkContextVerifier.

type Query added in v0.1.24 

type Query struct {
	// contains filtered or unexported fields
}

func For added in v0.1.24 

func For(ctx context.Context) *Query

func (*Query) API added in v0.1.24 

func (q *Query) API(name string) *Query

func (*Query) Configuration added in v0.1.24 

func (q *Query) Configuration(key string, name string) (string, error)

func (*Query) Endpoint added in v0.1.41 

func (q *Query) Endpoint(name string) *Query

Endpoint sets the endpoint name independently from the API type. Use when the endpoint name differs from the API protocol. Example: codefly.For(ctx).Service("neo4j").Endpoint("bolt").API("tcp")

func (*Query) Module added in v0.1.26 

func (q *Query) Module(s string) *Query

func (*Query) NamingScope added in v0.1.57 

func (q *Query) NamingScope(scope string) *Query

NamingScope selects the same advanced local port namespace used by `codefly run --naming-scope`. Leave empty for the normal interactive workspace.

func (*Query) NetworkInstance added in v0.1.24 

func (q *Query) NetworkInstance() *resources.NetworkInstance

func (*Query) Normalize added in v0.1.24 

func (q *Query) Normalize()

func (*Query) ResolveNetworkInstance added in v0.1.57 

func (q *Query) ResolveNetworkInstance() (*resources.NetworkInstance, error)

ResolveNetworkInstance returns one typed endpoint or a diagnostic error.

Runtime-injected endpoint capabilities always win. In Codefly LOCAL (and before an environment is explicitly selected), the SDK falls back to the workspace's deterministic native endpoint map. This lets independently loaded agents use the same address as `codefly endpoint` without parsing Codefly environment carriers or shelling out to the CLI.

func (*Query) Secret added in v0.1.24 

func (q *Query) Secret(key string, name string) (string, error)

func (*Query) Service added in v0.1.24 

func (q *Query) Service(s string) *Query

func (*Query) WithDefaultNetwork added in v0.1.25 

func (q *Query) WithDefaultNetwork() *Query

func (*Query) WorkspaceConfiguration added in v0.1.46 

func (q *Query) WorkspaceConfiguration(name string, key string) (string, error)

WorkspaceConfiguration returns one non-secret workspace configuration value. Product services must use this API instead of depending on Codefly's environment variable encoding, which is an SDK/runtime implementation detail.

func (*Query) WorkspaceSecret added in v0.1.46 

func (q *Query) WorkspaceSecret(name string, key string) (string, error)

WorkspaceSecret returns one secret workspace configuration value without exposing Codefly's environment variable encoding to the caller.

func (*Query) WorkspaceValue added in v0.1.46 

func (q *Query) WorkspaceValue(name string, key string) (string, error)

WorkspaceValue resolves a workspace value from the public namespace first, then the secret namespace. It is intended for settings whose sensitivity is deployment-defined while preserving a single SDK-only lookup boundary.

type StartChildSessionInput added in v0.1.51 

type StartChildSessionInput struct {
	SessionID    string
	Audience     string
	Actor        *basev0.WorkActorV1
	ReplayPolicy string
	TTL          time.Duration
}

StartChildSessionInput appends exactly one verified Actor and creates a child Session. The new actor's scopes must attenuate the parent's effective scope.

type StartRootSessionInput added in v0.1.51 

type StartRootSessionInput struct {
	SessionID    string
	Audience     string
	ReplayPolicy string
	TTL          time.Duration
}

StartRootSessionInput exchanges a valid capability for another root Session under the same Task. Identity, owner, scopes, actors, and attribution cannot be changed by the caller.

type StartTaskInput added in v0.1.51 

type StartTaskInput struct {
	Audience              string
	TenantID              string
	OwnerPrincipalID      string
	TaskID                string
	SessionID             string
	AuthorizationRevision uint64
	ReplayPolicy          string
	AuthorityScopes       []*basev0.WorkScopeV1
	ActorChain            []*basev0.WorkActorV1
	AttributionTeamIDs    []string
	WorkspaceID           string
	ProjectID             string
	TTL                   time.Duration
	NotBefore             time.Time
}

StartTaskInput creates a Task and its first root Session capability.

type WorkContextExpectations added in v0.1.51 

type WorkContextExpectations struct {
	Issuer                string
	Audience              string
	TenantID              string
	OwnerPrincipalID      string
	TaskID                string
	SessionID             string
	ParentSessionID       *string
	AuthorizationRevision *uint64
}

type WorkContextJWKSVerifier added in v0.1.54 

type WorkContextJWKSVerifier struct {
	// contains filtered or unexported fields
}

WorkContextJWKSVerifier verifies signed Work Contexts against a bounded, cached Ed25519 JWKS. An unknown key ID forces one generation-aware refresh, so rotation is picked up immediately without a request stampede.

func NewWorkContextJWKSVerifier added in v0.1.54 

func NewWorkContextJWKSVerifier(
	options WorkContextJWKSVerifierOptions,
) (*WorkContextJWKSVerifier, error)

NewWorkContextJWKSVerifier validates configuration without performing network I/O. The first Verify call fetches the JWKS.

func (*WorkContextJWKSVerifier) Verify added in v0.1.54 

func (v *WorkContextJWKSVerifier) Verify(
	ctx context.Context,
	token WorkContextToken,
	expected WorkContextExpectations,
) (*basev0.WorkContextV1, error)

Verify establishes Work Context trust using the current cached JWKS.

type WorkContextJWKSVerifierOptions added in v0.1.54 

type WorkContextJWKSVerifierOptions struct {
	URL            string
	HTTPClient     *http.Client
	CacheTTL       time.Duration
	RequestTimeout time.Duration
	Now            func() time.Time
	ClockSkew      time.Duration
}

WorkContextJWKSVerifierOptions configures rotation-aware public Work Context verification. The verifier caches only public keys and never stores bearer tokens or private material.

type WorkContextScopeRequirement added in v0.1.55 

type WorkContextScopeRequirement struct {
	ResourceKind            string
	Action                  string
	ResourceID              string
	RequireExplicitResource bool
}

WorkContextScopeRequirement identifies one exact capability a verified Work Context must grant. An empty ResourceID asks whether the effective scope grants every resource of ResourceKind; it never ignores explicit resource restrictions.

type WorkContextSigner added in v0.1.51 

type WorkContextSigner struct {
	// contains filtered or unexported fields
}

WorkContextSigner is an authority-side capability. Product applications should receive tokens from an authority/exchange endpoint, not receive this signer or its private key.

func NewWorkContextSigner added in v0.1.51 

func NewWorkContextSigner(options WorkContextSignerOptions) (*WorkContextSigner, error)

func (*WorkContextSigner) ExchangeWorkContextAudience added in v0.1.63 

func (s *WorkContextSigner) ExchangeWorkContextAudience(
	parent WorkContextToken,
	input ExchangeWorkContextAudienceInput,
) (WorkContextToken, *basev0.WorkContextV1, error)

ExchangeWorkContextAudience reissues a capability for another audience without creating a new Task, Session, actor, or delegation. Authorities use this when one logical execution crosses service trust boundaries. An exchange may reduce effective authority but can never widen it.

func (*WorkContextSigner) StartChildSession added in v0.1.51 

func (s *WorkContextSigner) StartChildSession(parent WorkContextToken, input StartChildSessionInput) (WorkContextToken, *basev0.WorkContextV1, error)

func (*WorkContextSigner) StartSession added in v0.1.51 

func (s *WorkContextSigner) StartSession(parent WorkContextToken, input StartRootSessionInput) (WorkContextToken, *basev0.WorkContextV1, error)

func (*WorkContextSigner) StartTask added in v0.1.51 

func (s *WorkContextSigner) StartTask(input StartTaskInput) (WorkContextToken, *basev0.WorkContextV1, error)

StartTask constructs and signs an immutable Task/root-Session context.

type WorkContextSignerOptions added in v0.1.51 

type WorkContextSignerOptions struct {
	Issuer     string
	KeyID      string
	PrivateKey ed25519.PrivateKey
	Now        func() time.Time
	Nonce      func() (string, error)
}

type WorkContextToken added in v0.1.51 

type WorkContextToken struct {
	// contains filtered or unexported fields
}

WorkContextToken is an opaque signed capability. Its encoded representation is exposed only for storage and transport adapters; use AttachWorkContext for HTTP requests and WorkContextVerifier for trust decisions.

func ParseWorkContextToken added in v0.1.51 

func ParseWorkContextToken(encoded string) (WorkContextToken, error)

ParseWorkContextToken validates only the bounded two-segment wire shape. It does not establish trust; call WorkContextVerifier.Verify before using claims.

func WorkContextFromHeaders added in v0.1.51 

func WorkContextFromHeaders(headers http.Header) (WorkContextToken, error)

WorkContextFromHeaders extracts an opaque token. It does not verify it.

func (WorkContextToken) Encoded added in v0.1.51 

func (t WorkContextToken) Encoded() string

Encoded returns the signed wire value for persistence or a non-HTTP transport.

type WorkContextVerifier added in v0.1.51 

type WorkContextVerifier struct {
	// contains filtered or unexported fields
}

func NewWorkContextVerifier added in v0.1.51 

func NewWorkContextVerifier(options WorkContextVerifierOptions) (*WorkContextVerifier, error)

func (*WorkContextVerifier) Verify added in v0.1.51 

func (v *WorkContextVerifier) Verify(token WorkContextToken, expected WorkContextExpectations) (*basev0.WorkContextV1, error)

type WorkContextVerifierOptions added in v0.1.51 

type WorkContextVerifierOptions struct {
	PublicKeys map[string]ed25519.PublicKey
	Now        func() time.Time
	ClockSkew  time.Duration
}

Source Files

View all Source files

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.