update documentation with missing piecese documented in v7 release notes

SoftInstigate/restheart#471

Author: ujibang

docs/graalvm.md

@@ -151,6 +151,18 @@ In order to use Java or Kotlin plugins on RESTHeart native you must build them a
 
 Refer to [Deploy Java Plugins On Restheart Native](https://restheart.org/docs/plugins/deploy/#deploy-java-plugins-on-restheart-native) for detailed instructions on how to do it.
 
+### Automatic reflection configuration for plugins
+
+Since RESTHeart v7, plugin reflection configuration for native images is handled automatically. RESTHeart implements a GraalVM feature that automatically generates the necessary reflection configuration for plugins annotated with `@RegisterPlugin`.
+
+This means you no longer need to manually maintain `reflect-config.json` files for your plugins. The reflection configuration is automatically generated at build time, streamlining the development process for plugins that will be bundled in RESTHeart native builds.
+
+The automatic reflection configuration covers:
+- Plugin classes annotated with `@RegisterPlugin`
+- Plugin initialization methods
+- Dependency injection fields and methods
+- Provider implementations
+
 ## build native image
 
 Build image for local OS

docs/plugins/interceptors.adoc

@@ -21,11 +21,13 @@ The special interceptor interface, `WildcardInterceptor`, intercepts requests ha
 - `JsonInterceptor`: Intercepts requests handled by services implementing `JsonService`
 - `BsonInterceptor`: Intercepts requests handled by services implementing `BsonService`
 - `MongoInterceptor`: Intercepts requests handled by the `MongoService`
-- `GraphQLInterceptor`: Intercepts GraphQL requests
+- `GraphQLInterceptor`: Intercepts GraphQL requests (available since RESTHeart v7)
 - `ProxyInterceptor`: Intercepts proxied requests
 
 NOTE: `MongoInterceptor` is particularly useful as it allows intercepting requests to the `MongoService`, adding logic to its data API. For instance, the following response interceptor removes the property `secret` from `GET /coll`.
 
+NOTE: `GraphQLInterceptor` became available in RESTHeart v7 when `GraphQLRequest` was moved to `restheart-commons`, enabling plugin developers to intercept and modify GraphQL requests and responses. This allows implementing custom logic such as query validation, result transformation, or access logging for GraphQL operations.
+
 [source,java]
 ----
 @RegisterPlugin(name = "secretFilter",

docs/plugins/services.adoc

@@ -83,12 +83,80 @@ The following table describes the arguments of the annotation for Services:
 |`true` to require successful authentication and authorization to be invoked; can be overridden by the service configuration option `secure`
 |no
 |`false`
+|`blocking`
+|`true` to execute the service in the worker thread pool (blocking mode), `false` to execute in the IO thread (non-blocking mode)
+|no
+|`true`
 |`dontIntercept`
 |list of interceptPoints to be executed on requests handled by the service, e.g. `dontIntercept = { InterceptPoint.ANY, InterceptPoint.RESPONSE }`
 |no
 |`{}`
 |===
 
+=== Blocking vs Non-Blocking Services
+
+RESTHeart allows you to control the execution model of your services using the `blocking` parameter in the `@RegisterPlugin` annotation.
+
+==== Blocking Services (Default)
+
+By default, services are executed in **blocking mode** (`blocking = true`). In this mode, when a request arrives, it is dispatched to a worker thread from the thread pool whose size is configured by the `worker-threads` parameter.
+
+This concurrency model performs well for CPU-bound and blocking operations, such as:
+- MongoDB operations executed with the `mongodb-driver-sync`
+- Database queries
+- File I/O operations
+- Network calls to external services
+
+[source,java]
+----
+@RegisterPlugin(
+    name = "blocking-service",
+    description = "A service that performs blocking operations",
+    blocking = true)  // Default value, can be omitted
+public class BlockingService implements JsonService {
+    @Override
+    public void handle(JsonRequest req, JsonResponse res) {
+        // Blocking operation - this will be executed in a worker thread
+        var result = performDatabaseQuery();
+        res.setContent(result);
+    }
+}
+----
+
+==== Non-Blocking Services
+
+For non-blocking operations, you can specify `blocking = false`. In this mode, the service is executed directly by the IO thread, avoiding the overhead of thread dispatching and context switching.
+
+This approach follows the **Event Loop** concurrency model and can perform better for:
+- Reactive operations
+- Async computations
+- Services that don't perform blocking I/O
+
+[source,java]
+----
+@RegisterPlugin(
+    name = "non-blocking-service",
+    description = "A service that performs non-blocking operations",
+    blocking = false)  // Enable non-blocking mode
+public class NonBlockingService implements JsonService {
+    @Override
+    public void handle(JsonRequest req, JsonResponse res) {
+        // Non-blocking operation - executed directly by IO thread
+        var result = performAsyncComputation();
+        res.setContent(result);
+    }
+}
+----
+
+==== Performance Considerations
+
+- **Blocking services**: Better for CPU-intensive tasks and operations that involve waiting for I/O
+- **Non-blocking services**: Better for lightweight operations and reactive programming patterns
+
+WARNING: Be careful not to perform blocking operations (like database calls) in non-blocking services, as this will block the IO thread and negatively impact performance.
+
+Since RESTHeart uses Virtual Threads, there are virtually no limits on the number of blocking threads.
+
 === Service with custom generic types
 
 To implement a `Service` that handles different types of `Request` and `Response`, it must implement the base `Service` interface.

docs/upgrade-to-v8.adoc

@@ -295,6 +295,28 @@ public void init() {
 }
 ```
 
+=== MongoService Driver Update
+
+RESTHeart v8 completes the migration from `mongo-driver-legacy` to `mongo-driver-sync` that was started in v7.
+
+*Impact for Plugin Developers*
+
+This change affects plugins that:
+- Use `@Inject("mclient")` to access the MongoDB client
+- Interact with MongoDB through the MongoService
+- Implement custom MongoDB operations
+
+*Benefits*
+
+- Improved performance and stability
+- Better alignment with MongoDB's current driver architecture
+- Enhanced support for modern MongoDB features
+- Consistent synchronous API patterns
+
+*Migration Notes*
+
+No code changes are required for existing plugins using `@Inject("mclient")`, as the injected `MongoClient` interface remains the same. The underlying implementation has been updated to use the modern MongoDB driver.
+
 === Lazy-load Request Content
 
 Up to RESTHeart v7, requests processed by the `MongoService` are designed to lazy-load their content. This means that the request body is only read when `MongoRequest.getContent()` is invoked for the first time.