ctlogs

type Backoff ¶

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

Backoff implements an exponential back-off with optional jitter and a maximum cap. It is goroutine-safe if each goroutine uses its own instance.

Zero value is ready to use with default parameters (base 500ms, factor 2.0, max 60s).

Call Next() to obtain the next wait duration. Call Reset() after a successful attempt to restart.

The implementation purposefully avoids floats at runtime by using pre-scaled integers.

func NewBackoff(base, max time.Duration) Backoff

func (b *Backoff) Next() time.Duration

func (b *Backoff) Reset()

type CTLogClient ¶

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

CTLogClient is a thin wrapper over certificate-transparency-go's LogClient with room for future enhancements such as rate-limiting/back-off, statistics and instrumentation. It is safe for concurrent use.

func NewCTLogClient(info CTLogInfo, optFns ...func(*ClientOptions)) (*CTLogClient, error)

func (c *CTLogClient) GetEntries(ctx context.Context, start, end uint64) ([]ct.LogEntry, error)

func (c *CTLogClient) GetSTH(ctx context.Context) (*ct.SignedTreeHead, error)

func (c *CTLogClient) Info() CTLogInfo

type CTLogEntry ¶

type CTLogEntry struct {
	LeafInput string `json:"leaf_input"`
	ExtraData string `json:"extra_data"`
}

CTLogEntry represents a single CT log entry

type CTLogInfo ¶

type CTLogInfo struct {
	Description string `json:"description"`
	LogID       string `json:"log_id"`
	Key         string `json:"key"`
	URL         string `json:"url"`
	MMD         int    `json:"mmd"` // Maximum Merge Delay
}

CTLogInfo represents a CT log from the official log list

type CTLogList ¶

type CTLogList struct {
	Version   string       `json:"version"`
	Operators []CTOperator `json:"operators"`
}

CTLogList represents the official Google CT log list

type CTLogResponse ¶

type CTLogResponse struct {
	Entries []CTLogEntry `json:"entries"`
}

CTLogResponse represents the response from a CT log API

type CTLogSource ¶

type CTLogSource struct {
	Client     *CTLogClient
	LastSize   uint64
	TreeSize   uint64 // Current tree size from latest STH
	WindowSize uint64 // Sliding window size
}

CTLogSource represents a Certificate Transparency log source

type CTLogsService ¶

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

CTLogsService handles Certificate Transparency logs streaming

func New(optFns ...ServiceOption) (*CTLogsService, error)

func (service *CTLogsService) GetStats() Stats

func (service *CTLogsService) Start()

func (service *CTLogsService) Stop()

type CTOperator ¶

type CTOperator struct {
	Name  string      `json:"name"`
	Email []string    `json:"email"`
	Logs  []CTLogInfo `json:"logs"`
}

CTOperator represents a CT log operator

type ClientOptions ¶

type ClientOptions struct {
	// HTTPClient used for all outbound requests.
	HTTPClient *http.Client

	// MaxBackoff caps the exponential back-off duration (future milestone).
	MaxBackoff time.Duration

	// Sleep allows overriding the sleep behaviour (useful for testing).
	Sleep func(time.Duration)
}

ClientOptions controls behaviour of a CTLogClient. All fields are optional – sensible defaults are applied when a value is not supplied.

type EntryCallback ¶

type EntryCallback func(meta EntryMeta, certData []byte, duplicate bool)

EntryCallback is invoked for every certificate observed (after dedup phase).

duplicate indicates whether the certificate is *likely* a duplicate according to the inverse bloom filter (always false before Milestone 2).

type EntryMeta ¶

type EntryMeta struct {
	SourceID       string // normalized source identifier
	SourceDesc     string // human-readable log description
	LogURL         string // CT log URL for identification
	Index          uint64 // leaf index within the log
	TreeSize       uint64 // total number of entries in the log (head)
	Lag            uint64 // number of pending entries (TreeSize - Index)
	CollectionTime time.Time
}

EntryMeta carries minimal contextual information about a log entry passed to the callback.

type ServiceOption ¶

type ServiceOption func(*ServiceOptions)

ServiceOption mutates a ServiceOptions instance.

func WithCallback(cb EntryCallback) ServiceOption

func WithCert(c bool) ServiceOption

func WithCustomStartIndex(logID string, idx uint64) ServiceOption

func WithCustomStartIndices(m map[string]uint64) ServiceOption

func WithDedupeSize(sz int) ServiceOption

func WithPollInterval(d time.Duration) ServiceOption

func WithStartBeginning() ServiceOption

func WithStartNow() ServiceOption

func WithVerbose(v bool) ServiceOption

type ServiceOptions ¶

type ServiceOptions struct {
	Verbose bool
	Cert    bool // include PEM in callback

	PollInterval time.Duration

	// Size of the inverse bloom filter (number of buckets).
	// Larger values reduce false negatives. Default 1,000,000.
	DedupeSize int

	// Stream start behaviour.
	StartMode          StartMode
	CustomStartIndices map[string]uint64 // by log URL or ID

	Callback EntryCallback
}

ServiceOptions configures a CTLogsService instance.

The struct should remain stable; always prefer adding new functional option helpers instead of exposing fields.

type StartMode ¶

type StartMode int

StartMode defines where the service should begin streaming from.

Beginning: from index 0 Now: from log's current tree size (default) Custom: per-log custom indices provided by the caller.

const (
	StartNow StartMode = iota // default behaviour
	StartBeginning
	StartCustom
)

type Stats ¶

type Stats struct {
	Total      uint64 `json:"total"`
	Unique     uint64 `json:"unique"`
	Duplicates uint64 `json:"duplicates"`
	Retries    uint64 `json:"retries"`
}

Stats represents a snapshot of service metrics.