gitlab-glaz 2.0.0 → 2.2.0

data/Cargo.toml

@@ -4,14 +4,14 @@ members = ["ext/*"]
 resolver = "2"
 
 [workspace.package]
-version = "2.0.0"
+version = "2.2.0"
 edition = "2024"
 
 # Shared dependencies for all crates
 [workspace.dependencies]
-magnus = { version = "0.8.2", features = ["rb-sys"] }
+magnus = { version = "0.9.0", features = ["rb-sys"] }
 rb-sys = "0.9.128"
 prost = "0.14"
-glaz-module = { git = "https://gitlab.com/gitlab-org/auth/glaz.git", rev = "0c90ffcd6e6f74b7a1998e196e7d324ad7d54b56" }
-glaz-roles = { git = "https://gitlab.com/gitlab-org/auth/glaz.git", rev = "0c90ffcd6e6f74b7a1998e196e7d324ad7d54b56" }
-glaz-proto = { git = "https://gitlab.com/gitlab-org/auth/glaz.git", rev = "0c90ffcd6e6f74b7a1998e196e7d324ad7d54b56" }
+glaz-module = { git = "https://gitlab.com/gitlab-org/auth/glaz.git", rev = "432611dc73b9a98cf0a2557225155c768b9a14ea" }
+glaz-roles = { git = "https://gitlab.com/gitlab-org/auth/glaz.git", rev = "432611dc73b9a98cf0a2557225155c768b9a14ea" }
+glaz-proto = { git = "https://gitlab.com/gitlab-org/auth/glaz.git", rev = "432611dc73b9a98cf0a2557225155c768b9a14ea" }

data/README.md

