components

Documentation

Index

• Constants
• Variables
• type ActorHostType
• type ActorProvider
• type FetchAndLeaseUpcomingAlarmsReq
• type GetAlarmRes
• type GetLeasedAlarmRes
• type LookupActorOpts
• type LookupActorRes
• type ProviderConfig
  • func (o *ProviderConfig) Validate() error
• type ProviderOptions
• type RegisterHostReq
• type RegisterHostRes
• type RenewAlarmLeasesReq
• type RenewAlarmLeasesRes
• type SetAlarmReq
• type SetStateOpts
• type UpdateActorHostReq
• type UpdateLeasedAlarmReq

Constants

const (
	DefaultHostHealthCheckDeadline  = 20 * time.Second
	DefaultAlarmsLeaseDuration      = 20 * time.Second
	DefaultAlarmsFetchAheadInterval = 2500 * time.Millisecond
	DefaultAlarmsFetchAheadBatch    = 25
)

Variables

var (
	ErrAlreadyRunning        = errors.New("already running")
	ErrHostAlreadyRegistered = errors.New("another host is already registered at the same address")
	ErrHostUnregistered      = errors.New("host is not registered")
	ErrNoHost                = errors.New("could not find a suitable host for this actor")
	ErrNoActor               = errors.New("actor does not exist")
	ErrNoAlarm               = errors.New("alarm does not exist")
	ErrNoState               = errors.New("no state found for the actor")
)

Types

type ActorHostType

type ActorHostType struct {
	// Actor type
	ActorType string
	// Idle timeout for the actor type
	// A negative value means no timeout
	IdleTimeout time.Duration
	// Maximum number of actors of the given type active on the current host
	// Set to 0 for no limit
	ConcurrencyLimit int32
	// Actor deactivation timeout
	DeactivationTimeout time.Duration
	// Maximum number of attempts when invoking the actor or executing alarms
	MaxAttempts int
	// Initial retry delay after failed invocation attempts
	InitialRetryDelay time.Duration
}

ActorHostType references a supported actor type.

type ActorProvider

type ActorProvider interface {
	// Init the actor provider
	Init(ctx context.Context) error

	// Run the actor provider
	// This method blocks until the context is canceled
	// If the provider is already running, returns ErrAlreadyRunning
	Run(ctx context.Context) error

	// RegisterHost registers a new actor host.
	// If a host already exists at the same address, returns ErrHostAlreadyRegistered.
	RegisterHost(ctx context.Context, req RegisterHostReq) (RegisterHostRes, error)

	// UpdateActorHost updates the properties for an actor host
	// If the host doesn't exist, returns ErrHostUnregistered.
	UpdateActorHost(ctx context.Context, hostID string, req UpdateActorHostReq) error

	// UnregisterHost unregisters an actor host.
	// If the host doesn't exist, returns ErrHostUnregistered.
	UnregisterHost(ctx context.Context, hostID string) error

	// LookupActor returns the address of the actor host for a given actor type and ID.
	// If the actor is not currently active on any host, a new actor is created and assigned to a random host; if it's not possible to find an instance capable of hosting the given actor, ErrNoHost is returned instead.
	LookupActor(ctx context.Context, ref ref.ActorRef, opts LookupActorOpts) (LookupActorRes, error)

	// RemoveActor removes an actor from the collection of active actors.
	// If the actor doesn't exist, returns ErrNoActor.
	RemoveActor(ctx context.Context, ref ref.ActorRef) error

	// GetAlarm returns an alarm.
	// It returns ErrNoAlarm if it doesn't exist.
	GetAlarm(ctx context.Context, ref ref.AlarmRef) (GetAlarmRes, error)

	// SetAlarm sets or replaces an alarm configured for an actor.
	SetAlarm(ctx context.Context, ref ref.AlarmRef, req SetAlarmReq) error

	// DeleteAlarm removes an alarm configured for an actor.
	// If the alarm doesn't exist, returns ErrNoAlarm.
	DeleteAlarm(ctx context.Context, ref ref.AlarmRef) error

	// FetchAndLeaseUpcomingAlarms fetches the upcoming alarms, acquiring a lease on them.
	FetchAndLeaseUpcomingAlarms(ctx context.Context, req FetchAndLeaseUpcomingAlarmsReq) ([]*ref.AlarmLease, error)

	// RenewAlarmLeases renews the leases for the alarms in the request.
	// The method can renew specific alarm leases and/or those tied to specific hosts.
	RenewAlarmLeases(ctx context.Context, req RenewAlarmLeasesReq) (RenewAlarmLeasesRes, error)

	// ReleaseAlarmLease releases an active lease on an alarm.
	// Returns ErrNoAlarm if the alarm doesn't exist or the lease is not valid.
	ReleaseAlarmLease(ctx context.Context, lease *ref.AlarmLease) error

	// GetLeasedAlarm retrieves an alarm using an alarm lease object.
	// Returns ErrNoAlarm if the alarm doesn't exist or the lease is not valid.
	GetLeasedAlarm(ctx context.Context, lease *ref.AlarmLease) (GetLeasedAlarmRes, error)

	// UpdateLeasedAlarm updates an alarm using an alarm lease object.
	// Returns ErrNoAlarm if the alarm doesn't exist or the lease is not valid.
	UpdateLeasedAlarm(ctx context.Context, lease *ref.AlarmLease, req UpdateLeasedAlarmReq) error

	// DeleteLeasedAlarm deletes an alarm using an alarm lease object.
	// Returns ErrNoAlarm if the alarm doesn't exist or the lease is not valid.
	DeleteLeasedAlarm(ctx context.Context, lease *ref.AlarmLease) error

	// GetState retrieves the persistent state of an actor.
	// If there's no state, returns ErrNoState.
	GetState(ctx context.Context, ref ref.ActorRef) ([]byte, error)

	// SetState sets the persistent state of an actor.
	SetState(ctx context.Context, ref ref.ActorRef, data []byte, opts SetStateOpts) error

	// DeleteState deletes the persistent state of an actor.
	// If there's no state, returns ErrNoState.
	DeleteState(ctx context.Context, ref ref.ActorRef) error

	// HealthCheckInterval returns the recommended health check interval for hosts.
	HealthCheckInterval() time.Duration

	// HealthCheckInterval returns the recommended lease renewal interval for hosts.
	RenewLeaseInterval() time.Duration
}

