feat: US-001 - ManagerDriver accepts ActorQuery targets for gateway operations

Author: NathanFlurry

Cargo.lock

@@ -72,6 +72,7 @@ members = [
   axum-test = "17"
   base64 = "0.22"
   bcrypt = "0.13.0"
+  ciborium = "0.2"
   bytes = "1.6.0"
   cjson = "0.1"
   colored_json = "5.0.0"

Cargo.toml

@@ -26,3 +26,12 @@ When changing a versioned VBARE schema, follow the existing migration pattern.
      - `engine/sdks/rust/runner-protocol/src/lib.rs` `PROTOCOL_MK2_VERSION`
      - `engine/sdks/typescript/runner/src/mod.ts` `PROTOCOL_VERSION`
    - Update the Rust latest re-export in `engine/sdks/rust/runner-protocol/src/lib.rs` to the new generated module.
+
+## Guard matrix query paths
+
+- In `engine/packages/guard/src/routing/mod.rs`, query paths use the format `/gateway/{name};namespace=...;method=...;key=.../{path}` where the actor name is the path segment and matrix params follow it. Parse the name from the segment prefix (before the first `;`) and the remaining params from the raw segment after the first `;`, all before percent-decoding. Reject raw `@token` syntax, duplicate params, unknown params, `name` as a matrix param, and params missing `=`.
+- `namespace` is a required matrix param. The guard resolves it directly via `namespace::ops::resolve_for_name_global` instead of scanning all namespaces.
+- `crashPolicy` is an optional matrix param. When omitted, defaults to `Sleep`.
+- For `key`, split on literal commas first and percent-decode each component separately so empty components like `key=` and `a,,b` survive round trips.
+- Keep query `input` as validated raw CBOR bytes in the parsed guard query shape. Validate the base64url and CBOR structure via `ciborium` during parsing, but defer any higher-level input conversion to the later gateway resolution step.
+- In `engine/packages/guard/src/routing/pegboard_gateway.rs`, resolve query gateway paths by resolving the namespace from the matrix param, then choosing a runner selector. Query-path creation should fail on ambiguous runners instead of guessing.

engine/CLAUDE.md

@@ -12,7 +12,9 @@ path = "src/lib.rs"
 [dependencies]
 anyhow.workspace = true
 axum.workspace = true
+base64.workspace = true
 bytes.workspace = true
+ciborium.workspace = true
 futures.workspace = true
 gas.workspace = true
 http-body-util.workspace = true
@@ -23,19 +25,23 @@ tower.workspace = true
 hyper = "1.6.0"
 indoc.workspace = true
 lazy_static.workspace = true
+namespace.workspace = true
 once_cell.workspace = true
 pegboard-envoy.workspace = true
 pegboard-gateway.workspace = true
 pegboard-gateway2.workspace = true
 pegboard-runner.workspace = true
 pegboard.workspace = true
 regex.workspace = true
+rivet-api-types.workspace = true
+rivet-api-util.workspace = true
 rivet-api-builder.workspace = true
 rivet-api-public.workspace = true
 rivet-cache.workspace = true
 rivet-config.workspace = true
 rivet-data.workspace = true
 rivet-error.workspace = true
+rivet-types.workspace = true
 rivet-guard-core.workspace = true
 rivet-logs.workspace = true
 rivet-metrics.workspace = true

engine/artifacts/errors/guard.invalid_request.json

@@ -21,13 +21,24 @@ pub fn create_cache_key_function() -> CacheKeyFn {
 
 		// MARK: Path-based cache key
 		// Check for path-based actor routing
-		if let Some(actor_path_info) = parse_actor_path(req_ctx.path()) {
-			tracing::debug!("using path-based cache key for actor");
+		if let Some(actor_path_info) = parse_actor_path(req_ctx.path())? {
+			match actor_path_info {
+				crate::routing::ParsedActorPath::Direct(actor_path_info) => {
+					tracing::debug!("using path-based cache key for actor");
 
-			if let Ok(cache_key) =
-				pegboard_gateway::build_cache_key_path_based(req_ctx, &actor_path_info)
-			{
-				return Ok(cache_key);
+					if let Ok(cache_key) =
+						pegboard_gateway::build_cache_key_path_based(req_ctx, &actor_path_info)
+					{
+						return Ok(cache_key);
+					}
+				}
+				crate::routing::ParsedActorPath::Query(_) => {
+					// Query paths encode all routing params (namespace, name, method,
+					// key, input, region) as matrix params in the URL path. Hash the
+					// full path so different queries produce distinct cache keys.
+					tracing::debug!("using query-path cache key for actor");
+					return Ok(host_path_method_cache_key(req_ctx));
+				}
 			}
 		}
 

engine/packages/guard/Cargo.toml

@@ -70,3 +70,14 @@ pub struct MustUseRegionalHost {
 pub struct ActorRunnerFailed {
 	pub actor_id: Id,
 }
+
+#[derive(RivetError, Serialize)]
+#[error(
+	"guard",
+	"invalid_request",
+	"Invalid request.",
+	"{message}"
+)]
+pub struct InvalidRequest {
+	pub message: String,
+}