events

Documentation

Overview

* Nuts registry * Copyright (C) 2020. Nuts community * * This program is free software: you can redistribute it and/or modify * it under the terms of the GNU General Public License as published by * the Free Software Foundation, either version 3 of the License, or * (at your option) any later version. * * This program is distributed in the hope that it will be useful, * but WITHOUT ANY WARRANTY; without even the implied warranty of * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the * GNU General Public License for more details. * * You should have received a copy of the GNU General Public License * along with this program. If not, see <https://www.gnu.org/licenses/>. *

* Nuts registry * Copyright (C) 2020. Nuts community * * This program is free software: you can redistribute it and/or modify * it under the terms of the GNU General Public License as published by * the Free Software Foundation, either version 3 of the License, or * (at your option) any later version. * * This program is distributed in the hope that it will be useful, * but WITHOUT ANY WARRANTY; without even the implied warranty of * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the * GNU General Public License for more details. * * You should have received a copy of the GNU General Public License * along with this program. If not, see <https://www.gnu.org/licenses/>. *

Index

• Variables
• func SuggestEventFileName(event Event) string
• type Event
  • func CreateEvent(eventType EventType, payload interface{}, previousEvent Ref) Event
  • func EventFromJSON(data []byte) (Event, error)
  • func EventFromJSONWithIssuedAt(data []byte, issuedAt time.Time) (Event, error)
  • func EventsFromJSON(data []byte) ([]Event, error)
• type EventHandler
• type EventLookup
• type EventMatcher
• type EventRegistrar
• type EventSystem
  • func NewEventSystem(eventTypes ...EventType) EventSystem
• type EventType
• type JwsVerifier
• type Ref
  • func (r Ref) Equal(other Ref) bool
  • func (r Ref) IsZero() bool
  • func (r Ref) MarshalJSON() ([]byte, error)
  • func (r Ref) String() string
  • func (r *Ref) UnmarshalJSON(data []byte) error
• type SignatureDetails
• type SignatureValidator
  • func NewSignatureValidator(verifier JwsVerifier, certVerifier cert.Verifier) SignatureValidator
  • func (v SignatureValidator) RegisterEventHandlers(fn EventRegistrar, eventType []EventType)
• type TrustStore
• type UnmarshalPostProcessor
• type Version

Variables

var ErrEventNotSigned = errors.New("the event is not signed")

ErrEventNotSigned is returned when the event is not signed

var ErrEventSystemNotConfigured = errors.New("the event system hasn't been configured, please call Configure()")

ErrEventSystemNotConfigured is returned when the event system is used but wasn't configured by calling Configure()

var ErrInvalidTimestamp = errors.New("event timestamp does not match required pattern (yyyyMMddHHmmssmmm)")

ErrInvalidTimestamp is returned when a timestamp does not match the required pattern

var ErrMissingEventType = errors.New("unmarshalling error: missing event type")

ErrMissingEventType is given when the event being unmarshalled has no type attribute.

Functions

func SuggestEventFileName

func SuggestEventFileName(event Event) string

SuggestEventFileName suggests a file name for a event, when writing that event to disk.

Types

type Event

type Event interface {
	Type() EventType
	IssuedAt() time.Time
	// Version holds the version of the event, which can be used for differentiate processing/ignoring legacy events
	Version() Version
	// Ref holds the reference to the current event
	Ref() Ref
	// PreviousRef holds the reference to the previous event
	PreviousRef() Ref
	Unmarshal(out interface{}) error
	Marshal() []byte
	Signature() []byte
	SignatureDetails() SignatureDetails
	Sign(signFn func([]byte) ([]byte, error)) error
}

Event defines an event which can be (un)marshalled.

func CreateEvent

func CreateEvent(eventType EventType, payload interface{}, previousEvent Ref) Event

CreateEvent creates an event of the given type and the provided payload.

func EventFromJSON

func EventFromJSON(data []byte) (Event, error)