@@ -39,7 +39,24 @@ Schemas must declare `User` and `Resource` entities (checks build `User::"<subje
 
 ### Governance policies
 
-`Gitlab::Glaz::GovernPolicyEngine` evaluates the Rego governance policies that apply to an event trigger. The engine fetches them itself from the Policy Store REST API, so name the store first:
+`Gitlab::Glaz::GovernPolicyEngine` evaluates the Rego governance policies that apply to an event trigger. A caller that already has the policies (the Policy Store itself, running the engine in-process) passes the active policies of the trigger and organization on the call, shaped like the store's policy entity, and no store is contacted:
+
+```ruby
+result = Gitlab::Glaz.govern_policy_engine.evaluate(
+  trigger: 'deployment_requested',
+  context: { organization: { id: 'organizations/1' }, environment: { tier: 'production' }, approvals: [] },
+  principal: 'users/42',
+  resource: 'organizations/1/deployments/9',
+  policies: [
+    { id: 1, name: 'Approve production', trigger_type: 'deployment_requested', organization_id: 1,
+      namespace_id: nil, # the owning group's id, or nil for an organization-level policy
+      mode: 'enforce', scope_rego: nil, scope_dimensions: [], policy_rego: "package governance\n...",
+      actions: [{ type: 'block', value: { message: 'Needs approval' } }] }
+  ]
+)
+```
+
+A policy that belongs to another trigger or organization, or to a namespace outside the hierarchy the context names in `groups`, raises `ArgumentError` for the whole call. An empty Array is a successful, empty evaluation. Any other caller leaves `policies:` out and the engine fetches the policies from the Policy Store REST API, so name the store first:
 
 ```ruby
 Gitlab::Glaz::GovernPolicyEngine.policy_store_url = 'https://gitlab.com/api/v4'
@@ -52,14 +69,20 @@ result = Gitlab::Glaz.govern_policy_engine.evaluate(
   resource: 'organizations/1/deployments/9', # what the decision is about
   store_authorization: "Bearer #{token}" # per request; nil sends no Authorization header
 )
-# => { decisions: [{ policy_id: 1, matched: true, actions: [{ action_type: 'block', gating: true, ... }], ... }],
+# => { decisions: [{ policy_id: 1, name: 'Approve production', mode: 'enforce', matched: true,
+#                    actions: [{ action_type: 'block', gating: true, ... }], ... }],
 #      undecided_policy_ids: [],
-#      identifier: 'ed9cb624-7d8f-51eb-ad5a-ef394efcee74' }
+#      identifier: 'ed9cb624-7d8f-51eb-ad5a-ef394efcee74',
+#      dry_run: false }
 ```
 
-Each call makes one `GET {store_url}/organizations/{id}/security/policy_store?trigger_type={trigger}` (500 ms connect / 2 s total timeout by default, no redirects, TLS against the platform trust store, `*_PROXY`/`NO_PROXY` honoured), so egress rules must allow it. Deny when any returned action is `gating` or `undecided_policy_ids` is non-empty; allow otherwise. Caller mistakes raise `ArgumentError`, store faults raise `RuntimeError`, and a policy that could not be decided (broken, or over the per-evaluation time budget) is reported in-band on its decision's `error` and listed in `undecided_policy_ids`. `data` must not define a policy's own `violation`/`deny`/`allow` rules. `principal` and `resource` name the decision subject (each trimmed, and rejected if blank, newline-carrying, or over 64 KiB); the response's `identifier` is a stable UUIDv5 over `(principal, trigger, resource)`, so re-evaluating the same subject yields the same identifier for journaling, action deduplication, and approval correlation.
+Each call without `policies:` makes one `GET {store_url}/organizations/{id}/security/policy_store?trigger_type={trigger}` (500 ms connect / 2 s total timeout by default, no redirects, TLS against the platform trust store, `*_PROXY`/`NO_PROXY` honoured), so egress rules must allow it. Deny when any returned action is `gating` or `undecided_policy_ids` is non-empty; allow otherwise. Caller mistakes raise `ArgumentError`, store faults raise `RuntimeError`, and a policy that could not be decided (broken, or over the per-evaluation time budget) is reported in-band on its decision's `error` and listed in `undecided_policy_ids`. `data` must not define a policy's own `violation`/`deny`/`allow` rules. `principal` and `resource` name the decision subject (each trimmed, and rejected if blank, newline-carrying, or over 64 KiB); the response's `identifier` is a stable UUIDv5 over `(principal, trigger, resource)`, so re-evaluating the same subject yields the same identifier for journaling, action deduplication, and approval correlation.
+
+`#evaluate_dry_run` takes the same arguments and returns the same result with `dry_run: true`, to preview what the policies would decide. It is never a gate: do not deny on its result, and nothing records it.
+
+`#list_policies(trigger:, context:, store_authorization: nil, policies: nil)` answers a different question: which policies could ever apply here. It needs only the trigger and the lookup keys (`organization.id`, plus, for the project settings triggers, the project's namespace hierarchy: `groups`, and `project.namespace_id` for a personal project), runs no policy's rules and returns `{ policies: [{ policy_id:, name:, applicability:, missing_dimensions:, error: }] }`, with nothing to gate on. `applicability` is `"applies"`, `"not_applicable"` or `"might_apply"`; a `"might_apply"` row lists in `missing_dimensions` the context paths to supply to settle it. A row whose scope could not be evaluated has a nil `applicability` and its `error`.
 
-Without a store URL the shared engine still serves `#validate` (save-time parse check) and `#debug_evaluate` (raw single-policy evaluation); only trigger-keyed evaluation needs the store. See the class documentation for the full contract.
+Without a store URL the shared engine still serves `#validate` (save-time parse check) and `#debug_evaluate` (raw single-policy evaluation); only `#evaluate`, `#evaluate_dry_run` and `#list_policies` need the store, and only when called without `policies:`. See the class documentation for the full contract.
 
 ## Development
 

data/ext/glaz/src/lib.rs

@@ -59,8 +59,10 @@ impl PermissionCheckEngine {
 }
 
 /// Thin 1:1 wrapper around `glaz_module::GovernPolicyCheckEngine`, the Rego
-/// governance evaluator. The policy lookup fetches from the Policy Store
-/// REST API named at construction; authentication is per request, on
+/// governance evaluator. A request may carry its own policies
+/// (`EvaluateGovernPolicyRequest.policies`); then no lookup runs. Otherwise
+/// the lookup fetches from the Policy Store REST API named at construction,
+/// authenticated per request on
 /// `EvaluateGovernPolicyRequest.store_authorization`. Stateless between
 /// calls. `evaluate_policies` raises on a whole-call failure (matching
 /// `PermissionCheckEngine`'s convention): `ArgumentError` for caller
@@ -81,8 +83,9 @@ impl GovernPolicyEngine {
     /// `base_url` is the Policy Store REST API root (e.g.
     /// `"https://gitlab.com/api/v4"`); `nil` timeouts keep
     /// `glaz-govern`'s defaults. Without `base_url` the engine has no policy
-    /// source: `validate` and `debug_evaluate` work, `evaluate_policies`
-    /// fails closed (see `NoStore`).
+    /// lookup: `validate` and `debug_evaluate` work, and `evaluate_policies`
+    /// works for a request that carries its own policies. Any other
+    /// `evaluate_policies` call fails closed (see `NoStore`).
     fn initialize(
         base_url: Option<String>,
         connect_timeout_ms: Option<u64>,
@@ -130,10 +133,10 @@ impl GovernPolicyEngine {
     }
 
     /// Trigger-keyed batch evaluation: takes an encoded
-    /// `EvaluateGovernPolicyRequest`, resolves the applicable policies from
-    /// the Policy Store (keyed on `trigger` and the context's
-    /// `organization.id`) and returns the encoded
-    /// `EvaluateGovernPolicyResponse`. Raises `ArgumentError` for caller
+    /// `EvaluateGovernPolicyRequest`, takes the policies from the request's
+    /// `policies` when set and from the Policy Store otherwise (keyed on
+    /// `trigger` and the context's `organization.id`), and returns the
+    /// encoded `EvaluateGovernPolicyResponse`. Raises `ArgumentError` for caller
     /// faults and `RuntimeError` for backend faults — never an empty batch,
     /// which would read fail-open. A broken individual policy is reported
     /// in-band on its decision's `error`.
@@ -161,6 +164,56 @@ impl GovernPolicyEngine {
         Ok(ruby.str_from_slice(&response))
     }
 
+    /// Dry-run twin of `evaluate_policies` (GOVERN-004: a method of its own,
+    /// never a flag). Takes an encoded `EvaluateGovernPolicyRequest` with
+    /// `dry_run` set and returns the encoded response echoing it; same
+    /// errors, GVL release and thread handling as `evaluate_policies`.
+    fn evaluate_policies_dry_run(
+        ruby: &Ruby,
+        rb_self: &Self,
+        proto_bytes: magnus::RString,
+    ) -> Result<magnus::RString, Error> {
+        // Copy the request out of the Ruby string first: once the GVL is
+        // released the GC may move or free the buffer behind `as_slice`.
+        let request = unsafe { proto_bytes.as_slice() }.to_vec();
+        let engine = Arc::clone(&rb_self.engine);
+        let response = without_gvl(ruby, move || {
+            on_own_thread(move || {
+                engine
+                    .evaluate_policies_dry_run(&request)
+                    .map(|response| response.encode_to_vec())
+            })
+        })?
+        .map_err(|e| map_error(ruby, e))?;
+        Ok(ruby.str_from_slice(&response))
+    }
+
+    /// List an encoded `ListGovernPoliciesRequest`: every policy the lookup
+    /// resolves for the trigger and scope, each with whether it applies to
+    /// the context supplied. Evaluates no policy's rules, so the encoded
+    /// `ListGovernPoliciesResponse` carries nothing to gate on. Same errors,
+    /// GVL release and thread handling as `evaluate_policies`; a policy whose
+    /// scope fails to evaluate comes back in-band on its own row.
+    fn list_policies(
+        ruby: &Ruby,
+        rb_self: &Self,
+        proto_bytes: magnus::RString,
+    ) -> Result<magnus::RString, Error> {
+        // Copy the request out of the Ruby string first: once the GVL is
+        // released the GC may move or free the buffer behind `as_slice`.
+        let request = unsafe { proto_bytes.as_slice() }.to_vec();
+        let engine = Arc::clone(&rb_self.engine);
+        let response = without_gvl(ruby, move || {
+            on_own_thread(move || {
+                engine
+                    .list_policies(&request)
+                    .map(|response| response.encode_to_vec())
+            })
+        })?
+        .map_err(|e| map_error(ruby, e))?;
+        Ok(ruby.str_from_slice(&response))
+    }
+
     /// Parse and compile a Rego policy without evaluating it against input.
     ///
     /// Infallible for policy errors: parse failures and oversized input are
@@ -195,8 +248,9 @@ impl GovernPolicyEngine {
 
 /// The lookup of an engine constructed without a Policy Store: every
 /// lookup fails closed as `LookupError::Unavailable` (a `RuntimeError`), so
-/// such an engine can never report "nothing to enforce". The Ruby wrapper
-/// rejects the call earlier with configuration guidance.
+/// such an engine can never report "nothing to enforce" for a request
+/// without its own policies. The Ruby wrapper rejects that call earlier
+/// with configuration guidance.
 struct NoStore;
 
 impl glaz_module::PolicyLookup for NoStore {
@@ -213,12 +267,18 @@ impl glaz_module::PolicyLookup for NoStore {
 
 /// Return the default roles embedded in the extension at build time (parsed
 /// from glaz-roles' roles/**/*.yml) as an array of hashes shaped like
-/// `{ id: String, name: String, permissions: [String, ...] }`.
+/// `{ id: String, key: String, name: String, permissions: [String, ...] }`.
+///
+/// `key` is the role's stable machine identifier (e.g. `artifact_admin`),
+/// distinct from the human-facing `name` and from the `id` callers put in
+/// relationships. Callers reference a role by `key` instead of hardcoding
+/// its UUID or matching on its display name.
 fn roles(ruby: &Ruby) -> Result<magnus::RArray, Error> {
     let array = ruby.ary_new();
     for role in glaz_roles::default_roles() {
         let hash = ruby.hash_new();
         hash.aset(ruby.sym_new("id"), role.id.to_string())?;
+        hash.aset(ruby.sym_new("key"), role.key)?;
         hash.aset(ruby.sym_new("name"), role.name)?;
         let permissions = ruby.ary_new();
         for permission in &role.permissions {
@@ -374,6 +434,14 @@ fn init(ruby: &Ruby) -> Result<(), Error> {
         "evaluate_policies",
         magnus::method!(GovernPolicyEngine::evaluate_policies, 1),
     )?;
+    govern.define_method(
+        "evaluate_policies_dry_run",
+        magnus::method!(GovernPolicyEngine::evaluate_policies_dry_run, 1),
+    )?;
+    govern.define_method(
+        "list_policies",
+        magnus::method!(GovernPolicyEngine::list_policies, 1),
+    )?;
     govern.define_method("validate", magnus::method!(GovernPolicyEngine::validate, 1))?;
     Ok(())
 }