📝 Add comprehensive JavaDoc to org.restheart.polyglot and org.restheart.security packages of module commons

Author: ujibang

commons/src/main/java/org/restheart/polyglot/NodeQueue.java

@@ -22,17 +22,69 @@
 import java.util.Queue;
 import java.util.concurrent.LinkedBlockingDeque;
 
+/**
+ * A singleton queue implementation for communication between RESTHeart and Node.js polyglot environments.
+ * 
+ * <p>This class provides a thread-safe, blocking queue that facilitates data exchange between
+ * the Java-based RESTHeart server and JavaScript code running in a Node.js environment via
+ * GraalVM's polyglot capabilities.</p>
+ * 
+ * <p>The queue is implemented as a singleton to ensure a single shared communication channel
+ * across the entire application. It uses a {@link LinkedBlockingDeque} internally to provide
+ * thread-safe operations without explicit synchronization.</p>
+ * 
+ * <p>Example usage:</p>
+ * <pre>{@code
+ * // Get the singleton instance
+ * NodeQueue queue = NodeQueue.instance();
+ * 
+ * // Add data to the queue
+ * queue.queue().offer(someData);
+ * 
+ * // Check if running in Node.js context
+ * if (queue.isRunningOnNode()) {
+ *     // Perform Node.js specific operations
+ * }
+ * }</pre>
+ * 
+ * @author Andrea Di Cesare {@literal <andrea@softinstigate.com>}
+ * @since 8.0.0
+ */
 public class NodeQueue {
-    // a concurrent queue shared with Node
+    /**
+     * The concurrent queue used for communication with Node.js.
+     * This queue can safely be accessed from multiple threads.
+     */
     private final Queue<Object> queue;
+    
+    /**
+     * Flag indicating whether the current execution context is within a Node.js environment.
+     * This is set to true when RESTHeart is running with Node.js polyglot support enabled.
+     */
     private boolean runningOnNode = false;
 
+    /**
+     * Private constructor to enforce singleton pattern.
+     * Initializes the internal queue with a thread-safe {@link LinkedBlockingDeque}.
+     */
     private NodeQueue() {
       this.queue = new LinkedBlockingDeque<>();
     }
 
+    /**
+     * The singleton instance of NodeQueue.
+     */
     private static NodeQueue instance;
 
+    /**
+     * Returns the singleton instance of NodeQueue.
+     * 
+     * <p>This method lazily initializes the queue on first access. While not strictly
+     * thread-safe, the race condition is benign as multiple threads creating instances
+     * would create functionally identical objects, and only one would ultimately be used.</p>
+     * 
+     * @return the singleton NodeQueue instance
+     */
     public static NodeQueue instance() {
         if (instance == null) {
             instance = new NodeQueue();
@@ -41,14 +93,44 @@ public static NodeQueue instance() {
         return instance;
     }
 
+    /**
+     * Returns the underlying queue for direct manipulation.
+     * 
+     * <p>The returned queue is thread-safe and supports all standard {@link Queue} operations.
+     * Common operations include:</p>
+     * <ul>
+     *   <li>{@code offer(Object)} - adds an element to the queue</li>
+     *   <li>{@code poll()} - retrieves and removes the head element, or returns null if empty</li>
+     *   <li>{@code peek()} - retrieves but does not remove the head element</li>
+     * </ul>
+     * 
+     * @return the concurrent queue instance
+     */
     public Queue<Object> queue() {
         return queue;
     }
 
+    /**
+     * Checks whether the current execution context is within a Node.js environment.
+     * 
+     * <p>This method is typically used to conditionally execute code based on whether
+     * RESTHeart is running with Node.js polyglot support enabled.</p>
+     * 
+     * @return {@code true} if running in a Node.js context, {@code false} otherwise
+     */
     public boolean isRunningOnNode() {
         return runningOnNode;
     }
 
+    /**
+     * Marks this instance as running within a Node.js environment.
+     * 
+     * <p>This method should only be called by the polyglot initialization code when
+     * setting up the Node.js execution context. Once set, this flag cannot be unset.</p>
+     * 
+     * <p><strong>Note:</strong> This method is not thread-safe and should only be called
+     * during application initialization.</p>
+     */
     public void setAsRunningOnNode() {
         this.runningOnNode = true;
     }

commons/src/main/java/org/restheart/security/ACLRegistry.java

@@ -26,62 +26,139 @@
 /**
  * Registry for defining Access Control Lists (ACLs) programmatically.
  *
- * This registry is utilized by the {@code ACLRegistryVetoer} and {@code ACLRegistryAllower} authorizers
- * to manage request permissions. The {@code ACLRegistryVetoer} denies requests based on veto predicates,
- * while the {@code ACLRegistryAllower} grants permission to proceed with requests based on allow predicate.
+ * <p>This registry serves as a central repository for dynamic access control rules that can be
+ * registered at runtime. It is utilized by the {@code ACLRegistryVetoer} and {@code ACLRegistryAllower}
+ * authorizers to manage request permissions in a flexible, programmatic manner.</p>
  *
- * A request is permitted to proceed if it is not denied by any {@code ACLRegistryVetoer} and at least one
- * {@code ACLRegistryAllower} approves it.
+ * <h2>Authorization Model</h2>
+ * <p>The registry implements a two-phase authorization model:</p>
+ * <ol>
+ *   <li><strong>Veto Phase:</strong> The {@code ACLRegistryVetoer} evaluates all registered veto
+ *       predicates. If any predicate returns {@code true}, the request is immediately denied.</li>
+ *   <li><strong>Allow Phase:</strong> If not vetoed, the {@code ACLRegistryAllower} checks if at
+ *       least one allow predicate returns {@code true}. The request proceeds only if approved.</li>
+ * </ol>
  *
- * Example usage:
- * <pre>
- * {@code
+ * <p>A request is permitted to proceed if and only if:</p>
+ * <ul>
+ *   <li>It is not denied by any {@code ACLRegistryVetoer} predicates, AND</li>
+ *   <li>At least one {@code ACLRegistryAllower} predicate approves it</li>
+ * </ul>
+ *
+ * <h2>Example Usage</h2>
+ * <pre>{@code
  * @Inject("acl-registry")
  * ACLRegistry registry;
  *
  * @OnInit
  * public void init() {
- *  registry.registerVeto(request -> request.getPath().equals("/deny"));
- *  registry.registerAllow(request -> request.getPath().equals("/allow"));
- * }
+ *     // Deny all requests to /admin from non-admin users
+ *     registry.registerVeto(request -> 
+ *         request.getPath().startsWith("/admin") && 
+ *         !request.isAccountInRole("admin")
+ *     );
+ *     
+ *     // Allow authenticated users to access /api
+ *     registry.registerAllow(request -> 
+ *         request.getPath().startsWith("/api") && 
+ *         request.isAuthenticated()
+ *     );
+ *     
+ *     // Require authentication for all /secure paths
+ *     registry.registerAuthenticationRequirement(request ->
+ *         request.getPath().startsWith("/secure")
+ *     );
  * }
- * </pre>
+ * }</pre>
  *
  * @author Andrea Di Cesare {@literal <andrea@softinstigate.com>}
+ * @since 6.0.0
+ * @see org.restheart.security.plugins.authorizers.ACLRegistryVetoer
+ * @see org.restheart.security.plugins.authorizers.ACLRegistryAllower
  */
 public interface ACLRegistry {
     /**
      * Registers a veto predicate that determines if a request should be denied.
-     * When the predicate evaluates to true, the request is immediately forbidden (vetoed).
-     * Additionally, a request will also be denied if it is not explicitly authorized by any
-     * allow predicates or any other active allowing authorizers.
+     * 
+     * <p>When the predicate evaluates to {@code true}, the request is immediately forbidden (vetoed)
+     * with no further evaluation. This provides a mechanism for implementing hard denials that cannot
+     * be overridden by allow rules.</p>
+     * 
+     * <p>Common use cases for veto predicates include:</p>
+     * <ul>
+     *   <li>Blocking access to sensitive administrative endpoints</li>
+     *   <li>Enforcing IP-based access restrictions</li>
+     *   <li>Preventing access during maintenance windows</li>
+     *   <li>Implementing rate limiting or abuse prevention</li>
+     * </ul>
+     * 
+     * <p><strong>Note:</strong> Veto predicates are evaluated before allow predicates. A single
+     * veto is sufficient to deny a request, regardless of any allow rules.</p>
      *
-     * @param veto The veto predicate to register. This predicate should return true to veto (deny) the request,
-     *             and false to let the decision be further evaluated by allow predicates or other authorizers.
+     * @param veto The veto predicate to register. This predicate should return {@code true} to veto
+     *             (deny) the request, and {@code false} to let the decision be further evaluated
+     *             by allow predicates or other authorizers
+     * @throws NullPointerException if the veto predicate is null
      */
     public void registerVeto(Predicate<Request<?>> veto);
 
     /**
      * Registers an allow predicate that determines if a request should be authorized.
-     * The request is authorized if this predicate evaluates to true, provided that no veto predicates
-     * or other active vetoer authorizers subsequently deny the request. This method helps in setting up
-     * conditions under which requests can proceed unless explicitly vetoed.
+     * 
+     * <p>The request is authorized if this predicate evaluates to {@code true}, provided that no
+     * veto predicates or other active vetoer authorizers have denied the request. Multiple allow
+     * predicates can be registered, and the request proceeds if any one of them returns {@code true}.</p>
+     * 
+     * <p>Common use cases for allow predicates include:</p>
+     * <ul>
+     *   <li>Granting access based on user roles or permissions</li>
+     *   <li>Implementing path-based access control</li>
+     *   <li>Allowing access based on request headers or parameters</li>
+     *   <li>Implementing custom business logic for authorization</li>
+     * </ul>
+     * 
+     * <p><strong>Important:</strong> Allow predicates are only evaluated if no veto predicates
+     * have denied the request. At least one allow predicate must return {@code true} for the
+     * request to be authorized.</p>
      *
-     * @param allow The allow predicate to register. This predicate should return true to authorize the request,
-     *              unless it is vetoed by any veto predicates or other vetoing conditions.
+     * @param allow The allow predicate to register. This predicate should return {@code true} to
+     *              authorize the request, unless it is vetoed by any veto predicates or other
+     *              vetoing conditions
+     * @throws NullPointerException if the allow predicate is null
      */
     public void registerAllow(Predicate<Request<?>> allow);
 
     /**
-     * Registers a predicate that determines whether requests handled by the ACLRegistryAllower
-     * require authentication. This method is used to specify conditions under which authentication
-     * is mandatory. Typically, authentication is required unless there are allow predicates
-     * explicitly authorizing requests that are not authenticated.
-     *
+     * Registers a predicate that determines whether requests require authentication.
+     * 
+     * <p>This method is used to specify conditions under which authentication is mandatory before
+     * authorization rules are evaluated. When the predicate returns {@code true}, the request must
+     * have valid authentication credentials; otherwise, it will be rejected with a 401 Unauthorized
+     * status.</p>
+     * 
+     * <p>Authentication requirements are evaluated before authorization rules. This ensures that
+     * sensitive endpoints can enforce authentication regardless of allow predicates.</p>
+     * 
+     * <p>Common use cases include:</p>
+     * <ul>
+     *   <li>Requiring authentication for all API endpoints</li>
+     *   <li>Enforcing authentication for specific URL patterns</li>
+     *   <li>Making authentication mandatory for certain HTTP methods</li>
+     *   <li>Implementing mixed authentication models (some paths public, others protected)</li>
+     * </ul>
+     * 
+     * <p>Example:</p>
+     * <pre>{@code
+     * // Require authentication for all paths except /public
+     * registry.registerAuthenticationRequirement(request ->
+     *     !request.getPath().startsWith("/public")
+     * );
+     * }</pre>
      *
      * @param authenticationRequired The predicate to determine if authentication is necessary.
-     *                               It should return true if the request must be authenticated,
-     *                               otherwise false if unauthenticated requests might be allowed.
+     *                               It should return {@code true} if the request must be authenticated,
+     *                               otherwise {@code false} if unauthenticated requests might be allowed
+     * @throws NullPointerException if the authenticationRequired predicate is null
      */
     public void registerAuthenticationRequirement(Predicate<Request<?>> authenticationRequired);