gitlab-glaz 1.2.0 → 2.0.0

data/Cargo.toml

@@ -4,7 +4,7 @@ members = ["ext/*"]
 resolver = "2"
 
 [workspace.package]
-version = "1.2.0"
+version = "2.0.0"
 edition = "2024"
 
 # Shared dependencies for all crates
@@ -12,6 +12,6 @@ edition = "2024"
 magnus = { version = "0.8.2", features = ["rb-sys"] }
 rb-sys = "0.9.128"
 prost = "0.14"
-glaz-module = { git = "https://gitlab.com/gitlab-org/auth/glaz.git", rev = "af9019a186fbb42cede0ad5ba7496aff2f88cb41" }
-glaz-roles = { git = "https://gitlab.com/gitlab-org/auth/glaz.git", rev = "af9019a186fbb42cede0ad5ba7496aff2f88cb41" }
-glaz-proto = { git = "https://gitlab.com/gitlab-org/auth/glaz.git", rev = "af9019a186fbb42cede0ad5ba7496aff2f88cb41" }
+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" }

data/README.md

@@ -3,7 +3,7 @@
 > [!WARNING]
 > This gem is currently designed entirely for internal use at GitLab.
 
-Ruby bindings for the [Glaz](https://gitlab.com/gitlab-org/auth/glaz) authorization engine. A thin [Magnus](https://github.com/matsadler/magnus) FFI extension exposes the Rust `glaz-module` engine to Ruby, so Cedar policy checks run in-process.
+Ruby bindings for the [Glaz](https://gitlab.com/gitlab-org/auth/glaz) authorization and governance engines. A thin [Magnus](https://github.com/matsadler/magnus) FFI extension exposes the Rust `glaz-module` engines to Ruby: Cedar permission checks run in-process, and Rego governance policies are fetched from the Policy Store and evaluated in-process.
 
 ## Installation
 
@@ -37,6 +37,30 @@ The schema is loaded once at construction and cannot change; build a new engine
 
 Schemas must declare `User` and `Resource` entities (checks build `User::"<subject_uuid>"` and `Resource::"<object_uuid>"` UIDs), and every action's context type must include `permissions: Set<Action>`, which the engine injects with the checked action.
 
+### 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:
+
+```ruby
+Gitlab::Glaz::GovernPolicyEngine.policy_store_url = 'https://gitlab.com/api/v4'
+# or export GLAZ_POLICY_STORE_URL; a bare http(s) URL, no credentials
+
+result = Gitlab::Glaz.govern_policy_engine.evaluate(
+  trigger: 'deployment_requested',
+  context: { organization: { id: 'organizations/1' }, environment: { tier: 'production' }, approvals: [] },
+  principal: 'users/42', # who the decision is about
+  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, ... }], ... }],
+#      undecided_policy_ids: [],
+#      identifier: 'ed9cb624-7d8f-51eb-ad5a-ef394efcee74' }
+```
+
+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.
+
+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.
+
 ## Development
 
 ```shell

data/ext/glaz/Cargo.toml

@@ -13,3 +13,4 @@ glaz-proto = { workspace = true }
 glaz-roles = { workspace = true }
 magnus = { workspace = true }
 prost = { workspace = true }
+rb-sys = { workspace = true }

data/ext/glaz/src/lib.rs

@@ -1,3 +1,9 @@
+use std::ffi::c_void;
+use std::panic::{AssertUnwindSafe, catch_unwind, resume_unwind};
+use std::sync::Arc;
+use std::time::Duration;
+
+use magnus::rb_sys::AsRawValue;
 use magnus::{Error, Ruby, prelude::*};
 use prost::Message;
 
@@ -53,70 +59,106 @@ impl PermissionCheckEngine {
 }
 
 /// Thin 1:1 wrapper around `glaz_module::GovernPolicyCheckEngine`, the Rego
-/// governance evaluator. Stateless between calls; `evaluate` raises on
-/// failure (matching `PermissionCheckEngine`'s convention) and returns the
-/// encoded `EvaluateGovernPolicyResponse` on success — `ArgumentError` for
-/// bad policy/input, `RuntimeError` for an engine-side fault, see
-/// `map_error`; `debug_evaluate` is infallible and carries failures in-band
-/// in its JSON response instead, since it's a raw debugging escape hatch;
-/// `validate` is also infallible — policy errors are returned as
-/// `Ok(valid: false, errors: [...])` so the Policy Store can surface
-/// actionable feedback without treating a user mistake as an exceptional
-/// condition; a malformed protobuf payload raises `ArgumentError`, while
-/// internal engine failures (`NotInitialized`, `Runtime`) raise
-/// `RuntimeError` via `map_error`.
+/// governance evaluator. The policy lookup fetches from the Policy Store
+/// REST API named at construction; authentication is per request, on
+/// `EvaluateGovernPolicyRequest.store_authorization`. Stateless between
+/// calls. `evaluate_policies` raises on a whole-call failure (matching
+/// `PermissionCheckEngine`'s convention): `ArgumentError` for caller
+/// faults, `RuntimeError` for backend faults, see `map_error`.
+/// `debug_evaluate` and `validate` are infallible for policy errors, which
+/// they return in-band; only a malformed protobuf payload raises.
 ///
-/// Registered as `Glaz::Native::GovernPolicyEngine` (not
-/// `Glaz::GovernPolicyEngine`) specifically to avoid colliding, in name,
-/// with the polished `Gitlab::Glaz::GovernPolicyEngine` wrapper — this
-/// class is raw FFI plumbing; prefer the wrapper unless you specifically
-/// need `debug_evaluate`.
+/// Registered as `Glaz::Native::GovernPolicyEngine` to avoid colliding in
+/// name with the `Gitlab::Glaz::GovernPolicyEngine` wrapper — this class is
+/// raw FFI plumbing; prefer the wrapper.
 #[magnus::wrap(class = "Glaz::Native::GovernPolicyEngine")]
 struct GovernPolicyEngine {
-    engine: glaz_module::GovernPolicyCheckEngine,
+    // Shared with the per-call lookup thread, see `on_own_thread`.
+    engine: Arc<glaz_module::GovernPolicyCheckEngine>,
 }
 
 impl GovernPolicyEngine {
-    fn initialize() -> Self {
+    /// `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`).
+    fn initialize(
+        base_url: Option<String>,
+        connect_timeout_ms: Option<u64>,
+        timeout_ms: Option<u64>,
+    ) -> Self {
+        let Some(base_url) = base_url else {
+            return Self {
+                engine: Arc::new(glaz_module::GovernPolicyCheckEngine::with_lookup(NoStore)),
+            };
+        };
+        let mut config = glaz_module::StoreConfig::new(base_url);
+        if let Some(ms) = connect_timeout_ms {
+            config = config.with_connect_timeout(Duration::from_millis(ms));
+        }
+        if let Some(ms) = timeout_ms {
+            config = config.with_total_timeout(Duration::from_millis(ms));
+        }
         Self {
-            engine: glaz_module::GovernPolicyCheckEngine::new(),
+            engine: Arc::new(glaz_module::GovernPolicyCheckEngine::with_store(config)),
         }
     }
 
-    /// Evaluate using the request's `query` field. `query` must be
-    /// non-blank; a blank query is reported in-band as an error rather than
-    /// falling back to discovery (use `evaluate` for that).
+    /// Evaluate the request's `query` directly, with no
+    /// `violation`/`deny`/`allow` interpretation and no policy lookup. A
+    /// blank query is reported in-band.
+    ///
+    /// Runs with the GVL released (`without_gvl`), on its own thread where a
+    /// forked child needs one (`on_own_thread`): the parse it performs
+    /// parks the calling thread the same way `evaluate_policies`'s lookup
+    /// does. Not interruptible from Ruby until it returns.
     fn debug_evaluate(
         ruby: &Ruby,
         rb_self: &Self,
         proto_bytes: magnus::RString,
     ) -> Result<magnus::RString, Error> {
-        let bytes = unsafe { proto_bytes.as_slice() };
-        let response = rb_self.engine.debug_evaluate(bytes);
+        // 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 || Ok(engine.debug_evaluate(&request)))
+        })?
+        .map_err(|e| map_error(ruby, e))?;
         Ok(ruby.str_from_slice(&response))
     }
 
-    /// Evaluate by auto-discovering the policy's `violation`, `deny`,
-    /// and/or `allow` rules. The request's `query` field is ignored.
+    /// 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
+    /// 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`.
     ///
-    /// Raises on any evaluation failure rather than returning an in-band
-    /// error, matching `PermissionCheckEngine#check_action`'s convention.
-    /// `map_error` raises `ArgumentError` for malformed protobuf, invalid
-    /// policy, oversized documents, undefined results, or an unrecognized
-    /// result shape - all caller-fixable - and `RuntimeError` for an
-    /// engine-side fault (e.g. the Rego evaluation time budget was
-    /// exceeded), which is not.
-    fn evaluate(
+    /// Runs with the GVL released (`without_gvl`), on its own thread where
+    /// a forked child needs one (`on_own_thread`). Not interruptible from
+    /// Ruby until it returns.
+    fn evaluate_policies(
         ruby: &Ruby,
         rb_self: &Self,
         proto_bytes: magnus::RString,
     ) -> Result<magnus::RString, Error> {
-        let bytes = unsafe { proto_bytes.as_slice() };
-        let response = rb_self
-            .engine
-            .evaluate(bytes)
-            .map_err(|e| map_error(ruby, e))?;
-        Ok(ruby.str_from_slice(&response.encode_to_vec()))
+        // 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(&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.
@@ -125,17 +167,47 @@ impl GovernPolicyEngine {
     /// returned in-band as `{ valid: false, errors: [...] }` rather than
     /// raised. Only a malformed protobuf payload raises `ArgumentError`; an
     /// internal engine fault raises `RuntimeError` via `map_error`.
+    ///
+    /// Runs with the GVL released (`without_gvl`), on its own thread where a
+    /// forked child needs one (`on_own_thread`): the parse it performs
+    /// parks the calling thread the same way `evaluate_policies`'s lookup
+    /// does. Not interruptible from Ruby until it returns.
     fn validate(
         ruby: &Ruby,
         rb_self: &Self,
         proto_bytes: magnus::RString,
     ) -> Result<magnus::RString, Error> {
-        let bytes = unsafe { proto_bytes.as_slice() };
-        let response = rb_self
-            .engine
-            .validate(bytes)
-            .map_err(|e| map_error(ruby, e))?;
-        Ok(ruby.str_from_slice(&response.encode_to_vec()))
+        // 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
+                    .validate(&request)
+                    .map(|response| response.encode_to_vec())
+            })
+        })?
+        .map_err(|e| map_error(ruby, e))?;
+        Ok(ruby.str_from_slice(&response))
+    }
+}
+
+/// 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.
+struct NoStore;
+
+impl glaz_module::PolicyLookup for NoStore {
+    fn lookup(
+        &self,
+        _key: &glaz_module::LookupKey,
+        _store_authorization: &str,
+    ) -> Result<Vec<glaz_module::StoredPolicy>, glaz_module::LookupError> {
+        Err(glaz_module::LookupError::Unavailable(
+            "no Policy Store configured for this engine".to_string(),
+        ))
     }
 }
 