ActorProvider is the interface implemented by all actor providers

type FetchAndLeaseUpcomingAlarmsReq

type FetchAndLeaseUpcomingAlarmsReq struct {
	// Limits to alarms that can be fetched on these hosts.
	Hosts []string
}

FetchAndLeaseUpcomingAlarmsReq is the request object for the FetchAndLeaseUpcomingAlarms method.

type GetAlarmRes

type GetAlarmRes struct {
	ref.AlarmProperties
}

GetAlarmRes is the response object for the GetAlarm method.

type GetLeasedAlarmRes

type GetLeasedAlarmRes struct {
	ref.AlarmRef
	ref.AlarmProperties
}

GetLeasedAlarmRes is the response object for the GetLeasedAlarm method.

type LookupActorOpts

type LookupActorOpts struct {
	// List of hosts on which the actor can be activated.
	// If the actor is active on a different host, ErrNoActorHost is returned.
	Hosts []string
	// If true, performs a lookup for an actor that's currently active only
	ActiveOnly bool
}

LookupActorOpts contains options for LookupActor.

type LookupActorRes

type LookupActorRes struct {
	// Host ID
	HostID string
	// Host address (including port)
	Address string
	// Actor idle timeout
	// Note: this is the absolute idle timeout, and not the remaining lifetime of the actor
	IdleTimeout time.Duration
}

LookupActorRes is the response object for the LookupActor method.

type ProviderConfig

type ProviderConfig struct {
	// Maximum interval between pings received from an actor host.
	HostHealthCheckDeadline time.Duration

	// Alarms lease duration
	AlarmsLeaseDuration time.Duration

	// Pre-fetch interval for alarms
	AlarmsFetchAheadInterval time.Duration

	// Batch size for pre-fetching alarms
	AlarmsFetchAheadBatchSize int
}

ProviderConfig contains the configuration for the actor provider

func (*ProviderConfig) Validate

func (o *ProviderConfig) Validate() error

type ProviderOptions

type ProviderOptions any

ProviderOptions is an empty interface implemented by all options structs for providers

type RegisterHostReq

type RegisterHostReq struct {
	// Host address, where
	Address string
	// List of supported actor types
	ActorTypes []ActorHostType
}

RegisterHostReq is the request object for the RegisterHost method.

type RegisterHostRes

type RegisterHostRes struct {
	// Auto-generated ID of the actor host
	HostID string
}

RegisterHostRes is the response object for the RegisterHost method.

type RenewAlarmLeasesReq

type RenewAlarmLeasesReq struct {
	// Limits to alarms owned by these hosts.
	Hosts []string
	// Optional list of leases to renew.
	// If this is empty, renews the lease for all alarms on the host.
	Leases []*ref.AlarmLease
}

RenewAlarmLeasesReq is the request object for the RenewAlarmLeases method.

type RenewAlarmLeasesRes

type RenewAlarmLeasesRes struct {
	// List of leases that were successfully renewed.
	Leases []*ref.AlarmLease
}

RenewAlarmLeasesRes is the response object for the RenewAlarmLeases method.

type SetAlarmReq

type SetAlarmReq struct {
	ref.AlarmProperties
}

SetAlarmReq is the request object for the SetAlarm method.

type SetStateOpts

type SetStateOpts struct {
	TTL time.Duration
}

SetStateOpts contains options for SetState

type UpdateActorHostReq

type UpdateActorHostReq struct {
	// Updates last health check time
	// If true, will update the value in the database with the current time
	UpdateLastHealthCheck bool
	// List of supported actor types
	// If non-nil, will replace all existing, registered actor types (an empty, non-nil slice indicates no supported actor types)
	ActorTypes []ActorHostType
}

UpdateActorHostReq is the request object for the UpdateActorHost method.

type UpdateLeasedAlarmReq

type UpdateLeasedAlarmReq struct {
	// Due time.
	DueTime time.Time
	// When true, preserves and refreshes the lease on the alarm.
	// The default behavior is to release the lease.
	RefreshLease bool
}

UpdateLeasedAlarmReq is the request object for the UpdateLeasedAlarm method.