Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
7 changes: 4 additions & 3 deletions CHANGELOG.md
Original file line number Diff line number Diff line change
Expand Up @@ -19,9 +19,10 @@ conflict with a third party's registered US trademark in cloud services.
- The query language is now **PitotQL**. Existing structured dashboard queries,
MCP `query_telemetry` arguments (`text`, `panel.query`, `panel.sql`), query
keywords, Explore URL parameters and browser storage keys are unchanged.
Previous query HTTP paths and the MCP reference URI remain read aliases;
responses and new clients use canonical PitotQL names. See
[rename compatibility](site/src/content/docs/docs/reference/rename-compatibility.mdx) for the exact aliases.
Previous query HTTP paths, MCP reference URI and error-code reader aliases
are removed. Clients must use canonical PitotQL names. Permanent website
redirects preserve existing documentation links. See
[rename compatibility](site/src/content/docs/docs/reference/rename-compatibility.mdx) for the cutover requirements.
- Before upgrading, stop the service and take a cold backup of the complete
data directory. On startup, Pitot automatically renames the previous control
database and its SQLite WAL, shared-memory and rollback-journal sidecars in
Expand Down
4 changes: 2 additions & 2 deletions internal/api/auth_middleware.go
Original file line number Diff line number Diff line change
Expand Up @@ -346,9 +346,9 @@ func classifyNonSCIMRoute(method, path string) (routePolicy, bool) {
return routePolicy{kind: routePolicyCapability, capability: ManageAlerts}, unsafe
case path == "/api/queries/run" || path == "/api/queries/exemplars" || path == "/api/queries/variables/resolve" || path == "/api/annotations/query":
return routePolicy{kind: routePolicyCapability, capability: ReadTelemetry}, method == http.MethodPost
case path == "/api/pitotql/parse" || path == "/api/pitotql/format" || path == "/api/pitotql/complete" || path == previousQueryPath("parse") || path == previousQueryPath("format") || path == previousQueryPath("complete"):
case path == "/api/pitotql/parse" || path == "/api/pitotql/format" || path == "/api/pitotql/complete":
return routePolicy{kind: routePolicyCapability, capability: ReadTelemetry}, method == http.MethodPost
case path == "/api/pitotql/reference" || path == previousQueryPath("reference") || path == "/api/telemetry/schema":
case path == "/api/pitotql/reference" || path == "/api/telemetry/schema":
return routePolicy{kind: routePolicyCapability, capability: ReadTelemetry}, read
case path == "/api/dashboards" || strings.HasPrefix(path, "/api/dashboards/"):
return routePolicy{kind: routePolicyCapability, capability: ManageOwnDashboards}, read || unsafe
Expand Down
8 changes: 0 additions & 8 deletions internal/api/pitotql.go
Original file line number Diff line number Diff line change
Expand Up @@ -24,16 +24,8 @@ func RegisterPitotQLRoutes(e *echo.Echo, parser query.Parser, engine QueryEngine
e.POST("/api/pitotql/format", h.format, read)
e.POST("/api/pitotql/complete", h.complete, read)
e.GET("/api/pitotql/reference", h.reference, read)
// Published route aliases accept old clients; all response content is canonical.
e.POST(previousQueryPath("parse"), h.parse, read)
e.POST(previousQueryPath("format"), h.format, read)
e.POST(previousQueryPath("complete"), h.complete, read)
e.GET(previousQueryPath("reference"), h.reference, read)
}

// Intentional published API compatibility exception.
func previousQueryPath(action string) string { return "/api/fanql/" + action }

type pitotqlPreview struct {
Text string `json:"text"`
Note string `json:"note"`
Expand Down
37 changes: 14 additions & 23 deletions internal/api/pitotql_test.go
Original file line number Diff line number Diff line change
Expand Up @@ -459,28 +459,19 @@ func TestPitotQLParseOffersSeenDottedKey(t *testing.T) {
}
}

func TestPreviousQueryRoutesAcceptClientsAndReturnCanonicalNames(t *testing.T) {
for _, tc := range []struct {
action, method, body string
status int
}{
{"parse", http.MethodPost, `{"text":"spans | count() by service"}`, http.StatusOK},
{"format", http.MethodPost, `{"query":{"from":"spans","where":["service = 'api'"]}}`, http.StatusOK},
{"complete", http.MethodPost, `{"text":"spa","cursor":3}`, http.StatusOK},
{"reference", http.MethodGet, "", http.StatusOK},
{"parse", http.MethodPost, `{"text":"spans where a:1 b:2 or c:3"}`, http.StatusBadRequest},
} {
t.Run(tc.action+tc.body, func(t *testing.T) {
oldPath := previousQueryPath(tc.action)
policy, ok := classifyRoute(tc.method, oldPath)
if !ok || policy.capability != ReadTelemetry {
t.Fatalf("unprotected alias: %+v", policy)
}
old := servePitotQL(t, &fakePitotQLParser{}, &fakePitotQLPanels{}, tc.method, oldPath, tc.body)
current := servePitotQL(t, &fakePitotQLParser{}, &fakePitotQLPanels{}, tc.method, "/api/pitotql/"+tc.action, tc.body)
if old.Code != tc.status || old.Body.String() != current.Body.String() {
t.Fatalf("alias: %d %s; canonical: %d %s", old.Code, old.Body, current.Code, current.Body)
}
})
func TestRetiredQueryRoutesAreNotRegistered(t *testing.T) {
for _, action := range []string{"parse", "format", "complete", "reference"} {
method := http.MethodPost
if action == "reference" {
method = http.MethodGet
}
path := "/api/fanql/" + action
if _, ok := classifyRoute(method, path); ok {
t.Fatalf("retired route classified: %s", path)
}
response := servePitotQL(t, &fakePitotQLParser{}, &fakePitotQLPanels{}, method, path, `{}`)
if response.Code != http.StatusNotFound {
t.Fatalf("retired route: %d %s", response.Code, response.Body)
}
}
}
16 changes: 0 additions & 16 deletions internal/mcp/pitotql_resource.go
Original file line number Diff line number Diff line change
Expand Up @@ -7,8 +7,6 @@ import (
"github.com/modelcontextprotocol/go-sdk/mcp"
)

const previousQueryReferenceURI = "pitot://fanql/reference" // Published read alias.

const pitotqlReferenceURI = "pitot://pitotql/reference"

func (s *Server) registerPitotQLResource() {
Expand All @@ -20,17 +18,3 @@ func (s *Server) registerPitotQLResource() {
return &mcp.ReadResourceResult{Contents: []*mcp.ResourceContents{{URI: pitotqlReferenceURI, MIMEType: "text/markdown", Text: pitotql.Reference()}}}, nil
})
}

// canonicalQueryResource accepts the published URI without advertising it.
func canonicalQueryResource(next mcp.MethodHandler) mcp.MethodHandler {
return func(ctx context.Context, method string, req mcp.Request) (mcp.Result, error) {
if read, ok := req.(*mcp.ReadResourceRequest); ok && method == "resources/read" && read.Params != nil && read.Params.URI == previousQueryReferenceURI {
copied := *read
params := *read.Params
params.URI = pitotqlReferenceURI
copied.Params = &params
req = &copied
}
return next(ctx, method, req)
}
}
15 changes: 8 additions & 7 deletions internal/mcp/pitotql_test.go
Original file line number Diff line number Diff line change
Expand Up @@ -286,22 +286,23 @@ func TestQueryTelemetryKeepsInvalidPanelProblems(t *testing.T) {
}
}

func TestPreviousQueryReferenceReadsCanonicalResource(t *testing.T) {
func TestRetiredQueryReferenceIsUnavailable(t *testing.T) {
const previousURI = "pitot://fanql/reference"
client := connectTestClient(t, newPanelServer(t), nil)
listed, err := client.ListResources(t.Context(), nil)
if err != nil {
t.Fatal(err)
}
for _, resource := range listed.Resources {
if resource.URI == previousQueryReferenceURI {
if resource.URI == previousURI {
t.Fatal("read alias advertised")
}
}
result, err := client.ReadResource(t.Context(), &mcp.ReadResourceParams{URI: previousQueryReferenceURI})
if err != nil {
t.Fatal(err)
if _, err := client.ReadResource(t.Context(), &mcp.ReadResourceParams{URI: previousURI}); err == nil {
t.Fatal("retired resource resolved")
}
if len(result.Contents) != 1 || result.Contents[0].URI != pitotqlReferenceURI || result.Contents[0].Text != pitotql.Reference() {
t.Fatalf("resource = %+v", result)
result, err := client.ReadResource(t.Context(), &mcp.ReadResourceParams{URI: pitotqlReferenceURI})
if err != nil || len(result.Contents) != 1 || result.Contents[0].Text != pitotql.Reference() {
t.Fatalf("current resource = %+v, %v", result, err)
}
}
2 changes: 1 addition & 1 deletion internal/mcp/server.go
Original file line number Diff line number Diff line change
Expand Up @@ -143,7 +143,7 @@ func newServer(queries Observability, dashboards *dashboard.Service, panels *que
s.registerDashboardTools()
s.registerAppResources()
s.registerPitotQLResource()
s.mcp.AddReceivingMiddleware(limitLegacySessions(s.mcp), canonicalQueryResource, normalizeToolErrors, recoverToolPanic, addStaticCacheHints, filterMCPAppToolMetadata, s.validateToolArguments)
s.mcp.AddReceivingMiddleware(limitLegacySessions(s.mcp), normalizeToolErrors, recoverToolPanic, addStaticCacheHints, filterMCPAppToolMetadata, s.validateToolArguments)
return s
}

Expand Down
4 changes: 3 additions & 1 deletion internal/pitotql/complete.go
Original file line number Diff line number Diff line change
Expand Up @@ -164,9 +164,11 @@ func (c *Completer) schema(ctx context.Context, key completionKey) (*query.Schem
if c.source == nil {
return nil, false, false
}
schema, err := c.source.Schema(ctx, query.SchemaRequest{Window: key.window, Namespace: key.namespace, Cached: true})
c.mu.Lock()
defer c.mu.Unlock()
// Read the cache while holding the same lock that retires an in-flight
// fetch, so a stale miss cannot admit a duplicate after that fetch finishes.
schema, err := c.source.Schema(ctx, query.SchemaRequest{Window: key.window, Namespace: key.namespace, Cached: true})
if err == nil && schema != nil {
delete(c.failed, key)
return schema, true, false
Expand Down
16 changes: 0 additions & 16 deletions internal/pitotql/failure.go
Original file line number Diff line number Diff line change
@@ -1,23 +1,7 @@
package pitotql

import "encoding/json"

// Failure is the transport-neutral PitotQL failure.
type Failure struct {
Code string `json:"code"`
Message string `json:"message"`
}

// UnmarshalJSON accepts recorded responses from before the language rename.
func (f *Failure) UnmarshalJSON(data []byte) error {
type plain Failure
var value plain
if err := json.Unmarshal(data, &value); err != nil {
return err
}
if value.Code == "invalid_fanql" {
value.Code = "invalid_pitotql"
}
*f = Failure(value)
return nil
}
17 changes: 0 additions & 17 deletions internal/pitotql/failure_test.go

This file was deleted.

Large diffs are not rendered by default.

Loading
Loading