Documentation
¶
Index ¶
Constants ¶
This section is empty.
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") )
Functions ¶
This section is empty.
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 EventEmitterClient ¶
type EventEmitterClient struct {
// contains filtered or unexported fields
}
EventEmitterClient creates ToolEvents and persists them to the local WAL.
func NewEventEmitterClient ¶
func NewEventEmitterClient(toolName string, toolVersion string, opts ...SyncOption) (*EventEmitterClient, error)
NewEventEmitterClient creates a new emit-only client.
The client validates tool metadata, opens the local WAL, and requires no transport or endpoint identity. WithBatchSize is accepted because SyncOption is shared with SyncClient, but it has no effect on emit-only behavior.
type EventTransport ¶
type EventTransport interface {
Send(ctx context.Context, req *servicev1.SyncEventsRequest) (*servicev1.SyncEventsResponse, error)
CheckIn(ctx context.Context, req *servicev1.CheckInRequest) (*servicev1.CheckInResponse, 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) CheckIn ¶
func (c *SyncClient) CheckIn(ctx context.Context) error
CheckIn reports endpoint presence to the server without events. The caller decides when to call it; this client holds no cooldown state. An Unimplemented error means an older server: the caller should treat it as a soft failure.
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
Source Files