collect

type BadRecord struct {
	Raw    RawFact
	Reason string
}

type Batch struct {
	Raws   []RawFact
	Cursor string
	Done   bool
	// Notes are connector-reported counters surfaced in the job stats.
	Notes map[string]int
}

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

type ClientConfig struct {
	// RequestsPerSecond caps the request rate (0 = DefaultRPS).
	RequestsPerSecond float64
	// Timeout bounds one request (0 = DefaultTimeout).
	Timeout time.Duration
	// MaxBodyBytes bounds one response body (0 = DefaultMaxBodyBytes).
	MaxBodyBytes int64
	// UserAgent identifies GSEER honestly (0 value = DefaultUserAgent).
	UserAgent string
}

type Collector interface {
	// Kind is the connector type ("dns", "rdap", "asn", "ct").
	Kind() string
	// Review is the terms-compliance verdict (see doc.go contract 2).
	Review() Review
	// Collect runs one passive pass and returns the batch.  A connector
	// NEVER ingests: it only produces facts (the Runner owns ingestion,
	// checkpoints, dead letters and job bookkeeping).
	Collect(ctx Ctx) (*Batch, error)
}

type Ctx struct {
	Context context.Context // the run's context; never nil from the Runner
	Source  SourceRef
	Config  SourceConfig
	Cursor  string
	Limit   int     // per-run record budget (0 = DefaultRunLimit)
	Client  *Client // shared rate-limited HTTP client
	// IndexSeeds loads seed identifiers already in the index (seed_mode
	// "index"): no third-party target lists are ever used.
	IndexSeeds func(kind string, limit int) ([]string, error)
	// Now is injectable for tests.
	Now func() time.Time
}

type Fact = storage.Fact

type FatalError struct{ Err error }

type RawFact struct {
	AssetKind  string // "ip" | "domain" | "hostname"
	Value      string // raw surface form; canonicalized by the pipeline
	ObservedAt time.Time
	Confidence string // "high" | "medium" (provider-dependent)

	// Enrichment fields (asset metadata the upsert merges without
	// blanking stored values): the ASN/BGP connector fills ASN/ASNOrg/
	// GeoCountry; RDAP fills GeoCountry.  They ride on the asset row —
	// never invented beyond what the provider stated.
	ASN        int
	ASNOrg     string
	GeoCountry string

	// Extra lands inside observation.evidence under the connector's key.
	Extra map[string]any
}

type RedriveOptions struct {
	// SourceID restricts to one source; 0 = all sources.
	SourceID int64
	// Limit bounds the pass (0 = 500).
	Limit int
	// Discard marks the pending rows discarded instead of re-driving.
	Discard bool
}

type RedriveStats struct {
	Considered   int `json:"considered"`
	Redriven     int `json:"redriven"`      // ingestion attempted
	Resolved     int `json:"resolved"`      // applied successfully
	StillFailing int `json:"still_failing"` // attempted, failed again (kept pending, attempts bumped)
	Suppressed   int `json:"suppressed"`    // refused by the suppression gate (kept pending)
	Discarded    int `json:"discarded"`     // only with Discard
}

type Review struct {
	// Verdict is "reviewed-enabled" (clear compatible terms: the
	// connector may be enabled by the operator) or "disabled"
	// (credentials/payment/unclear permission for indexing or reuse —
	// the runner refuses to run it, period).
	Verdict string `json:"verdict"`
	// Why is the one-line justification (what the terms say or lack).
	Why string `json:"why"`
	// DocRef anchors the full review in docs/SOURCES.md.
	DocRef string `json:"doc_ref"`
}

type RunStats struct {
	Source     string `json:"source"`
	Connector  string `json:"connector"`
	JobID      int64  `json:"job_id"`
	Records    int    `json:"records"`
	Facts      int    `json:"facts"`
	Ingested   int    `json:"ingested"`
	Updated    int    `json:"updated"`
	Deduped    int    `json:"deduped"`
	Suppressed int    `json:"suppressed"`
	DeadLetter int    `json:"dead_lettered"`
	Batches    int    `json:"batches"`
	Cursor     string `json:"cursor"`
	Done       bool   `json:"done"`
	// Skipped is set (with the reason) when nothing ran.
	Skipped string `json:"skipped,omitempty"`
}

type Runner struct {
	Store  *postgres.Store
	Client *Client // shared default client (per-source config may override)

	// Now is injectable for tests; zero value = time.Now.
	Now func() time.Time
	// MaxAttempts bounds transport retries per batch (0 = DefaultMaxAttempts).
	MaxAttempts int
	// Backoff is the base delay between retries, doubled per attempt
	// (0 = DefaultBackoff).
	Backoff time.Duration
	// MaxBatches bounds one run's batch loop (0 = DefaultMaxBatches) —
	// a stuck cursor must not spin forever.
	MaxBatches int
	// contains filtered or unexported fields
}

type SourceConfig struct {
	// Endpoint is the provider's API base URL (HTTP connectors).
	Endpoint string `json:"endpoint,omitempty" yaml:"endpoint,omitempty"`
	// Seeds are operator-configured identifiers (seed_mode "config").
	Seeds []string `json:"seeds,omitempty" yaml:"seeds,omitempty"`
	// SeedMode: "config" (use Seeds) or "index" (use identifiers already
	// in the GSEER index — the connector enriches the operator's own
	// corpus; it never consults a third-party target list).
	SeedMode string `json:"seed_mode,omitempty" yaml:"seed_mode,omitempty"`
	// SeedKind is the asset kind index seeds are drawn from
	// ("ip" for rdap/asn enrichment; unused for "config" mode).
	SeedKind string `json:"seed_kind,omitempty" yaml:"seed_kind,omitempty"`
	// Resolver is an optional DNS server address ("host:port") for the
	// dns/asn connectors; empty = the system resolver.
	Resolver string `json:"resolver,omitempty" yaml:"resolver,omitempty"`
	// RequestsPerSecond caps the HTTP client (0 = connector default).
	RequestsPerSecond float64 `json:"requests_per_second,omitempty" yaml:"requests_per_second,omitempty"`
	// TimeoutMs bounds one provider request (0 = connector default).
	TimeoutMs int `json:"timeout_ms,omitempty" yaml:"timeout_ms,omitempty"`
	// LimitPerRun bounds one run's record budget (0 = DefaultRunLimit).
	LimitPerRun int `json:"limit_per_run,omitempty" yaml:"limit_per_run,omitempty"`
}

type SourceRef struct {
	ID   int64
	Name string
}