@@ -158,6 +230,109 @@ fn roles(ruby: &Ruby) -> Result<magnus::RArray, Error> {
     Ok(array)
 }
 
+/// Run `func` with the GVL released and hand its result back once the GVL
+/// is held again. `func` must not touch the Ruby VM, so callers copy their
+/// input out of Ruby objects first. A panic in `func` is caught at the
+/// `extern "C"` boundary and resumed afterwards.
+///
+/// No unblock function is registered, so `func` always runs to completion;
+/// a Ruby interrupt aimed at this thread takes effect once it returns.
+///
+/// Catching the panic requires `panic = "unwind"`, the default profile
+/// setting; magnus's method wrappers already rely on it to turn panics into
+/// Ruby exceptions, so an `abort` profile would break the extension as a
+/// whole, not just this helper.
+fn without_gvl<F, T>(ruby: &Ruby, func: F) -> Result<T, Error>
+where
+    F: FnOnce() -> T + Send,
+    T: Send,
+{
+    enum Call<F, T> {
+        Pending(F),
+        Done(std::thread::Result<T>),
+    }
+
+    unsafe extern "C" fn trampoline<F: FnOnce() -> T, T>(data: *mut c_void) -> *mut c_void {
+        // SAFETY: `data` is the `Call` below, which outlives this call.
+        let slot = unsafe { &mut *data.cast::<Option<Call<F, T>>>() };
+        let Some(Call::Pending(func)) = slot.take() else {
+            unreachable!("the trampoline runs exactly once, on a pending call");
+        };
+        *slot = Some(Call::Done(catch_unwind(AssertUnwindSafe(func))));
+        std::ptr::null_mut()
+    }
+
+    let mut call = Some(Call::Pending(func));
+    // `protect` catches Ruby unwinding out of the interrupt checks
+    // `rb_thread_call_without_gvl` performs before and after `func`.
+    let protected = magnus::rb_sys::protect(|| {
+        unsafe {
+            rb_sys::rb_thread_call_without_gvl(
+                Some(trampoline::<F, T>),
+                (&mut call as *mut Option<Call<F, T>>).cast::<c_void>(),
+                None,
+                std::ptr::null_mut(),
+            );
+        }
+        ruby.qnil().as_raw()
+    });
+
+    // A panic outranks an interrupt that arrived after it.
+    match call {
+        Some(Call::Done(Err(panic))) => resume_unwind(panic),
+        Some(Call::Done(Ok(value))) => protected.map(|_| value),
+        Some(Call::Pending(_)) | None => {
+            protected?;
+            unreachable!("rb_thread_call_without_gvl returned without running the call")
+        }
+    }
+}
+
+/// On Apple targets, run `func` on a native thread of its own; elsewhere,
+/// inline.
+///
+/// While resolving a host name under a timeout the HTTP client parks its
+/// thread, and on Apple targets Rust's `std` parks with a per-thread
+/// libdispatch semaphore. A forked child inherits the forking thread's
+/// semaphore and libdispatch aborts the process (`SIGTRAP`) on its first
+/// use, so a Unicorn worker evaluating on the thread its master evaluated
+/// on would crash. A fresh thread gets a fresh semaphore. Linux parks on a
+/// futex, which survives a fork.
+fn on_own_thread<F, T>(func: F) -> Result<T, glaz_module::GlazError>
+where
+    F: FnOnce() -> Result<T, glaz_module::GlazError> + Send + 'static,
+    T: Send + 'static,
+{
+    #[cfg(not(target_vendor = "apple"))]
+    {
+        func()
+    }
+    #[cfg(target_vendor = "apple")]
+    {
+        let handle = std::thread::Builder::new()
+            .name("glaz-policy-lookup".to_string())
+            // The main thread's 8 MiB rather than the 2 MiB spawn default.
+            .stack_size(8 << 20)
+            .spawn(func)
+            .map_err(|e| {
+                glaz_module::GlazError::Runtime(format!(
+                    "could not start the policy lookup thread: {e}"
+                ))
+            })?;
+        match handle.join() {
+            Ok(result) => result,
+            Err(panic) => resume_unwind(panic),
+        }
+    }
+}
+
+// The engine is called concurrently from any thread: other Ruby threads
+// while one waits outside the GVL, and the lookup thread on Apple targets.
+const _: () = {
+    const fn assert_sync_send<T: Sync + Send>() {}
+    assert_sync_send::<glaz_module::GovernPolicyCheckEngine>();
+};
+
 fn map_error(ruby: &Ruby, e: glaz_module::GlazError) -> Error {
     use glaz_module::GlazError::*;
     match e {
@@ -190,12 +365,15 @@ fn init(ruby: &Ruby) -> Result<(), Error> {
     )?;
     let native = glaz.define_module("Native")?;
     let govern = native.define_class("GovernPolicyEngine", ruby.class_object())?;
-    govern.define_singleton_method("new", magnus::function!(GovernPolicyEngine::initialize, 0))?;
+    govern.define_singleton_method("new", magnus::function!(GovernPolicyEngine::initialize, 3))?;
     govern.define_method(
         "debug_evaluate",
         magnus::method!(GovernPolicyEngine::debug_evaluate, 1),
     )?;
-    govern.define_method("evaluate", magnus::method!(GovernPolicyEngine::evaluate, 1))?;
+    govern.define_method(
+        "evaluate_policies",
+        magnus::method!(GovernPolicyEngine::evaluate_policies, 1),
+    )?;
     govern.define_method("validate", magnus::method!(GovernPolicyEngine::validate, 1))?;
     Ok(())
 }