endpointsync

Documentation

Index

• Variables
• type EndpointIdentityOption
  • func WithEndpointID(id string) EndpointIdentityOption
• type EndpointIdentityResolver
  • func NewEndpointIdentityResolver(opts ...EndpointIdentityOption) EndpointIdentityResolver
• type EventTransport
  • func NewGrpcTransport(conn *grpc.ClientConn) EventTransport
• type SyncClient
  • func NewSyncClient(toolName string, toolVersion string, transport EventTransport, ...) (*SyncClient, error)
  • func (c *SyncClient) Close() error
  • func (c *SyncClient) Emit(ctx context.Context, event *servicev1.ToolEvent) error
  • func (c *SyncClient) NewEvent() (*servicev1.ToolEvent, error)
  • func (c *SyncClient) Sync(ctx context.Context) (int, error)
• type SyncOption
  • func WithBatchSize(n int) SyncOption
  • func WithMaxPending(n int) SyncOption
  • func WithWALPath(path string) SyncOption

Variables

var (
	// ErrMissingTransport is returned when no transport is provided.
	ErrMissingTransport = errors.New("endpointsync: transport is required")

	// ErrMissingIdentity is returned when no identity resolver is provided.
	ErrMissingIdentity = errors.New("endpointsync: identity resolver is required")

	// ErrWALOpen is returned when the WAL database cannot be opened.
	ErrWALOpen = errors.New("endpointsync: failed to open WAL database")

	// ErrWALFull is returned by Emit() when pending events reach MaxPending.
	// Tools must handle this gracefully and continue operating without sync.
	ErrWALFull = errors.New("endpointsync: WAL is full, sync required before emitting more events")
)

Types

type EndpointIdentityOption

type EndpointIdentityOption func(*defaultEndpointIdentityResolver)

EndpointIdentityOption configures the default identity resolver.

func WithEndpointID

func WithEndpointID(id string) EndpointIdentityOption

WithEndpointID sets an operator-provided endpoint identifier.

When set, this value becomes the source of truth for endpoint identity: it is used as the human-readable Identifier and the MachineId is derived from it via HMAC-SHA256 instead of being read from the host. This yields a stable identity across machines, which is required for ephemeral environments such as CI/CD runners where the system machine ID changes every run.

The provided ID must be unique per logical endpoint unless sharing the same backend identity is intentional. If two different hosts or runners are configured with the same endpoint ID, they will produce the same MachineId and be treated as the same endpoint by the backend.

If not set or empty, the resolver falls back to hostname for the Identifier and uses the host's machine ID for MachineId.

type EndpointIdentityResolver

type EndpointIdentityResolver interface {
	Resolve() (*controltowerv1.EndpointIdentity, error)
}

EndpointIdentityResolver resolves the endpoint identity for sync.

func NewEndpointIdentityResolver

func NewEndpointIdentityResolver(opts ...EndpointIdentityOption) EndpointIdentityResolver

NewEndpointIdentityResolver creates a default identity resolver.

type EventTransport

type EventTransport interface {
	Send(ctx context.Context, req *servicev1.SyncEventsRequest) (*servicev1.SyncEventsResponse, error)
	Close() error
}

EventTransport abstracts the sync delivery mechanism.

func NewGrpcTransport

func NewGrpcTransport(conn *grpc.ClientConn) EventTransport

NewGrpcTransport creates a transport that sends events via unary gRPC calls to EndpointService.SyncEvents.

type SyncClient

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

SyncClient handles reliable event sync to SafeDep Cloud.

func NewSyncClient

func NewSyncClient(toolName string, toolVersion string, transport EventTransport, identity EndpointIdentityResolver, opts ...SyncOption) (*SyncClient, error)

NewSyncClient creates a new sync client.

• toolName: tool identifier (e.g., "pmg", "gryph"). Used for WAL path (os.UserConfigDir()/safedep/<toolName>/sync.db) and internal logging/telemetry. Must be lowercase alphanumeric with hyphens only.
• toolVersion: tool version (e.g., "1.2.3"). Included in every event for debugging and telemetry. Must not be empty.
• transport: pre-configured delivery mechanism for sending events to SafeDep Cloud.
• identity: resolves endpoint identity (identifier + metadata) for sync requests.
• opts: optional overrides (WithBatchSize, WithMaxPending, WithWALPath).

func (*SyncClient) Close

func (c *SyncClient) Close() error

Close releases resources.

func (*SyncClient) Emit

func (c *SyncClient) Emit(ctx context.Context, event *servicev1.ToolEvent) error

Emit persists a ToolEvent to the local WAL.

func (*SyncClient) NewEvent

func (c *SyncClient) NewEvent() (*servicev1.ToolEvent, error)

NewEvent creates a ToolEvent with pre-filled fields.

func (*SyncClient) Sync

func (c *SyncClient) Sync(ctx context.Context) (int, error)

Sync delivers pending events from the WAL to the server.

type SyncOption

type SyncOption func(*syncConfig)

SyncOption configures optional sync client behavior.

func WithBatchSize

func WithBatchSize(n int) SyncOption

WithBatchSize sets events per batch in Sync(). Default: 100. Maximum: 100 (the proto enforces max_items: 100 on SyncEventsRequest.events).

func WithMaxPending

func WithMaxPending(n int) SyncOption

WithMaxPending sets the WAL pending event limit. Default: 100000. Emit() returns ErrWALFull when reached.

func WithWALPath

func WithWALPath(path string) SyncOption

WithWALPath overrides the default WAL path. Default: os.UserConfigDir()/safedep/<name>/sync.db