package protocol // Search brokered by the Pipelines server: one query can find a pipeline, a // pipeline version, a run, a recorded step/visit, the text of a step field // (input/output/evidence/transcript) or a recorded artifact. A client sends // Message{Type: Search, ID: , Search: } and the server // echoes the ID with a SearchResults response, matching every other exchange. const ( Search = "search" SearchResults = "search_results" ) // Search.Kind narrowing values. They are the only narrowing mechanism and are // enforced server-side; an empty Kind searches every kind. const ( SearchKindPipeline = "pipeline" SearchKindVersion = "version" SearchKindRun = "run" SearchKindStep = "step" SearchKindField = "field" SearchKindArtifact = "artifact" ) // SearchKinds is the accepted Kind vocabulary in display order; the CLI help // and notes are kept in step with it. var SearchKinds = []string{ SearchKindPipeline, SearchKindVersion, SearchKindRun, SearchKindStep, SearchKindField, SearchKindArtifact, } // SearchStatuses is the accepted set of bare status words a query may name to // select runs. It mirrors the run status vocabulary; a bare word selects runs // rather than matching as free text. var SearchStatuses = []string{"queued", "running", "succeeded", "failed", "canceled", "interrupted"} // Search budget and cap constants. They are fixed, enforced server-side and // reported on SearchResponse so a client can see the bound that applied. const ( // SearchDefaultLimit is the result cap when a request omits Limit (or sends 0). SearchDefaultLimit = 50 // SearchMaxLimit is the largest accepted result cap; larger requests clamp. SearchMaxLimit = 200 // SearchMaxScanSteps bounds how many recorded steps one query inspects while // scanning input/output/transcript field text. SearchMaxScanSteps = 2000 // SearchMaxScanBytes bounds the total field bytes (input_json + output_json + // evidence_json + transcript) one query decodes and searches before it stops // and reports Truncated. SearchMaxScanBytes = 1 << 20 ) // SearchRequest is the search request body. Query is the free text, a bare // status word or a date expression; Kind optionally narrows to one SearchKind; // Limit caps the returned results (0 = server default). type SearchRequest struct { Query string `json:"query"` Kind string `json:"kind,omitempty"` Limit int `json:"limit,omitempty"` } // SearchResponse is the ranked, bounded set of matches. Results are ordered by // score, then recency, then a stable kind/target tie-break. Truncated reports // that either the result cap or the field-scan budget dropped matches; // ScannedSteps/ScannedBytes and ScanBoundBytes make the body-scan bound // observable. type SearchResponse struct { Query string `json:"query"` Kind string `json:"kind,omitempty"` Results []SearchResult `json:"results"` Truncated bool `json:"truncated,omitempty"` ScannedSteps int `json:"scanned_steps"` ScannedBytes int `json:"scanned_bytes"` Cap int `json:"cap"` ScanBoundBytes int `json:"scan_bound_bytes"` } // SearchResult is one typed, navigable match. Kind selects which payload is // set; Target is a stable token an existing CLI command can resolve // (pipeline:, pipeline::v, run:, run::, // run:::, or an artifact URL). Score and MatchedField // expose the ranking tier and why the hit matched so a client can re-rank; // Recency is the hit's sortable UTC timestamp. type SearchResult struct { Kind string `json:"kind"` Target string `json:"target"` Score int `json:"score"` MatchedField string `json:"matched_field"` Recency string `json:"recency,omitempty"` Pipeline *SearchPipeline `json:"pipeline,omitempty"` Version *SearchVersion `json:"version,omitempty"` Run *SearchRun `json:"run,omitempty"` Step *SearchStep `json:"step,omitempty"` Field *SearchField `json:"field,omitempty"` Artifact *SearchArtifact `json:"artifact,omitempty"` } // SearchPipeline is a pipeline name/identity hit: its latest version and stage count. type SearchPipeline struct { ID int64 `json:"id"` Name string `json:"name"` Version int `json:"version"` Stages int `json:"stages"` } // SearchVersion is a pipeline version/source hit. type SearchVersion struct { PipelineID int64 `json:"pipeline_id"` Version int `json:"version"` ContentHash string `json:"content_hash"` CreatedAt string `json:"created_at"` } // SearchRun is a run identity/metadata hit. FinishedAt and DurationSeconds are // omitted for a run without a recorded finish. type SearchRun struct { ID int64 `json:"id"` PipelineName string `json:"pipeline_name"` Status string `json:"status"` Workspace string `json:"workspace,omitempty"` CreatedAt string `json:"created_at"` FinishedAt string `json:"finished_at,omitempty"` DurationSeconds float64 `json:"duration_seconds,omitempty"` } // SearchStep is a recorded step/visit hit. type SearchStep struct { RunID int64 `json:"run_id"` Sequence int `json:"sequence"` Stage string `json:"stage"` Visit int `json:"visit,omitempty"` Outcome string `json:"outcome,omitempty"` Target string `json:"target,omitempty"` Diagnostic string `json:"diagnostic,omitempty"` } // SearchField is a stage input/output/evidence/transcript text hit with a // snippet around the first match. type SearchField struct { RunID int64 `json:"run_id"` Sequence int `json:"sequence"` Field string `json:"field"` Snippet string `json:"snippet"` } // SearchArtifact is a recorded artifact hit; contents are never read, only the // recorded metadata. type SearchArtifact struct { RunID int64 `json:"run_id"` Sequence int `json:"sequence"` Name string `json:"name"` ContentType string `json:"content_type"` SizeBytes int64 `json:"size_bytes"` URL string `json:"url"` }