mirror of
https://github.com/ModernRelay/omnigraph.git
synced 2026-06-30 02:49:39 +02:00
feat: inline query strings in CLI and HTTP server (#110)
* feat(MR-656): inline query strings in CLI and HTTP server
CLI:
- Add -e / --query-string <STRING> to omnigraph read and omnigraph change
- Exactly one of --query, --query-string, --alias is required (3-way XOR)
- Empty --query-string is rejected with a clear error
HTTP:
- New POST /query (read-only, clean field names: query/name/params/branch/snapshot)
- Mutations on /query are rejected with 400 -- use POST /change instead
- ChangeRequest fields polished: query (alias query_source), name (alias query_name)
- POST /read and POST /change remain byte-compatible for existing clients
Tests:
- cli.rs: -e happy-path on read/change, mutex error vs --query, empty -e rejected
- system_local.rs: inline -e read and -e change exercise the local flow
- system_remote.rs: inline -e read/change over HTTP plus direct /query 200/400
- server.rs: /query 200, /query 400 on mutation, /change legacy field alias
- openapi.rs: new /query path, QueryRequest schema, ChangeRequest field-name polish
Docs: cli.md (-e examples), cli-reference.md (read/change rows), server.md (/query)
Co-Authored-By: Ragnor Comerford <ragnor.comerford@gmail.com>
* feat(MR-656): rename read/change to query/mutate with deprecation signals
HTTP server:
- Add POST /mutate as canonical write endpoint (pairs with POST /query).
- Mark POST /read and POST /change as deprecated. Three-channel signal:
* OpenAPI: `deprecated: true` on the operation (every codegen flags
the generated SDK method).
* RFC 9745: response `Deprecation: true` header on every response.
* RFC 8288: response `Link: </successor>; rel="successor-version"`
pointing at /query and /mutate respectively.
- Share business logic across /mutate and /change via run_mutate(); the
/change wrapper is the only place that adds the deprecation headers.
- ChangeRequest field aliases (query_source/query_name) preserved.
- AliasCommand serde now accepts `query`/`mutate` alongside `read`/`change`.
CLI:
- Promote `omnigraph query` / `omnigraph mutate` to top-level canonical
subcommands (clap visible_alias keeps `omnigraph read` / `omnigraph
change` working forever).
- Promote `omnigraph lint` / `omnigraph check` to top-level (was nested
under `omnigraph query lint`, which is now a deprecated argv shim that
rewrites to the canonical form).
- Argv-level preprocessing prints a one-line deprecation warning to
stderr when any legacy spelling is used. Canonical names are silent.
Tests:
- Server: /mutate works, /change emits Deprecation+Link headers, /read
emits Deprecation+Link headers, /query carries no deprecation signal.
- OpenAPI: /read and /change flagged deprecated; /query and /mutate not.
- CLI: canonical `lint` matches deprecated `query lint` / `query check`
output; `read` / `change` print deprecation warnings.
Docs:
- cli.md: new canonical examples; "Deprecated names" migration table.
- cli-reference.md: top-level table updated; aliases.<name>.command
accepts both legacy and canonical spellings.
- server.md: endpoint inventory shows /query and /mutate as canonical
and /read and /change as deprecated; dedicated section explains the
three-channel deprecation signal.
- og-cheet-sheet.md: use new `omnigraph lint` / `omnigraph check`.
- openapi.json regenerated.
Migration is purely cosmetic — every deprecated form continues to work
indefinitely; only the spelling changes.
Co-Authored-By: Ragnor Comerford <ragnor.comerford@gmail.com>
* fix(MR-656): address Devin Review findings on /query and /change
Two issues raised by Devin Review on PR #110:
1. `POST /query` mutation-rejection error pointed at the deprecated
`/change` endpoint instead of the canonical `/mutate`. Fixed in
three places: the runtime error message in `server_query`, the
utoipa 400-response description, and the handler doc comment. The
`QueryRequest` schema docstrings in `api.rs` got the same update so
the openapi.json bodies match. Server and openapi tests updated.
2. `execute_change_remote` serialized `ChangeRequest` directly, which
emits the new canonical field names `query` / `name` on the wire.
`#[serde(alias = "query_source")]` only affects deserialization, so
a newer CLI talking to an older server would have its `/change`
POST body fail with "missing field: query_source". Fixed by
extracting a `legacy_change_request_body` helper that hand-rolls
the JSON with the legacy keys (`query_source` / `query_name`), the
same byte-stable contract `execute_read_remote` already uses
against `/read`. Added two unit tests on the helper to lock the
wire shape in.
Co-Authored-By: Ragnor Comerford <ragnor.comerford@gmail.com>
* docs(dev): RFC 001 — inline + stored queries, envelope, MCP
Tracked artifact consolidating the design across MR-656 (this branch),
MR-976 (Phase 1 envelope hardening parent, with MR-977/978/979/980
sub-issues), and MR-969 (stored queries + MCP).
Sections:
* Two paths, one engine — inline `/query` + `/mutate` (this PR) coexist
with stored `/queries/{name}` (MR-969). Same `run_query` / `run_mutate`
backend (the fold-in landed in the previous commit).
* Request envelope ("before") — Idempotency-Key, If-Match, X-Deadline,
X-Trace-Id, expect, dry_run, fields. Phase 1 ships the load-bearing
subset on `/mutate`.
* Response envelope ("after") — audit_id, snapshot_id, commit_id, stats,
warnings. Closes the provenance loop today's `ChangeOutput` leaves
open.
* `.gq` pragmas — `@description`, `@returns`, `@mcp`. Source-of-truth
for the stored-query agent contract; no separate YAML registry.
* Multi-graph MCP — per-graph `/graphs/{id}/mcp/tools` + `/mcp/invoke`.
Token binds to one graph by default; cross-graph agents loop.
* Cedar split — `read`/`change` for inline, `invoke_query` for stored.
Operators deny ad-hoc for agent groups while keeping curated tool
list open.
* Rejected alternatives — per-env override files, compiled bundles,
tool-name prefixing across graphs, body-field graph dispatch.
Index entry added under "Active Implementation Plans" so future agents
land on the RFC before touching queries / mutations / envelope code.
`scripts/check-agents-md.sh` clean (35 links, 34 docs).
* docs(server): clarify why run_query lacks AppState parameter
run_mutate takes state for workload admission; run_query doesn't because
reads aren't admission-gated today. Mark the asymmetry as intentional and
flag the two future events that would grow the signature: Phase 1's
`expect: { max_rows_scanned: N }` budget (MR-976) or per-actor admission
extending to stored-read invocations (MR-969). Prevents the natural
"make these symmetrical" follow-up.
* refactor(server): run_query / run_mutate take &ResolvedActor
Replace `Option<Extension<ResolvedActor>>` in the helpers with
`Option<&ResolvedActor>`. Saves MR-969's stored-query handler from
wrapping a bare actor in axum's `Extension(...)` before calling.
Handler signatures (`server_query`, `server_read`, `server_mutate`,
`server_change`) keep `Option<Extension<ResolvedActor>>` because that
is what axum injects, and unwrap at the call site with
`actor.as_ref().map(|Extension(actor)| actor)`.
Net: -13/+10 LOC, 89/0 server tests pass.
* docs(releases): v0.6.0 — describe inline + canonical-named queries (MR-656)
Extend the v0.6.0 release notes to cover the third piece of work landing
alongside the graph terminology rename and multi-graph server mode:
canonical-named `POST /query` and `POST /mutate` endpoints, the CLI's
new `-e/--query-string` flag, the top-level promotion of `lint` /
`check`, and the three-channel deprecation signal on `/read` and
`/change` (OpenAPI `deprecated: true` + RFC 9745 + RFC 8288).
Additions:
* Top blurb: "Two pieces" -> "Three pieces" with a bullet describing
the rename + inline flow.
* Breaking Changes: new "Query / mutation rename" subsection covering
the `ChangeRequest` field rename (with the back-compat serde aliases
and the CLI's `legacy_change_request_body` byte-stable wire helper)
and the `omnigraph query lint` -> `omnigraph lint` move.
* New: 5 bullets — the two endpoints, the CLI subcommands, the `-e`
flag, the deprecation signal channels, the widened `aliases.<name>.command`
vocabulary.
* User Impact: one bullet making explicit that the rename is cosmetic
on the client side and migration is voluntary.
* Documentation: pointers to the updated `server.md` / `cli.md` /
`cli-reference.md` and the new `docs/dev/rfc-001-queries-envelope-mcp.md`.
+15/-1 lines. `./scripts/check-agents-md.sh` clean.
* refactor(cli): demote `check` from visible_alias to deprecation shim
`omnigraph check` was a clap `visible_alias` on `lint`, advertised in
`--help` as an equivalent canonical name. Per MR-981 §6 (long-form
flags as canonical, short forms as visible aliases), visible aliases
on subcommand names hurt agent CX: agents emit either spelling
depending on training-data drift, and there's no length signal
pointing at the canonical name.
Changes:
* Remove `#[command(visible_alias = "check")]` from the `Lint` variant.
`omnigraph --help` now shows only `lint`.
* Add bare `check` to `rewrite_deprecated_argv` so `omnigraph check
<args>` still works — it rewrites to `omnigraph lint <args>` and
emits a one-line stderr deprecation warning, matching the existing
pattern for `read` / `change` / `query lint` / `query check`.
* Fix the nested `query check` shim to substitute `check` -> `lint` in
the rewritten argv (previously it relied on `check` being a
visible_alias to reach the `Lint` variant).
* New test `deprecated_check_top_level_rewrites_to_lint` covers: bare
`check` produces identical stdout to `lint`, emits the deprecation
warning, and `check` does NOT appear as an alias in `omnigraph
--help`.
* Release notes updated to reflect the deprecation-shim treatment and
cross-reference MR-981 §6 reasoning.
Cargo / Go users typing `check` still work indefinitely; one stderr
nudge per invocation teaches the canonical name. Agents see only
`lint` in `--help --json` so they emit one canonical form.
67/0 omnigraph-cli tests pass; 39 workspace test suites green.
---------
Co-authored-by: Devin AI <158243242+devin-ai-integration[bot]@users.noreply.github.com>
Co-authored-by: Ragnor Comerford <ragnor.comerford@gmail.com>
Co-authored-by: Ragnor Comerford <hello@ragnor.co>
This commit is contained in:
devin-ai-integration[bot]
GitHub
parent
e0f13b32c5
commit
1a4d2cee97
19 changed files with 2088 additions and 264 deletions
|
|
@ -250,19 +250,53 @@ pub struct ReadRequest {
|
|||
pub snapshot: Option<String>,
|
||||
}
|
||||
|
||||
/// Inline read-query request for `POST /query`.
|
||||
///
|
||||
/// Friendlier-named alternative to [`ReadRequest`] for ad-hoc reads and
|
||||
/// AI-agent integration. Mutations are rejected with 400 — use `POST
|
||||
/// /mutate` (or its deprecated alias `POST /change`) for write queries.
|
||||
/// Field names are deliberately short (`query`, `name`) to match the GQ
|
||||
/// keyword and the CLI `-e` flag.
|
||||
#[derive(Debug, Clone, Serialize, Deserialize, ToSchema)]
|
||||
pub struct QueryRequest {
|
||||
/// GQ read-query source. May declare one or more named queries; pick one
|
||||
/// with `name` when more than one is declared. Mutations
|
||||
/// (`insert`/`update`/`delete`) get 400 — use `POST /mutate` (or its
|
||||
/// deprecated alias `POST /change`) instead.
|
||||
#[schema(example = "query get_person($name: String) {\n match {\n $p: Person { name: $name }\n }\n return { $p.name, $p.age }\n}")]
|
||||
pub query: String,
|
||||
/// Name of the query to run when `query` declares multiple. Optional when
|
||||
/// only one query is declared.
|
||||
pub name: Option<String>,
|
||||
/// JSON object whose keys match the query's declared parameters.
|
||||
pub params: Option<Value>,
|
||||
/// Branch to read from. Mutually exclusive with `snapshot`. Defaults to `main`.
|
||||
pub branch: Option<String>,
|
||||
/// Snapshot id to read from. Mutually exclusive with `branch`.
|
||||
pub snapshot: Option<String>,
|
||||
}
|
||||
|
||||
#[derive(Debug, Clone, Serialize, Deserialize, ToSchema)]
|
||||
pub struct ChangeRequest {
|
||||
/// GQ mutation source containing `insert`, `update`, or `delete` statements.
|
||||
/// May declare multiple named mutations; pick one with `query_name`.
|
||||
/// May declare multiple named mutations; pick one with `name`.
|
||||
///
|
||||
/// Accepts the legacy field name `query_source` as a deserialization alias.
|
||||
#[schema(
|
||||
example = "query insert_person($name: String, $age: I32) {\n insert Person { name: $name, age: $age }\n}"
|
||||
)]
|
||||
pub query_source: String,
|
||||
/// Name of the mutation to run when `query_source` declares multiple.
|
||||
pub query_name: Option<String>,
|
||||
#[serde(alias = "query_source")]
|
||||
pub query: String,
|
||||
/// Name of the mutation to run when `query` declares multiple.
|
||||
///
|
||||
/// Accepts the legacy field name `query_name` as a deserialization alias.
|
||||
#[serde(default, alias = "query_name")]
|
||||
pub name: Option<String>,
|
||||
/// JSON object whose keys match the mutation's declared parameters.
|
||||
#[serde(default)]
|
||||
pub params: Option<Value>,
|
||||
/// Target branch. Defaults to `main`.
|
||||
#[serde(default)]
|
||||
pub branch: Option<String>,
|
||||
}
|
||||
|
||||
|
|
|
|||
|
|
@ -93,7 +93,16 @@ pub struct PolicySettings {
|
|||
#[derive(Debug, Clone, Copy, Eq, PartialEq, Serialize, Deserialize)]
|
||||
#[serde(rename_all = "snake_case")]
|
||||
pub enum AliasCommand {
|
||||
/// Read alias (canonical: `query`). The legacy spelling `read` is
|
||||
/// kept as the variant name for back-compat with serialized configs
|
||||
/// and external SDK callers; `query` is accepted on the wire via the
|
||||
/// serde alias.
|
||||
#[serde(alias = "query")]
|
||||
Read,
|
||||
/// Mutation alias (canonical: `mutate`). The legacy spelling `change`
|
||||
/// is kept as the variant name for back-compat; `mutate` is accepted
|
||||
/// on the wire via the serde alias.
|
||||
#[serde(alias = "mutate")]
|
||||
Change,
|
||||
}
|
||||
|
||||
|
|
|
|||
|
|
@ -22,16 +22,16 @@ use api::{
|
|||
BranchCreateOutput, BranchCreateRequest, BranchDeleteOutput, BranchListOutput,
|
||||
BranchMergeOutput, BranchMergeRequest, ChangeOutput, ChangeRequest, CommitListOutput,
|
||||
CommitListQuery, ErrorCode, ErrorOutput, ExportRequest, GraphInfo, GraphListResponse,
|
||||
HealthOutput, IngestOutput, IngestRequest, ReadOutput, ReadRequest, SchemaApplyOutput,
|
||||
SchemaApplyRequest, SchemaOutput, SnapshotQuery, ingest_output, schema_apply_output,
|
||||
snapshot_payload,
|
||||
HealthOutput, IngestOutput, IngestRequest, QueryRequest, ReadOutput, ReadRequest,
|
||||
SchemaApplyOutput, SchemaApplyRequest, SchemaOutput, SnapshotQuery, ingest_output,
|
||||
schema_apply_output, snapshot_payload,
|
||||
};
|
||||
pub use auth::{AWS_SECRET_ENV, EnvOrFileTokenSource, TokenSource, resolve_token_source};
|
||||
use axum::body::{Body, Bytes};
|
||||
use axum::extract::DefaultBodyLimit;
|
||||
use axum::extract::{Extension, OriginalUri, Path, Query, Request, State};
|
||||
use axum::http::StatusCode;
|
||||
use axum::http::header::{AUTHORIZATION, CONTENT_TYPE};
|
||||
use axum::http::header::{AUTHORIZATION, CONTENT_TYPE, HeaderName, HeaderValue};
|
||||
use axum::middleware::{self, Next};
|
||||
use axum::response::{IntoResponse, Response};
|
||||
use axum::routing::{delete, get, post};
|
||||
|
|
@ -86,9 +86,13 @@ fn hash_bearer_token(token: &str) -> BearerTokenHash {
|
|||
server_health,
|
||||
server_graphs_list,
|
||||
server_snapshot,
|
||||
server_read,
|
||||
// deprecated; the #[deprecated] attribute on the handler
|
||||
// surfaces as `deprecated: true` on the OpenAPI operation.
|
||||
#[allow(deprecated)] server_read,
|
||||
server_query,
|
||||
server_export,
|
||||
server_change,
|
||||
#[allow(deprecated)] server_change,
|
||||
server_mutate,
|
||||
server_schema_apply,
|
||||
server_schema_get,
|
||||
server_ingest,
|
||||
|
|
@ -930,8 +934,21 @@ pub fn build_app(state: AppState) -> Router {
|
|||
let per_graph_protected = Router::new()
|
||||
.route("/snapshot", get(server_snapshot))
|
||||
.route("/export", post(server_export))
|
||||
.route("/read", post(server_read))
|
||||
.route("/change", post(server_change))
|
||||
// /read and /change are kept indefinitely for back-compat;
|
||||
// their handlers carry #[deprecated] so the OpenAPI operation is
|
||||
// flagged and their responses include RFC 9745 Deprecation +
|
||||
// RFC 8288 Link headers. Suppress the call-site warning for the
|
||||
// route registration itself.
|
||||
.route("/read", post({
|
||||
#[allow(deprecated)]
|
||||
server_read
|
||||
}))
|
||||
.route("/query", post(server_query))
|
||||
.route("/change", post({
|
||||
#[allow(deprecated)]
|
||||
server_change
|
||||
}))
|
||||
.route("/mutate", post(server_mutate))
|
||||
.route("/schema", get(server_schema_get))
|
||||
.route("/schema/apply", post(server_schema_apply))
|
||||
.route(
|
||||
|
|
@ -1591,6 +1608,21 @@ async fn server_snapshot(
|
|||
Ok(Json(snapshot_payload(&branch, &snapshot)))
|
||||
}
|
||||
|
||||
/// Header values that flag a response as coming from a deprecated route
|
||||
/// (RFC 9745 / RFC 8288) and point at the canonical successor.
|
||||
fn deprecation_headers(successor_link: &'static str) -> [(HeaderName, HeaderValue); 2] {
|
||||
[
|
||||
(
|
||||
HeaderName::from_static("deprecation"),
|
||||
HeaderValue::from_static("true"),
|
||||
),
|
||||
(
|
||||
HeaderName::from_static("link"),
|
||||
HeaderValue::from_static(successor_link),
|
||||
),
|
||||
]
|
||||
}
|
||||
|
||||
#[utoipa::path(
|
||||
post,
|
||||
path = "/read",
|
||||
|
|
@ -1598,69 +1630,84 @@ async fn server_snapshot(
|
|||
operation_id = "read",
|
||||
request_body = ReadRequest,
|
||||
responses(
|
||||
(status = 200, description = "Query results", body = ReadOutput),
|
||||
(status = 200, description = "Query results (response includes `Deprecation: true` + `Link: </query>; rel=\"successor-version\"`)", body = ReadOutput),
|
||||
(status = 400, description = "Bad request", body = ErrorOutput),
|
||||
(status = 401, description = "Unauthorized", body = ErrorOutput),
|
||||
(status = 403, description = "Forbidden", body = ErrorOutput),
|
||||
),
|
||||
security(("bearer_token" = [])),
|
||||
)]
|
||||
/// Execute a GQ read query.
|
||||
#[deprecated(note = "use POST /query instead; /read is kept indefinitely for byte-stable back-compat")]
|
||||
/// **Deprecated** — use [`POST /query`](#tag/queries/operation/query) instead.
|
||||
///
|
||||
/// Runs the query in `query_source` against either a branch or a frozen
|
||||
/// snapshot (mutually exclusive). When `query_source` defines multiple named
|
||||
/// queries, pick one with `query_name`. `params` is a JSON object whose keys
|
||||
/// match the parameters declared by the query. Returns rows as a JSON array
|
||||
/// plus a `columns` list. Read-only.
|
||||
/// Execute a GQ read query. Behavior is unchanged from prior releases; the
|
||||
/// route is kept indefinitely for byte-stable back-compat. New integrations
|
||||
/// should target `POST /query`, which has clean field names (`query` /
|
||||
/// `name`) and a 400-on-mutation guard. Responses from this route include
|
||||
/// `Deprecation: true` and `Link: </query>; rel="successor-version"`
|
||||
/// headers per RFC 9745 / RFC 8288 so SDKs and proxies can surface the
|
||||
/// signal.
|
||||
async fn server_read(
|
||||
Extension(handle): Extension<Arc<GraphHandle>>,
|
||||
actor: Option<Extension<ResolvedActor>>,
|
||||
Json(request): Json<ReadRequest>,
|
||||
) -> std::result::Result<Json<ReadOutput>, ApiError> {
|
||||
if request.branch.is_some() && request.snapshot.is_some() {
|
||||
return Err(ApiError::bad_request(
|
||||
"read request may specify branch or snapshot, not both",
|
||||
));
|
||||
}
|
||||
|
||||
let target = read_target_from_request(request.branch, request.snapshot);
|
||||
let policy_branch = match &target {
|
||||
ReadTarget::Branch(branch) => Some(branch.clone()),
|
||||
ReadTarget::Snapshot(_) if handle.policy.is_some() && actor.is_some() => {
|
||||
let db = &handle.engine;
|
||||
db.resolved_branch_of(target.clone())
|
||||
.await
|
||||
.map(|branch| branch.or_else(|| Some("main".to_string())))
|
||||
.map_err(ApiError::from_omni)?
|
||||
}
|
||||
ReadTarget::Snapshot(_) => None,
|
||||
};
|
||||
authorize_request(
|
||||
) -> std::result::Result<([(HeaderName, HeaderValue); 2], Json<ReadOutput>), ApiError> {
|
||||
let (selected_name, target, result) = run_query(
|
||||
handle,
|
||||
actor.as_ref().map(|Extension(actor)| actor),
|
||||
handle.policy.as_deref(),
|
||||
PolicyRequest {
|
||||
action: PolicyAction::Read,
|
||||
branch: policy_branch,
|
||||
target_branch: None,
|
||||
},
|
||||
)?;
|
||||
let (selected_name, query_params) =
|
||||
select_named_query(&request.query_source, request.query_name.as_deref())
|
||||
.map_err(|err| ApiError::bad_request(err.to_string()))?;
|
||||
let params = query_params_from_json(&query_params, request.params.as_ref())
|
||||
.map_err(|err| ApiError::bad_request(err.to_string()))?;
|
||||
&request.query_source,
|
||||
request.query_name.as_deref(),
|
||||
request.params.as_ref(),
|
||||
request.branch,
|
||||
request.snapshot,
|
||||
false, // /read predates the D2 rule; legacy callers may submit mutating queries here
|
||||
)
|
||||
.await?;
|
||||
Ok((
|
||||
deprecation_headers("</query>; rel=\"successor-version\""),
|
||||
Json(api::read_output(selected_name, &target, result)),
|
||||
))
|
||||
}
|
||||
|
||||
let result = {
|
||||
let db = &handle.engine;
|
||||
db.query(
|
||||
target.clone(),
|
||||
&request.query_source,
|
||||
&selected_name,
|
||||
¶ms,
|
||||
)
|
||||
.await
|
||||
.map_err(ApiError::from_omni)?
|
||||
};
|
||||
#[utoipa::path(
|
||||
post,
|
||||
path = "/query",
|
||||
tag = "queries",
|
||||
operation_id = "query",
|
||||
request_body = QueryRequest,
|
||||
responses(
|
||||
(status = 200, description = "Query results", body = ReadOutput),
|
||||
(status = 400, description = "Bad request - also returned when the query body contains mutations; use POST /mutate (or its deprecated alias POST /change) for write queries", body = ErrorOutput),
|
||||
(status = 401, description = "Unauthorized", body = ErrorOutput),
|
||||
(status = 403, description = "Forbidden", body = ErrorOutput),
|
||||
),
|
||||
security(("bearer_token" = [])),
|
||||
)]
|
||||
/// Execute an inline read query (friendlier-named alternative to `POST /read`).
|
||||
///
|
||||
/// Designed for ad-hoc exploration and AI-agent tool-use: short field
|
||||
/// names (`query`, `name`) match the CLI `-e` flag and the GQ `query`
|
||||
/// keyword. Mutations (`insert`/`update`/`delete`) are rejected with 400
|
||||
/// -- use `POST /mutate` (or its deprecated alias `POST /change`) for
|
||||
/// write queries. Otherwise behaves identically to `POST /read`: same
|
||||
/// target semantics (branch xor snapshot), same Cedar action (Read),
|
||||
/// same response shape.
|
||||
async fn server_query(
|
||||
Extension(handle): Extension<Arc<GraphHandle>>,
|
||||
actor: Option<Extension<ResolvedActor>>,
|
||||
Json(request): Json<QueryRequest>,
|
||||
) -> std::result::Result<Json<ReadOutput>, ApiError> {
|
||||
let (selected_name, target, result) = run_query(
|
||||
handle,
|
||||
actor.as_ref().map(|Extension(actor)| actor),
|
||||
&request.query,
|
||||
request.name.as_deref(),
|
||||
request.params.as_ref(),
|
||||
request.branch,
|
||||
request.snapshot,
|
||||
true, // /query is read-only; reject mutations
|
||||
)
|
||||
.await?;
|
||||
Ok(Json(api::read_output(selected_name, &target, result)))
|
||||
}
|
||||
|
||||
|
|
@ -1725,44 +1772,31 @@ async fn server_export(
|
|||
.into_response())
|
||||
}
|
||||
|
||||
#[utoipa::path(
|
||||
post,
|
||||
path = "/change",
|
||||
tag = "mutations",
|
||||
operation_id = "change",
|
||||
request_body = ChangeRequest,
|
||||
responses(
|
||||
(status = 200, description = "Mutation results", body = ChangeOutput),
|
||||
(status = 400, description = "Bad request", body = ErrorOutput),
|
||||
(status = 401, description = "Unauthorized", body = ErrorOutput),
|
||||
(status = 403, description = "Forbidden", body = ErrorOutput),
|
||||
(status = 409, description = "Merge conflict", body = ErrorOutput),
|
||||
(status = 429, description = "Per-actor admission cap exceeded; honor `Retry-After` header", body = ErrorOutput),
|
||||
),
|
||||
security(("bearer_token" = [])),
|
||||
)]
|
||||
/// Apply a GQ mutation to a branch.
|
||||
/// Shared implementation behind `POST /mutate` (canonical) and
|
||||
/// `POST /change` (deprecated alias). Returns the bare `ChangeOutput`;
|
||||
/// each route handler wraps it (the alias also attaches Deprecation
|
||||
/// headers).
|
||||
/// Shared backend for `/mutate` (canonical) and `/change` (deprecated alias).
|
||||
///
|
||||
/// Writes to the named `branch` (defaults to `main`). Mutations are atomic
|
||||
/// per call and produce a new commit. Returns counts of nodes and edges
|
||||
/// affected. **Destructive**: on success the branch is updated; rejected
|
||||
/// mutations may still acquire locks briefly. Returns 409 on merge conflict.
|
||||
async fn server_change(
|
||||
State(state): State<AppState>,
|
||||
Extension(handle): Extension<Arc<GraphHandle>>,
|
||||
actor: Option<Extension<ResolvedActor>>,
|
||||
Json(request): Json<ChangeRequest>,
|
||||
) -> std::result::Result<Json<ChangeOutput>, ApiError> {
|
||||
let branch = request.branch.unwrap_or_else(|| "main".to_string());
|
||||
/// Decoupled from `ChangeRequest` so MR-969's `/queries/{name}` stored-query
|
||||
/// handler can call this directly with registry-supplied fields without
|
||||
/// rebuilding the request body. Today's HTTP handlers unpack the request and
|
||||
/// call here; the registry would do the same.
|
||||
async fn run_mutate(
|
||||
state: AppState,
|
||||
handle: Arc<GraphHandle>,
|
||||
actor: Option<&ResolvedActor>,
|
||||
query: &str,
|
||||
name: Option<&str>,
|
||||
params_json: Option<&Value>,
|
||||
branch: String,
|
||||
) -> std::result::Result<ChangeOutput, ApiError> {
|
||||
let actor_arc = actor
|
||||
.as_ref()
|
||||
.map(|Extension(actor)| Arc::clone(&actor.actor_id))
|
||||
.map(|a| Arc::clone(&a.actor_id))
|
||||
.unwrap_or_else(|| Arc::<str>::from("anonymous"));
|
||||
let actor_id = actor
|
||||
.as_ref()
|
||||
.map(|Extension(actor)| actor.actor_id.as_ref());
|
||||
let actor_id = actor.map(|a| a.actor_id.as_ref());
|
||||
authorize_request(
|
||||
actor.as_ref().map(|Extension(actor)| actor),
|
||||
actor,
|
||||
handle.policy.as_deref(),
|
||||
PolicyRequest {
|
||||
action: PolicyAction::Change,
|
||||
|
|
@ -1774,10 +1808,8 @@ async fn server_change(
|
|||
// estimated bytes per actor. Cedar runs FIRST so denied requests
|
||||
// don't consume admission slots. Estimate uses the request body
|
||||
// size as a coarse proxy; engine memory pressure can run higher.
|
||||
let est_bytes = request.query_source.len() as u64
|
||||
+ request
|
||||
.params
|
||||
.as_ref()
|
||||
let est_bytes = query.len() as u64
|
||||
+ params_json
|
||||
.map(|p| p.to_string().len() as u64)
|
||||
.unwrap_or(0);
|
||||
let _admission = state
|
||||
|
|
@ -1785,30 +1817,188 @@ async fn server_change(
|
|||
.try_admit(&actor_arc, est_bytes)
|
||||
.map_err(ApiError::from_workload_reject)?;
|
||||
let (selected_name, query_params) =
|
||||
select_named_query(&request.query_source, request.query_name.as_deref())
|
||||
.map_err(|err| ApiError::bad_request(err.to_string()))?;
|
||||
let params = query_params_from_json(&query_params, request.params.as_ref())
|
||||
select_named_query(query, name).map_err(|err| ApiError::bad_request(err.to_string()))?;
|
||||
let params = query_params_from_json(&query_params, params_json)
|
||||
.map_err(|err| ApiError::bad_request(err.to_string()))?;
|
||||
|
||||
let result = {
|
||||
let db = &handle.engine;
|
||||
db.mutate_as(
|
||||
&branch,
|
||||
&request.query_source,
|
||||
&selected_name,
|
||||
¶ms,
|
||||
actor_id,
|
||||
)
|
||||
.await
|
||||
.map_err(ApiError::from_omni)?
|
||||
db.mutate_as(&branch, query, &selected_name, ¶ms, actor_id)
|
||||
.await
|
||||
.map_err(ApiError::from_omni)?
|
||||
};
|
||||
Ok(Json(ChangeOutput {
|
||||
Ok(ChangeOutput {
|
||||
branch,
|
||||
query_name: selected_name,
|
||||
affected_nodes: result.affected_nodes,
|
||||
affected_edges: result.affected_edges,
|
||||
actor_id: actor_id.map(str::to_string),
|
||||
}))
|
||||
})
|
||||
}
|
||||
|
||||
/// Shared backend for `/query` (canonical) and `/read` (deprecated alias).
|
||||
///
|
||||
/// Mirrors [`run_mutate`]'s decoupled shape so MR-969's stored-query handler
|
||||
/// can call here with registry-supplied fields. Rejects inline source that
|
||||
/// contains mutations (D2 rule); callers wanting writes go through
|
||||
/// [`run_mutate`] instead.
|
||||
///
|
||||
/// Intentionally does **not** take [`AppState`] (unlike [`run_mutate`]):
|
||||
/// reads are not admission-gated today, so there is no `state.workload`
|
||||
/// consumer. The signature grows the parameter when Phase 1 (MR-976) adds
|
||||
/// the request envelope's `expect: { max_rows_scanned: N }` budget, or
|
||||
/// MR-969 extends per-actor admission to stored-read invocations.
|
||||
async fn run_query(
|
||||
handle: Arc<GraphHandle>,
|
||||
actor: Option<&ResolvedActor>,
|
||||
query: &str,
|
||||
name: Option<&str>,
|
||||
params_json: Option<&Value>,
|
||||
branch: Option<String>,
|
||||
snapshot: Option<String>,
|
||||
reject_mutations: bool,
|
||||
) -> std::result::Result<(String, ReadTarget, omnigraph_compiler::result::QueryResult), ApiError> {
|
||||
if branch.is_some() && snapshot.is_some() {
|
||||
return Err(ApiError::bad_request(
|
||||
"request may specify branch or snapshot, not both",
|
||||
));
|
||||
}
|
||||
|
||||
let target = read_target_from_request(branch, snapshot);
|
||||
let policy_branch = match &target {
|
||||
ReadTarget::Branch(branch) => Some(branch.clone()),
|
||||
ReadTarget::Snapshot(_) if handle.policy.is_some() && actor.is_some() => {
|
||||
let db = &handle.engine;
|
||||
db.resolved_branch_of(target.clone())
|
||||
.await
|
||||
.map(|branch| branch.or_else(|| Some("main".to_string())))
|
||||
.map_err(ApiError::from_omni)?
|
||||
}
|
||||
ReadTarget::Snapshot(_) => None,
|
||||
};
|
||||
authorize_request(
|
||||
actor,
|
||||
handle.policy.as_deref(),
|
||||
PolicyRequest {
|
||||
action: PolicyAction::Read,
|
||||
branch: policy_branch,
|
||||
target_branch: None,
|
||||
},
|
||||
)?;
|
||||
let query_decl =
|
||||
select_named_query_decl(query, name).map_err(|err| ApiError::bad_request(err.to_string()))?;
|
||||
if reject_mutations && !query_decl.mutations.is_empty() {
|
||||
return Err(ApiError::bad_request(format!(
|
||||
"query '{}' contains mutations (insert/update/delete); use POST /mutate for write queries",
|
||||
query_decl.name
|
||||
)));
|
||||
}
|
||||
let selected_name = query_decl.name.clone();
|
||||
let params = query_params_from_json(&query_decl.params, params_json)
|
||||
.map_err(|err| ApiError::bad_request(err.to_string()))?;
|
||||
|
||||
let result = {
|
||||
let db = &handle.engine;
|
||||
db.query(target.clone(), query, &selected_name, ¶ms)
|
||||
.await
|
||||
.map_err(ApiError::from_omni)?
|
||||
};
|
||||
Ok((selected_name, target, result))
|
||||
}
|
||||
|
||||
#[utoipa::path(
|
||||
post,
|
||||
path = "/change",
|
||||
tag = "mutations",
|
||||
operation_id = "change",
|
||||
request_body = ChangeRequest,
|
||||
responses(
|
||||
(status = 200, description = "Mutation results (response includes `Deprecation: true` + `Link: </mutate>; rel=\"successor-version\"`)", body = ChangeOutput),
|
||||
(status = 400, description = "Bad request", body = ErrorOutput),
|
||||
(status = 401, description = "Unauthorized", body = ErrorOutput),
|
||||
(status = 403, description = "Forbidden", body = ErrorOutput),
|
||||
(status = 409, description = "Merge conflict", body = ErrorOutput),
|
||||
(status = 429, description = "Per-actor admission cap exceeded; honor `Retry-After` header", body = ErrorOutput),
|
||||
),
|
||||
security(("bearer_token" = [])),
|
||||
)]
|
||||
#[deprecated(note = "use POST /mutate instead; /change is kept indefinitely for back-compat")]
|
||||
/// **Deprecated** — use [`POST /mutate`](#tag/mutations/operation/mutate) instead.
|
||||
///
|
||||
/// Apply a GQ mutation to a branch. Behavior is unchanged; the route is
|
||||
/// kept indefinitely for back-compat. New integrations should target
|
||||
/// `POST /mutate`, which has identical semantics and a name that pairs
|
||||
/// cleanly with `POST /query`. Responses from this route include
|
||||
/// `Deprecation: true` and `Link: </mutate>; rel="successor-version"`
|
||||
/// headers per RFC 9745 / RFC 8288 so SDKs and proxies can surface the
|
||||
/// signal.
|
||||
async fn server_change(
|
||||
State(state): State<AppState>,
|
||||
Extension(handle): Extension<Arc<GraphHandle>>,
|
||||
actor: Option<Extension<ResolvedActor>>,
|
||||
Json(request): Json<ChangeRequest>,
|
||||
) -> std::result::Result<([(HeaderName, HeaderValue); 2], Json<ChangeOutput>), ApiError> {
|
||||
let branch = request.branch.unwrap_or_else(|| "main".to_string());
|
||||
let output = run_mutate(
|
||||
state,
|
||||
handle,
|
||||
actor.as_ref().map(|Extension(actor)| actor),
|
||||
&request.query,
|
||||
request.name.as_deref(),
|
||||
request.params.as_ref(),
|
||||
branch,
|
||||
)
|
||||
.await?;
|
||||
Ok((
|
||||
deprecation_headers("</mutate>; rel=\"successor-version\""),
|
||||
Json(output),
|
||||
))
|
||||
}
|
||||
|
||||
#[utoipa::path(
|
||||
post,
|
||||
path = "/mutate",
|
||||
tag = "mutations",
|
||||
operation_id = "mutate",
|
||||
request_body = ChangeRequest,
|
||||
responses(
|
||||
(status = 200, description = "Mutation results", body = ChangeOutput),
|
||||
(status = 400, description = "Bad request", body = ErrorOutput),
|
||||
(status = 401, description = "Unauthorized", body = ErrorOutput),
|
||||
(status = 403, description = "Forbidden", body = ErrorOutput),
|
||||
(status = 409, description = "Merge conflict", body = ErrorOutput),
|
||||
(status = 429, description = "Per-actor admission cap exceeded; honor `Retry-After` header", body = ErrorOutput),
|
||||
),
|
||||
security(("bearer_token" = [])),
|
||||
)]
|
||||
/// Apply a GQ mutation to a branch (canonical mutation endpoint).
|
||||
///
|
||||
/// Writes to the named `branch` (defaults to `main`). Mutations are atomic
|
||||
/// per call and produce a new commit. Returns counts of nodes and edges
|
||||
/// affected. **Destructive**: on success the branch is updated; rejected
|
||||
/// mutations may still acquire locks briefly. Returns 409 on merge conflict.
|
||||
///
|
||||
/// Pairs with `POST /query` (read-only). The legacy `POST /change` route
|
||||
/// has identical semantics and is kept as a deprecated alias.
|
||||
async fn server_mutate(
|
||||
State(state): State<AppState>,
|
||||
Extension(handle): Extension<Arc<GraphHandle>>,
|
||||
actor: Option<Extension<ResolvedActor>>,
|
||||
Json(request): Json<ChangeRequest>,
|
||||
) -> std::result::Result<Json<ChangeOutput>, ApiError> {
|
||||
let branch = request.branch.unwrap_or_else(|| "main".to_string());
|
||||
Ok(Json(
|
||||
run_mutate(
|
||||
state,
|
||||
handle,
|
||||
actor.as_ref().map(|Extension(actor)| actor),
|
||||
&request.query,
|
||||
request.name.as_deref(),
|
||||
request.params.as_ref(),
|
||||
branch,
|
||||
)
|
||||
.await?,
|
||||
))
|
||||
}
|
||||
|
||||
#[utoipa::path(
|
||||
|
|
@ -2350,10 +2540,10 @@ fn read_target_from_request(branch: Option<String>, snapshot: Option<String>) ->
|
|||
}
|
||||
}
|
||||
|
||||
fn select_named_query(
|
||||
fn select_named_query_decl(
|
||||
query_source: &str,
|
||||
requested_name: Option<&str>,
|
||||
) -> Result<(String, Vec<omnigraph_compiler::query::ast::Param>)> {
|
||||
) -> Result<omnigraph_compiler::query::ast::QueryDecl> {
|
||||
let parsed = parse_query(query_source)?;
|
||||
let query = if let Some(name) = requested_name {
|
||||
parsed
|
||||
|
|
@ -2366,7 +2556,14 @@ fn select_named_query(
|
|||
} else {
|
||||
bail!("query file contains multiple queries; pass --name");
|
||||
};
|
||||
Ok(query)
|
||||
}
|
||||
|
||||
fn select_named_query(
|
||||
query_source: &str,
|
||||
requested_name: Option<&str>,
|
||||
) -> Result<(String, Vec<omnigraph_compiler::query::ast::Param>)> {
|
||||
let query = select_named_query_decl(query_source, requested_name)?;
|
||||
Ok((query.name, query.params))
|
||||
}
|
||||
|
||||
|
|
|
|||
Loading…
Add table
Add a link
Reference in a new issue