Documentation
¶
Index ¶
- Constants
- Variables
- func GetArtifact(ctx context.Context, target OCITarget, opts ...ClientOpts) (v1.Descriptor, error)
- func NewClient(ctx context.Context, network Network, opts ...ConnectionOption) (*http.Client, error)
- func NewGitHubClient(token string) *gogithub.Client
- func NewRegoPolicy(ctx context.Context, module, query string, policyContent []byte, ...) (*rego.PreparedEvalQuery, error)
- func NewRegoPolicyFS(ctx context.Context, module, query, path string) (*rego.PreparedEvalQuery, error)
- func NewStateMachine(ctx context.Context, current string, c *Contract, opts ...FSMOption) (*stateless.StateMachine, error)
- func NewTransitionContext(ctx context.Context, u *TransitionCtx) context.Context
- func ParseConcertoPayload(data interface{}) ([]map[string]interface{}, error)
- func StateTransitionValidator(ctx context.Context, current string, ctr *Contract, tx Transition) (*stateless.StateMachine, error)
- func ValidateRepository(ctx context.Context, token, uri, branch, path string) (string, error)
- type Action
- type ClientOpts
- type Condition
- type ConnectionOption
- type ConnectionOptions
- type Contract
- func GetFSContract(path string) (*Contract, error)
- func GetGitHubContract(token, uri, branch, path string) (*Contract, error)
- func New() Contract
- func ValidateJSONPayload(in []byte) (*Contract, error)
- func ValidateTOMLPayload(in []byte) (*Contract, error)
- func ValidateYAMLPayload(in []byte) (*Contract, error)
- func (c *Contract) Connect(ctx context.Context, streamCfg jetstream.StreamConfig, ...) (jetstream.JetStream, jetstream.Consumer, error)
- func (c *Contract) CreateEvent(eventType, source string) (cloudevents.Event, error)
- func (c *Contract) GetEvents() []string
- func (c *Contract) GetState(name string) (State, error)
- func (c *Contract) GetVariables(state string) ([]Variables, error)
- func (c *Contract) InsertState(s State)
- func (c *Contract) IsEventRegistered(event cloudevents.Event) bool
- type ContractText
- type FSMOption
- type FSMOptions
- type GitSource
- type KubernetesAction
- type Network
- type OCITarget
- type PolicyOptions
- type PolicySource
- type Reconciler
- type ReconcilerConfig
- type ReconcilerOptions
- type RepoCredential
- type State
- type StateConfiguration
- type Status
- type TextSource
- type Transition
- type TransitionCtx
- type Variables
Constants ¶
const ( CloudEventsVersion = "1.0" StrictHeaders = false )
const ( // JSON is the JSON file format. JSON = "json" // YAML is the YAML file format. YAML = "yaml" // TOML is the TOML file format. TOML = "toml" )
const ( MediaTypeConcertoDataV2 = "application/vnd.concerto.data.v2+json" MediaTypeDecombineTemplateSlcV2JSON = "application/vnd.decombine.template.slc.v1+json" )
const (
Version = "0.1.0"
)
Variables ¶
var ( ErrCannotUnmarshalJSON = errors.New("cannot unmarshal contract json") ErrCannotUnmarshalYAML = errors.New("cannot unmarshal contract yaml") ErrCannotUnmarshalTOML = errors.New("cannot unmarshal contract toml") )
var (
ErrStateNotFound = errors.New("state not found")
)
Functions ¶
func GetArtifact ¶
func GetArtifact(ctx context.Context, target OCITarget, opts ...ClientOpts) (v1.Descriptor, error)
GetArtifact retrieves an artifact from a remote repository. GetArtifact is not yet implemented while the OCI design is being finalized. The function is a placeholder for future use.
func NewClient ¶
func NewClient(ctx context.Context, network Network, opts ...ConnectionOption) (*http.Client, error)
NewClient creates a new Client for a Contract Network.
func NewGitHubClient ¶
func NewRegoPolicy ¶
func NewRegoPolicy(ctx context.Context, module, query string, policyContent []byte, variables []Variables, logger *slog.Logger) (*rego.PreparedEvalQuery, error)
NewRegoPolicy prepares an OPA Rego policy for evaluation that can be used within Contract State Condition.
func NewRegoPolicyFS ¶
func NewRegoPolicyFS(ctx context.Context, module, query, path string) (*rego.PreparedEvalQuery, error)
NewRegoPolicyFS prepares an OPA Rego policy for evaluation from the local file system that can be used within Contract State Condition. This is useful for testing and development.
func NewStateMachine ¶
func NewStateMachine(ctx context.Context, current string, c *Contract, opts ...FSMOption) (*stateless.StateMachine, error)
NewStateMachine initializes a Finite State Machine (FSM) for a given Smart Legal Contract. The FSM is constructed based on the StateConfiguration of the Contract. The FSM is set to the current State passed as an argument.
func NewTransitionContext ¶
func NewTransitionContext(ctx context.Context, u *TransitionCtx) context.Context
NewTransitionContext returns a new Context that carries value TransitionCtx.
func ParseConcertoPayload ¶
ParseConcertoPayload processes JSON dynamically to extract objects with a "$class" field.
func StateTransitionValidator ¶
func StateTransitionValidator(ctx context.Context, current string, ctr *Contract, tx Transition) (*stateless.StateMachine, error)
StateTransitionValidator evaluates a State Machine and a possible transition to determine if the transition is valid or not.
Types ¶
type Action ¶
type Action struct {
// The type of the action
ActionType string `json:"actionType,omitempty" yaml:"actionType" toml:"actionType"`
KubernetesActions []KubernetesAction `json:"kubernetesAction,omitempty" yaml:"kubernetesAction" toml:"kubernetesAction"`
}
type ClientOpts ¶
type ClientOpts struct {
// OCI is the target to pull the OCI artifact from.
OCI OCITarget
// OCICreds are the credentials to use for the OCI registry.
OCICreds RepoCredential
// OCIPullPath is the target to pull the OCI artifact to.
OCIPullPath string
}
func WithOCI ¶
func WithOCI(registry, repo, tag string) ClientOpts
func WithOCICreds ¶
func WithOCICreds(credential RepoCredential) ClientOpts
type Condition ¶
type Condition struct {
// Name of the Condition.
Name string `json:"name" yaml:"name" toml:"name"`
// Value of the Condition. This may be used to represent a specific policy query.
// E.g., "data.policy.allow"
Value string `json:"value" yaml:"value" toml:"value"`
// Path to the Condition logic. E.g., "./service/condition.rego"
// Path is relative to the PolicySource.Directory.
Path string `json:"path" yaml:"path" toml:"path"`
}
Condition is used to apply a Policy to a Smart Legal Contract State Transition. A Policy may include Open Policy Agent (OPA) Rego logic.
type ConnectionOption ¶
type ConnectionOption func(*ConnectionOptions)
func WithJetStream ¶
func WithJetStream(config jetstream.StreamConfig) ConnectionOption
WithJetStream is a ConnectionOption to provide a JetStream configuration for the Contract Network.
func WithSecret ¶
func WithSecret(secret string) ConnectionOption
func WithToken ¶
func WithToken(token string) ConnectionOption
WithToken is a ConnectionOption that changes the default behavior of the Contract Network to use a JSON Web Token (JWT).
type ConnectionOptions ¶
type ConnectionOptions struct {
JWT []byte
Secret string
JetStream jetstream.StreamConfig
}
ConnectionOptions holds options for configuring Contract Network connectivity.
type Contract ¶
type Contract struct {
// The unique identifier (UUID) of the SLC. Typically created by the Network managing the SLC.
ID string `json:"id,omitempty" yaml:"id,omitempty" toml:"id,omitempty"`
// The friendly Name of the SLC
Name string `json:"name" yaml:"name" toml:"name" validate:"required"`
// The Version of the SLC schema
Version string `json:"version" yaml:"version" toml:"version" validate:"required,semver"`
// Text of the SLC
Text ContractText `json:"text" yaml:"text" toml:"text"`
// The Source of the SLC
Source GitSource `json:"source" yaml:"source" toml:"source"`
// The Policy included in the SLC
Policy PolicySource `json:"policy" yaml:"policy" toml:"policy"`
// The StateConfiguration of the SLC used to dictate a State Machine.
State StateConfiguration `json:"state" yaml:"state" toml:"state" validate:"required"`
// The Network of the SLC
Network Network `json:"network,omitempty" yaml:"network,omitempty" toml:"network,omitempty"`
// Status of the SLC. Typically used by the runtime operating the SLC.
Status Status `json:"status,omitempty" yaml:"status,omitempty" toml:"status,omitempty"`
}
Contract is the definition of a Decombine SLC.
func GetFSContract ¶
func GetGitHubContract ¶
GetGitHubContract retrieves a Contract from a remote GitHub repository. A Personal Access Token (PAT) token may be provided for private repositories.
func ValidateJSONPayload ¶
ValidateJSONPayload validates a JSON payload input against the Contract struct.
func ValidateTOMLPayload ¶
ValidateTOMLPayload validates a TOML payload input against the Contract struct.
func ValidateYAMLPayload ¶
ValidateYAMLPayload validates a YAML payload input against the Contract struct.
func (*Contract) CreateEvent ¶
func (c *Contract) CreateEvent(eventType, source string) (cloudevents.Event, error)
CreateEvent creates a new Event with the given type.
func (*Contract) GetEvents ¶
GetEvents returns a list of all events that the Contract StateConfiguration has registered.
func (*Contract) GetVariables ¶
GetVariables returns the Variables for a given State. Variables can be used to store values associated with State Configuration.
func (*Contract) InsertState ¶
func (*Contract) IsEventRegistered ¶
func (c *Contract) IsEventRegistered(event cloudevents.Event) bool
IsEventRegistered determines if the Event is registered in a Transition.
type ContractText ¶
type ContractText struct {
// Text URL of the Smart Legal Contract
URL string `json:"url" yaml:"url" toml:"url" validate:"required,url"`
}
type FSMOption ¶
type FSMOption func(*FSMOptions)
func WithFSPolicyFiles ¶
WithFSPolicyFiles is an FSMOption that changes the default behavior of the FSM to use Policy files from the file system instead of a remote Git repository. This is useful for testing and development. The path argument is relative to the current working directory.
func WithGitHubToken ¶
WithGitHubToken is an FSMOption that changes the default behavior of the FSM to use a GitHub Personal Access Token when retrieving Policy files from a remote Git repository.
func WithLogger ¶
WithLogger is an FSMOption that allows the user to set a custom logger for the FSM.
type FSMOptions ¶
FSMOptions is a struct that holds options for configuring the behavior of the FSM.
type GitSource ¶
type GitSource struct {
// The type of the source
Type string `json:"type,omitempty" yaml:"type,omitempty" toml:"type,omitempty"`
// The URL of the Git repository
URL string `json:"url" yaml:"url" toml:"url" validate:"required,url"`
// The branch of the Git repository
Branch string `json:"branch" yaml:"branch" toml:"branch"`
// The path to the Smart Legal Contract Definition file
Path string `json:"path" yaml:"path" toml:"path"`
}
A GitSource is a Git repository source for Smart Legal Contracts.
type KubernetesAction ¶
type KubernetesAction struct {
Name string `json:"name,omitempty"`
Namespace string `json:"namespace,omitempty"`
KustomizationSpec *kustomizev1.KustomizationSpec `json:"kustomizationSpec,omitempty" yaml:"kustomizationSpec" toml:"kustomizationSpec"`
}
type Network ¶
type Network struct {
// The Name of the Network. E.g., "decombine"
Name string `json:"name" yaml:"name" toml:"name" `
// The API hostname address of the Network. E.g., "api.decombine.com"
API string `json:"api" yaml:"api" toml:"api" `
// The URL of the Network for informational purposes. E.g., "https://decombine.com"
URL string `json:"url" yaml:"url" toml:"url"`
// EventURL is the URL of the Event Stream.
EventURL string `json:"eventUrl" yaml:"eventUrl" toml:"eventUrl"`
// The ClientID of the Network used for OIDC.
ClientID string `json:"clientId" yaml:"clientId" tom:"clientId" `
// The Relying Party (RP) Issuer used for OIDC.
Issuer string `json:"issuer" yaml:"issuer" toml:"issuer"`
// The DiscoveryEndpoint used for OIDC.
DiscoveryEndpoint string `json:"discoveryEndpoint" yaml:"discoveryEndpoint" toml:"discoveryEndpoint"`
}
Network provides a reference for remote authentication, authorization, and state management.
type PolicyOptions ¶
type PolicyOptions struct {
Variables []Variables
}
func WithVars ¶
func WithVars(variables []Variables) PolicyOptions
type PolicySource ¶
type PolicySource struct {
// The branch of the Git repository
Branch string `json:"branch" yaml:"branch" toml:"branch"`
// The directory containing the OPA policies
Directory string `json:"directory" yaml:"directory" toml:"directory"`
// The URL of the Git repository
URL string `json:"url" yaml:"url" toml:"url" validate:"required,url"`
}
PolicySource for the Open Policy Agent (OPA) policies.
type Reconciler ¶
type Reconciler struct {
Config ReconcilerConfig
EventChannel chan *cloudevents.Event
Consumer jetstream.Consumer
Stream jetstream.JetStream
Contract *Contract
FSM *stateless.StateMachine
Client client.Client
CloudEventOpts []http.Option
Logger *slog.Logger
}
func NewReconciler ¶
func NewReconciler(c *Contract, fsm *stateless.StateMachine, consumer jetstream.Consumer, stream jetstream.JetStream, config ReconcilerConfig, options ...ReconcilerOptions) *Reconciler
func (*Reconciler) ConsumeEvent ¶
func (r *Reconciler) ConsumeEvent(ctx context.Context, event *cloudevents.Event, eligible []Transition) error
ConsumeEvent consumes an Event and initiates State Transition if the Event is relevant.
type ReconcilerConfig ¶
type ReconcilerConfig struct {
// LogLevel is the log level for the Reconciler.
LogLevel slog.Level
// UseCloudEventReceiver indicates if the Reconciler should start a CloudEvents receiver.
// Can be combined with Reconciler.CloudEventOpts to configure the receiver.
UseCloudEventReceiver bool
// PublishSubject adds a Subject to Publish events to on the Stream.
PublishSubject string
// Workers is the number of workers to spawn for processing messages.
Workers int
// MaxMassages is the maximum number of messages to process at once.
MaxMassages int
}
type ReconcilerOptions ¶
type ReconcilerOptions struct {
// contains filtered or unexported fields
}
func WithCloudEventReceiverOpts ¶
func WithCloudEventReceiverOpts(ceOpts ...http.Option) ReconcilerOptions
func WithKubernetesClient ¶
func WithKubernetesClient(client client.Client) ReconcilerOptions
func WithReconcilerLogger ¶
func WithReconcilerLogger(logger *slog.Logger) ReconcilerOptions
type RepoCredential ¶
type State ¶
type State struct {
// The name of the State
Name string `json:"name" yaml:"name" toml:"name"`
// The actions that are executed when the State is entered
Entry Action `json:"entry" yaml:"entry" toml:"entry"`
// The actions that are executed when the State is exited
Exit Action `json:"exit" yaml:"exit" toml:"exit"`
// The variables associated with the State
Variables []Variables `json:"variables" yaml:"variables" toml:"variables"`
// The transitions that are possible from this State
Transitions []Transition `json:"transitions" yaml:"transitions" toml:"transitions" validate:"required,gte=0,dive"`
}
A State is a configured Status for a Decombine Smart Legal Contract based on UML State Machine.
type StateConfiguration ¶
type StateConfiguration struct {
// The Initial State of the SLC
Initial string `json:"initial" yaml:"initial" toml:"initial" validate:"required"`
// The URL of the StateConfiguration
URL string `json:"url" yaml:"url" toml:"url" validate:"required,url"`
// The States that comprise the SLC
States []State `json:"states" yaml:"states" toml:"states" validate:"required,gte=1,dive"`
}
A StateConfiguration is a collection of States that define the State Machine of a Smart Legal Contract.
type Status ¶
type Status struct {
// The current state of the smart legal contract
CurrentState string `json:"currentState,omitempty" yaml:"currentState,omitempty" toml:"currentState,omitempty"`
// The source state of the smart legal contract
SourceState string `json:"sourceState,omitempty" yaml:"sourceState,omitempty" toml:"sourceState,omitempty"`
// The policy state of the smart legal contract
PolicyState string `json:"policyState,omitempty" yaml:"policyState,omitempty" toml:"policyState,omitempty"`
// The workload state of the smart legal contract
WorkloadState string `json:"workloadState,omitempty" yaml:"workloadState,omitempty" toml:"workloadState,omitempty"`
}
type TextSource ¶
type TextSource struct {
// Name of the TextSource. E.g., "agreement-markdown, services-contract.pdf, com.decombine.decision-slc"
Name string `json:"name" yaml:"name" toml:"name"`
// Kind of the TextSource is a string value representing the REST resource of the object. E.g., "concerto, markdown, pdf"
Kind string `json:"kind" yaml:"kind" toml:"kind"`
// URL of the TextSource is a string value representing the URL/URI to the given resource.
URL string `json:"url" yaml:"url" toml:"url"`
}
type Transition ¶
type Transition struct {
// The Name of the Transition
Name string `json:"name" yaml:"name" toml:"name" validate:"required"`
// The State To which the Transition leads
To string `json:"to" yaml:"to" toml:"to" validate:"required"`
// The Event that Triggers the Transition
On string `json:"on" yaml:"on" toml:"on" validate:"required"`
// The Guard Conditions that must be satisfied for the Transition to occur
Conditions []Condition `json:"conditions" yaml:"conditions" toml:"conditions"`
}
Transition is a change from one State to another.
type TransitionCtx ¶
type TransitionCtx struct {
Input interface{} `json:"input" yaml:"input" toml:"input"`
}
TransitionCtx is used to pass input data to FSM Guard Functions for State Transition evaluation using Open Policy Agent (OPA) Rego policies.
func FromContext ¶
func FromContext(ctx context.Context) (*TransitionCtx, bool)
FromContext returns the transition value stored in ctx, if any.
type Variables ¶
type Variables struct {
// Name of the Variable
Name string `json:"name" yaml:"name" toml:"name"`
// The Type of the Variable (e.g., "string", "int", "bool")
Type string `json:"type" yaml:"type" toml:"type"`
// Default value of the Variable
Default string `json:"default" yaml:"default" toml:"default"`
// Ref is the reference to a specific source to populate the Variable
Ref string `json:"ref" yaml:"ref" toml:"ref"`
// Kind is a string value representing the REST resource of the object
Kind string `json:"kind" yaml:"kind" toml:"kind"`
}