search

type Facet struct {
	Name      string       `json:"facet"`
	Values    []FacetValue `json:"values"`
	Truncated bool         `json:"truncated"` // more distinct values exist than returned
}

type FacetValue struct {
	Value string `json:"value"`
	Count int64  `json:"count"`
}

type FacetsInfo struct {
	GQL       string `json:"gql"`
	Mode      string `json:"mode"`
	TookMs    int64  `json:"took_ms"`
	MaxValues int    `json:"max_values"`
}

type FacetsQuery struct {
	// GQL is the raw filter expression (required; same language as
	// search — an empty filter is NOT allowed, facets always narrow).
	GQL string
	// Mode: "service" (default) or "asset" — mirrors search.
	Mode string
	// Timeout: 0 = the service default.
	Timeout time.Duration
	// MaxValues per facet: 0 = DefaultFacetValues; hard cap
	// MaxFacetValues.
	MaxValues int
	// Facets: which dimensions to compute; empty = all of them.
	Facets []string
}

type FacetsResult struct {
	Facets []Facet    `json:"facets"`
	Query  FacetsInfo `json:"query"`
}

type IndexMeta struct {
	Assets       int64      `json:"assets"`
	Services     int64      `json:"services"`
	Observations int64      `json:"observations"`
	FixtureObs   int64      `json:"fixture_observations"`
	LastObserved *time.Time `json:"last_observed_at,omitempty"`
	FixtureOnly  bool       `json:"fixture_only"`
	Empty        bool       `json:"empty"`
}

type Query struct {
	// GQL is the raw query text (required).
	GQL string
	// Mode: "service" (default, PD-1) or "asset".
	Mode string
	// Sort: comma-separated "field:dir" pairs (dir asc|desc, optional).
	// Empty = server default (last_seen DESC).
	Sort string
	// Limit: 0 = default.
	Limit int
	// Timeout: 0 = default.
	Timeout time.Duration
	// Cursor: opaque pagination cursor from a prior Result.
	Cursor string
	// Fields: optional projection (canonical paths or column names).
	Fields []string
	// WithStats: attach index freshness metadata to the Result.
	WithStats bool
}

type QueryError struct {
	Code   string
	Detail string
	Why    string
	Next   string
}

type QueryInfo struct {
	GQL       string             `json:"gql"`
	Mode      string             `json:"mode"`
	Branch    string             `json:"branch"`
	Limit     int                `json:"limit"`
	TimeoutMs int64              `json:"timeout_ms"`
	Sort      []planner.SortSpec `json:"sort"`
	TookMs    int64              `json:"took_ms"`
	RowCount  int                `json:"row_count"`
	// Fixtures is true when the index the query ran against is
	// fixture-labeled (copied from Index when WithStats was set).
	Fixtures bool `json:"fixtures"`
}

type Result struct {
	Rows []Row
	// NextCursor is the cursor for the next page, "" when exhausted.
	// Derived from the LAST row (sort value + composite row key), so
	// callers must not build it themselves.
	NextCursor string
	// HasMore is len(rows) == the effective limit (keyset pagination
	// heuristic; one extra round-trip on the tail page is avoided).
	HasMore bool
	// Query describes how the query was compiled (mode, branch, took).
	Query QueryInfo
	// Index carries freshness metadata when Query.WithStats was set.
	Index *IndexMeta
	// Explain carries the rendered plan when requested (Query flag via
	// the Explain result field on the CLI path; see Plan()).
	Explain string
	// Notice is a caller-facing notice (e.g. empty index guidance,
	// fixture-data label).  Never empty when the index needs context.
	Notice string
}

type Row struct {
	RowID   int64  `json:"row_id"`
	RowKind string `json:"row_kind"` // service | asset-only
	AssetID int64  `json:"asset_id"`

	AssetKind  string `json:"asset_kind"` // ip | domain | hostname
	AssetValue string `json:"asset_value"`

	IP       *string `json:"ip,omitempty"`
	Domain   *string `json:"domain,omitempty"`
	Hostname *string `json:"hostname,omitempty"`

	ASN    *int    `json:"asn,omitempty"`
	ASNOrg *string `json:"asn_org,omitempty"`

	GeoCountry *string `json:"geo_country,omitempty"`
	GeoRegion  *string `json:"geo_region,omitempty"`
	GeoCity    *string `json:"geo_city,omitempty"`

	Port      *int    `json:"port,omitempty"`
	Transport *string `json:"transport,omitempty"`
	Protocol  *string `json:"protocol,omitempty"`
	Name      *string `json:"name,omitempty"`
	Product   *string `json:"product,omitempty"`
	Version   *string `json:"version,omitempty"`

	HTTPStatus *int    `json:"http_status,omitempty"`
	HTTPTitle  *string `json:"http_title,omitempty"`
	HTTPServer *string `json:"http_server,omitempty"`

	TLSVersion       *string    `json:"tls_version,omitempty"`
	TLSCertSubjectCN *string    `json:"tls_cert_subject_cn,omitempty"`
	TLSCertIssuerCN  *string    `json:"tls_cert_issuer_cn,omitempty"`
	TLSCertExpiry    *time.Time `json:"tls_cert_expiry,omitempty"`

	Technologies []string `json:"technologies,omitempty"`
	Sources      []string `json:"sources,omitempty"`

	FirstSeen time.Time `json:"first_seen"`
	LastSeen  time.Time `json:"last_seen"`
	Stale     bool      `json:"stale"`
	// contains filtered or unexported fields
}

type Service struct {

	// Defaults (PD-1 and SPEC-03 §3); a Query's explicit values win.
	DefaultMode    planner.Mode
	DefaultLimit   int
	DefaultTimeout time.Duration
	// contains filtered or unexported fields
}

type TimeoutError struct{ Err error }

type UnavailableError struct{ Err error }