Documentation
¶
Overview ¶
Package captures authors explicit capture declarations for the kernel. There is no automatic discovery, registration or local capture worker. The kernel currently runs only API sources and root append rules; validation reports unsupported language features before activation. Source authorization is authorable but cannot be submitted through the CDL-only transport.
Index ¶
- type AppendRule
- type AuthorizationKind
- type Builder
- func (b *Builder) Append(rules ...AppendRule) *Builder
- func (b *Builder) Build(name string) (Definition, error)
- func (b *Builder) Children(path, key string, scope Scope) *Builder
- func (b Builder) Format(state fmt.State, _ rune)
- func (b *Builder) From(source Source) *Builder
- func (b *Builder) Key(path string) *Builder
- func (b Builder) LogValue() slog.Value
- func (b *Builder) Map(operations ...Mapping) *Builder
- func (b Builder) MarshalJSON() ([]byte, error)
- func (b *Builder) Nested(path string, scope Scope) *Builder
- func (b *Builder) UnmarshalJSON([]byte) error
- type Capturer
- type Condition
- type Definition
- func (d Definition) Authorization() (SourceAuthorization, bool)
- func (d Definition) Declaration() string
- func (d Definition) Format(state fmt.State, _ rune)
- func (d Definition) ID() uuid.UUID
- func (d Definition) LogValue() slog.Value
- func (d Definition) MarshalJSON() ([]byte, error)
- func (d *Definition) UnmarshalJSON([]byte) error
- type Mapping
- type Scope
- type Service
- type Source
- type SourceAuthorization
- type Translation
- type ValidationError
- type WebhookOption
Examples ¶
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
This section is empty.
Types ¶
type AppendRule ¶
type AppendRule struct {
// contains filtered or unexported fields
}
AppendRule is immutable. Construct using Append; the zero value is invalid.
type AuthorizationKind ¶ added in v0.3.0
type AuthorizationKind string
AuthorizationKind identifies an inbound capture source's authorization scheme.
const ( // AuthorizationNone is the zero SourceAuthorization's kind, not an authorable option. AuthorizationNone AuthorizationKind = "none" // AuthorizationBasic identifies username/password authorization. AuthorizationBasic AuthorizationKind = "basic" // AuthorizationBearer identifies bearer-token authorization. AuthorizationBearer AuthorizationKind = "bearer" // AuthorizationOAuth identifies authority/client credentials authorization. AuthorizationOAuth AuthorizationKind = "oauth" )
type Builder ¶
type Builder struct {
// contains filtered or unexported fields
}
Builder is a local mutable authoring builder, not safe for concurrent mutation. Source, key and Map are last-wins; append/nested/children accumulate. Build validates atomically and returns a frozen snapshot. Zero is usable. Formatting and logging are redacted; JSON import/export fails with ErrUnsupported.
Example ¶
package main
import (
"fmt"
"github.com/cratis/chronicle.go/captures"
"github.com/cratis/chronicle.go/events"
)
type StatusChanged struct{ Status string }
func main() {
event, err := events.Define[StatusChanged](events.WithID("InvoiceStatusChanged"))
if err != nil {
panic(err)
}
definition, err := new(captures.Builder).
From(captures.API("InvoicingApi", "/invoices", "10m")).
Key("id").
Append(captures.Append(event, captures.PropertyChanges("status"), map[string]string{"Status": "$.status"})).
Build("InvoiceCapture")
if err != nil {
panic(err)
}
fmt.Print(definition.Declaration())
}
Output: capture InvoiceCapture source api api InvoicingApi route /invoices poll 10m key id append InvoiceStatusChanged when status Status = $.status
func (*Builder) Append ¶
func (b *Builder) Append(rules ...AppendRule) *Builder
Append adds rules in declaration order.
func (*Builder) Build ¶
func (b *Builder) Build(name string) (Definition, error)
Build validates source/key/conditions and renders a new named CDL definition. Invalid webhook authorization fails with ErrInvalidConfiguration. Authorization is retained outside CDL; authorized definitions cannot yet be submitted. Build does not claim runtime support for every authorable language construct.
func (Builder) Format ¶ added in v0.3.0
Format redacts builder configuration for every fmt verb on both values and pointers.
func (Builder) LogValue ¶ added in v0.3.0
LogValue redacts builder configuration in structured logs.
func (Builder) MarshalJSON ¶ added in v0.3.0
MarshalJSON refuses builder export with ErrUnsupported.
func (*Builder) UnmarshalJSON ¶ added in v0.3.0
UnmarshalJSON refuses builder import with ErrUnsupported, leaving the value intact.
type Capturer ¶
Capturer is the explicit equivalent of C# ICapturer. Define is called once by Prepare, never on reconnect. It must not retain the builder or perform I/O.
type Condition ¶
type Condition struct {
// contains filtered or unexported fields
}
Condition is an immutable append condition; zero is invalid.
func Expression ¶
Expression authors a language expression. The pinned runtime rejects it; Validate/Save report that capability error instead of claiming activation.
func PropertyChanges ¶
PropertyChanges detects a single property's change.
func Transition ¶
Transition detects a property's change between two literal string values.
type Definition ¶
type Definition struct {
// contains filtered or unexported fields
}
Definition is immutable. Build assigns a fresh UUID, matching C#. Copies are safe for concurrent use. Formatting/logging is redacted; Declaration explicitly exports CDL only. JSON import/export fails with ErrUnsupported.
func Prepare ¶
func Prepare(name string, capturer Capturer) (Definition, error)
Prepare invokes a borrowed capturer and freezes its definition. No container, reflection discovery or automatic registration is involved.
func (Definition) Authorization ¶ added in v0.3.0
func (d Definition) Authorization() (SourceAuthorization, bool)
Authorization returns an immutable value and whether authorization was supplied on the source. The zero definition has no authorization.
func (Definition) Declaration ¶
func (d Definition) Declaration() string
Declaration returns the frozen CDL text. No credentials are embedded in it.
func (Definition) Format ¶
func (d Definition) Format(state fmt.State, _ rune)
Format redacts configuration, including mapping literals, for every fmt verb.
func (Definition) ID ¶
func (d Definition) ID() uuid.UUID
ID returns this declaration's identity; repeated saves update this capture.
func (Definition) LogValue ¶ added in v0.3.0
func (d Definition) LogValue() slog.Value
LogValue redacts the declaration and authorization in structured logs.
func (Definition) MarshalJSON ¶ added in v0.3.0
func (d Definition) MarshalJSON() ([]byte, error)
MarshalJSON refuses definition export with ErrUnsupported. Declaration explicitly exports CDL only.
func (*Definition) UnmarshalJSON ¶ added in v0.3.0
func (d *Definition) UnmarshalJSON([]byte) error
UnmarshalJSON refuses definition import with ErrUnsupported, leaving the value intact.
type Mapping ¶
type Mapping struct {
// contains filtered or unexported fields
}
Mapping is an immutable map operation. Operations run in declaration order.
func Translate ¶
func Translate(target, source string, entries ...Translation) Mapping
Translate maps values in order; duplicate entries are retained like C#. Targets must be nonempty CDL word tokens (letters, digits, underscores and Unicode word characters), not quoted literals or paths.
type Scope ¶
type Scope struct {
// contains filtered or unexported fields
}
Scope is an immutable nested/child set of map operations and append rules. NewScope copies slices; contained values are themselves immutable.
func NewScope ¶
func NewScope(mappings []Mapping, appends ...AppendRule) Scope
NewScope constructs a scope without nested scopes (matching C#).
type Service ¶
type Service struct {
// contains filtered or unexported fields
}
Service submits explicit capture declarations through authoritative CDL RPCs. It is concurrency-safe, borrows its connection, never retries writes and never starts a capture. Saving is not activation or proof that a source can be read.
func (*Service) Save ¶
func (s *Service) Save(ctx context.Context, d Definition) error
Save submits an explicit definition under its stable ID, without activating. The kernel can save an inactive definition and then return ValidationError; retain d.ID() to correct or remove it. A transport error has an unknown outcome. Source authorization returns ErrUnsupported before dispatch, regardless of ctx; no definition is persisted when authorization cannot be carried by the transport.
func (*Service) Validate ¶
func (s *Service) Validate(ctx context.Context, d Definition) error
Validate checks syntax and runtime capability without persisting or activating. References to missing external services or event types fail explicitly. Source authorization returns ErrUnsupported before dispatch, even if ctx is canceled: this transport carries CDL only and cannot preserve credentials.
type Source ¶
type Source struct {
// contains filtered or unexported fields
}
Source is an immutable, redacted source declaration. Zero is invalid. Copies are safe for concurrent use. JSON import/export fails with ErrUnsupported.
func API ¶
API refers to an external HTTP service by name. Poll uses kernel units s/m/h/d; an empty interval or route is preserved for server validation, like C#.
func MessageTopic ¶
MessageTopic declares a topic. The pinned kernel cannot run message sources.
func Webhook ¶
func Webhook(path string, options ...WebhookOption) Source
Webhook declares an inbound path and optional authorization. Nil options, blank credential values and multiple authorization options fail at Build. Authorization is never embedded in CDL; Validate/Save refuse authorized definitions with ErrUnsupported. The pinned kernel cannot run webhook sources.
func (Source) Authorization ¶ added in v0.3.0
func (s Source) Authorization() (SourceAuthorization, bool)
Authorization returns an immutable value and whether authorization was supplied, not whether the source is valid. Blank values or multiple options are rejected by Build. No options (including the zero source) means absent, not an explicitly supplied None.
func (Source) MarshalJSON ¶ added in v0.3.0
MarshalJSON refuses source export with ErrUnsupported, never silently losing authorization.
func (*Source) UnmarshalJSON ¶ added in v0.3.0
UnmarshalJSON refuses source import with ErrUnsupported, leaving the value intact.
type SourceAuthorization ¶ added in v0.3.0
type SourceAuthorization struct {
// contains filtered or unexported fields
}
SourceAuthorization is an immutable, redacted authorization value. Its zero value represents None. Construct present values through Webhook options. Copies are safe for concurrent use. JSON import/export fails with ErrUnsupported; no public credential export or decoder is provided.
func (SourceAuthorization) Format ¶ added in v0.3.0
func (a SourceAuthorization) Format(state fmt.State, _ rune)
Format redacts all configuration for every fmt verb.
func (SourceAuthorization) Kind ¶ added in v0.3.0
func (a SourceAuthorization) Kind() AuthorizationKind
Kind returns the scheme; the zero value returns AuthorizationNone.
func (SourceAuthorization) LogValue ¶ added in v0.3.0
func (a SourceAuthorization) LogValue() slog.Value
LogValue redacts authorization in structured logs.
func (SourceAuthorization) MarshalJSON ¶ added in v0.3.0
func (a SourceAuthorization) MarshalJSON() ([]byte, error)
MarshalJSON refuses credential export with ErrUnsupported.
func (*SourceAuthorization) UnmarshalJSON ¶ added in v0.3.0
func (a *SourceAuthorization) UnmarshalJSON([]byte) error
UnmarshalJSON refuses all input with ErrUnsupported, leaving the value intact. Unknown or missing discriminators must never downgrade credentials to None.
type Translation ¶
type Translation struct{ From, To string }
Translation is an ordered literal-string translation pair.
type ValidationError ¶
type ValidationError struct {
// Messages is a detached list of kernel diagnostic text. It may contain
// declaration literals; treat it as sensitive and do not log it indiscriminately.
Messages []string
}
ValidationError preserves capture-specific compiler/capability diagnostics, including failures returned in an otherwise successful command envelope. Save can persist an inactive definition before reporting these diagnostics.
func (*ValidationError) Error ¶
func (e *ValidationError) Error() string
type WebhookOption ¶ added in v0.3.0
type WebhookOption func(*webhookConfiguration)
WebhookOption configures an inbound source. Nil, blank credentials or more than one authorization option fail at Build with ErrInvalidConfiguration. No option means absent authorization, not an explicit None value.
func WithBasicAuth ¶ added in v0.3.0
func WithBasicAuth(username, password string) WebhookOption
WithBasicAuth authors inbound username/password authorization. Values are preserved verbatim; blank values fail at Build. It cannot yet be submitted.
func WithBearerToken ¶ added in v0.3.0
func WithBearerToken(token string) WebhookOption
WithBearerToken authors inbound bearer authorization. A blank token fails at Build. It cannot yet be submitted to the CDL-only capture transport.
Example ¶
package main
import (
"fmt"
"strings"
"github.com/cratis/chronicle.go/captures"
)
func main() {
definition, err := new(captures.Builder).
From(captures.Webhook("/synthetic-capture", captures.WithBearerToken("synthetic-token"))).
Key("id").Build("SyntheticCapture")
if err != nil {
fmt.Println("configuration failed")
return
}
authorization, present := definition.Authorization()
fmt.Println(authorization.Kind(), present)
fmt.Println(strings.Contains(definition.Declaration(), "synthetic-token"))
}
Output: bearer true false
func WithOAuth ¶ added in v0.3.0
func WithOAuth(authority, clientID, clientSecret string) WebhookOption
WithOAuth authors inbound authority/client credentials authorization, without contacting an authority. Blank values fail at Build. It cannot yet be submitted.
Source Files