EventFromJSON unmarshals an event. If the event can't be unmarshalled, an error is returned.

func EventFromJSONWithIssuedAt

func EventFromJSONWithIssuedAt(data []byte, issuedAt time.Time) (Event, error)

EventFromJSONWithIssuedAt functions exactly as EventFromJSON but allows the caller to set issuedAt if it's not present in the event which is the case for v0 events. If it's present, the supplied issuedAt is ignored.

func EventsFromJSON

func EventsFromJSON(data []byte) ([]Event, error)

EventsFromJSON is the same as EventsFromJSON except that it unmarshals a list of events rather than a single event.

type EventHandler

type EventHandler func(Event, EventLookup) error

EventHandler handles an event of a specific type.

type EventLookup

type EventLookup interface {
	// Get retrieves the event specified the reference. If the event doesn't exist, nil is returned.
	Get(ref Ref) Event
	// FindLastEvent finds the last event in the event path which matches the specified matcher. If there are multiple
	// event paths that match, an error is returned. If no events match, nil is returned.
	FindLastEvent(matcher EventMatcher) (Event, error)
}

type EventMatcher

type EventMatcher func(Event) bool

EventMatcher defines a matching function for events. The function should return true if the event matches, otherwise false.

type EventRegistrar

type EventRegistrar func(EventType, EventHandler)

EventRegistrar is a function to register an event

type EventSystem

type EventSystem interface {
	// RegisterEventHandler registers an event handler for the given type, which will be called when the an event of this
	// type is received.
	RegisterEventHandler(eventType EventType, handler EventHandler)
	ProcessEvent(event Event) error
	PublishEvent(event Event) error
	LoadAndApplyEvents() error
	Configure(location string) error
	Diagnostics() []core.DiagnosticResult
	EventLookup
}

EventSystem is meant for registering and handling events.

func NewEventSystem

func NewEventSystem(eventTypes ...EventType) EventSystem

NewEventSystem creates and initializes a new event system.

type EventType

type EventType string

EventType defines a supported type of event, which is used for executing the right handler.

type JwsVerifier

type JwsVerifier func(signature []byte, signingTime time.Time, verifier cert.Verifier) ([]byte, error)

JwsVerifier defines a verification delegate for JWS'.

type Ref

type Ref []byte

EventRef is a reference to an event

func (Ref) Equal

func (r Ref) Equal(other Ref) bool

func (Ref) IsZero

func (r Ref) IsZero() bool

func (Ref) MarshalJSON

func (r Ref) MarshalJSON() ([]byte, error)

func (Ref) String

func (r Ref) String() string

func (*Ref) UnmarshalJSON

func (r *Ref) UnmarshalJSON(data []byte) error

type SignatureDetails

type SignatureDetails struct {
	// Certificate contains the X.509 certificate that signed the event
	Certificate *x509.Certificate
	// Payload contains the event data that is protected by the signature
	Payload []byte
}

SignatureDetails describes the properties of the signature that secures the event

type SignatureValidator

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

SignatureValidator validates event signatures.

func NewSignatureValidator

func NewSignatureValidator(verifier JwsVerifier, certVerifier cert.Verifier) SignatureValidator

NewSignatureValidator creates a new SignatureValidator for the given event types.

func (SignatureValidator) RegisterEventHandlers

func (v SignatureValidator) RegisterEventHandlers(fn EventRegistrar, eventType []EventType)

RegisterEventHandlers registers event handlers which will validate the event signatures.

type TrustStore

type TrustStore interface {
	// Verify verifies the given certificate. The validity of the certificate is checked against the given moment in time.
	Verify(*x509.Certificate, time.Time) error
	RegisterEventHandlers(func(EventType, EventHandler))
}

type UnmarshalPostProcessor

type UnmarshalPostProcessor interface {
	PostProcessUnmarshal(event Event) error
}

UnmarshalPostProcessor allows to define custom logic that should be executed after unmarshalling

type Version

type Version int

Version