RavenDB-27140 Sync Python Embedded with C#

labs/01-embedded-zero-config.md

@@ -17,10 +17,12 @@ The complete, runnable example is [`01_embedded_zero_config.py`](01_embedded_zer
 The core is just:
 
 ```python
-from ravendb_embedded import EmbeddedServer
+from ravendb_embedded import EmbeddedServer, ServerOptions
+
+options = ServerOptions()
 
 with EmbeddedServer() as server:
-    server.start_server()
+    server.start_server(options)
     with server.get_document_store("Lab") as store:
         with store.open_session() as session:
             session.store({"name": "Ayende"}, "people/1")
@@ -33,10 +35,10 @@ with EmbeddedServer() as server:
    server (`Raven.Server.dll`) that ships inside the wheel.
 2. `RavenServerRunner` launches it as **`dotnet Raven.Server.dll ...`**, using the `dotnet`
    found on your `PATH` (`ServerOptions.dot_net_path`).
-3. `ServerOptions.framework_version` is empty by default, so no `--fx-version` is passed and
-   standard .NET host resolution applies. The host does **not** roll forward across major
-   versions, which is why a net10.0 server hard-fails on a machine that only has .NET 8
-   (error: "You must install ... version 10.0.x").
+3. `ServerOptions.framework_version` defaults to `""`, leaving runtime selection and roll-forward
+   to the dotnet host. Set it to `auto` when you want the package to read
+   `Raven.Server.runtimeconfig.json` and select a compatible installed patch. A net10.0 server
+   still requires .NET 10.
 4. The one exception: point the server at a **self-contained** build (an apphost
    `Raven.Server` with the runtime bundled) and it runs **without `dotnet`**. That is Lab 02.
 

labs/04-embedded-secured.md

@@ -30,10 +30,13 @@ with EmbeddedServer() as server:
 
 ## Certificates
 
-`secured()` needs a server `.pfx` and a client `.pem`; a password and a CA certificate are
-optional. In production you bring your own (for example from RavenDB's setup wizard or your CA).
-The lab generates a throwaway self-signed pair so it can run unattended; that generator is demo
-code, not something to ship. A RavenDB server certificate needs the right extensions
+The server `.pfx` is required. The client `.pem` is needed when `EmbeddedServer` creates
+authenticated document stores; a password and a CA certificate are optional. To configure only
+the HTTPS server and use clients managed elsewhere, call `options.secured(server_pfx_path)`.
+
+In production you bring your own certificates (for example from RavenDB's setup wizard or your
+CA). The lab generates a throwaway self-signed pair so it can run unattended; that generator is
+demo code, not something to ship. A RavenDB server certificate needs the right extensions
 (digitalSignature key usage, serverAuth/clientAuth EKU, and SANs for how the server is reached),
 which the lab's generator sets.
 

labs/04_embedded_secured.py

@@ -65,6 +65,8 @@ def _demo_certificates(directory):
         .add_extension(
             x509.ExtendedKeyUsage([ExtendedKeyUsageOID.SERVER_AUTH, ExtendedKeyUsageOID.CLIENT_AUTH]), critical=False
         )
+        .add_extension(x509.SubjectKeyIdentifier.from_public_key(key.public_key()), critical=False)
+        .add_extension(x509.AuthorityKeyIdentifier.from_issuer_public_key(key.public_key()), critical=False)
         .sign(key, hashes.SHA256())
     )
     cert_pem = cert.public_bytes(serialization.Encoding.PEM)

labs/05-embedded-persistent.md

@@ -37,8 +37,9 @@ with EmbeddedServer() as server:
 
 ## Notes
 
-- The default `data_directory` is a folder under the package location, which is fine for tests
-  but not what you want for real data. Set it explicitly to a path you control.
+- The default `data_directory` remains `RavenDB` inside the installed package directory. Set it
+  explicitly when the package directory may be read-only or the application needs a fixed,
+  application-owned location.
 - `get_document_store("Lab")` reuses the existing database on the second run; it only creates one
   when it is missing.
 

labs/06-embedded-lifecycle.md

@@ -0,0 +1,56 @@
+# Lab 06: Server lifecycle and process monitoring
+
+**For:** applications that need to stop or restart their managed RavenDB process and observe
+whether a process exit was expected or unexpected.
+
+## Run it
+
+```bash
+pip install ravendb-embedded
+python labs/06_embedded_lifecycle.py
+```
+
+The complete, self-checking example is
+[`06_embedded_lifecycle.py`](06_embedded_lifecycle.py). It exercises:
+
+- `get_server_process_id()`
+- `stop_server()`
+- `restart_server()`
+- `add_server_process_exited()`
+- document access after restart
+
+The core lifecycle flow is:
+
+```python
+from threading import Event
+
+from ravendb_embedded import EmbeddedServer, ServerOptions
+
+options = ServerOptions()
+
+exit_observed = Event()
+exit_events = []
+
+with EmbeddedServer() as server:
+    server.add_server_process_exited(
+        lambda event: (exit_events.append(event), exit_observed.set())
+    )
+    server.start_server(options)
+    first_process_id = server.get_server_process_id()
+
+    server.stop_server()
+    assert exit_observed.wait(10)
+    assert exit_events[-1].process_id == first_process_id
+    assert exit_events[-1].expected
+
+    server.restart_server()
+    assert server.get_server_process_id() != first_process_id
+```
+
+`event.expected` is `True` for `stop_server()`, `restart_server()`, and context-manager cleanup.
+It is `False` when RavenDB exits on its own.
+
+## Takeaway
+
+`EmbeddedServer` owns the RavenDB child process but exposes enough lifecycle information for an
+application to coordinate restarts and distinguish planned shutdowns from server failures.

labs/06_embedded_lifecycle.py

@@ -0,0 +1,53 @@
+"""Lab 06: Stop, restart, process IDs, and process-exit notifications."""
+
+import tempfile
+from pathlib import Path
+from threading import Event
+
+from ravendb_embedded import EmbeddedServer, ServerOptions
+
+
+def main() -> None:
+    with tempfile.TemporaryDirectory() as work:
+        options = ServerOptions()
+        options.data_directory = str(Path(work, "data"))
+        options.logs_path = str(Path(work, "logs"))
+
+        exit_observed = Event()
+        exit_events = []
+
+        def on_server_exit(event) -> None:
+            exit_events.append(event)
+            exit_observed.set()
+
+        with EmbeddedServer() as server:
+            server.add_server_process_exited(on_server_exit)
+            server.start_server(options)
+            first_process_id = server.get_server_process_id()
+            print(f"Started RavenDB process {first_process_id}")
+
+            server.stop_server()
+            if not exit_observed.wait(10):
+                raise RuntimeError("The server exit callback was not invoked.")
+
+            stopped = exit_events[-1]
+            assert stopped.process_id == first_process_id
+            assert stopped.expected
+            print(f"Stopped RavenDB process {stopped.process_id}")
+
+            exit_observed.clear()
+            server.restart_server()
+            second_process_id = server.get_server_process_id()
+            assert second_process_id != first_process_id
+            print(f"Restarted RavenDB as process {second_process_id}")
+
+            with server.get_document_store("LifecycleLab") as store:
+                with store.open_session() as session:
+                    session.store({"status": "running"}, "status/1")
+                    session.save_changes()
+
+        print("PASS: stop, exit notification, restart, and document access succeeded.")
+
+
+if __name__ == "__main__":
+    main()

labs/README.md

@@ -14,6 +14,7 @@ the released library and server binaries used by the scripts.
 | [03](03-on-demand-server.md) | On-demand cached self-contained download (no manual steps) | No |
 | [04](04-embedded-secured.md) | Secured embedded server (HTTPS + client certificate) | Yes |
 | [05](05-embedded-persistent.md) | Persistent data directory (data survives restarts) | Yes |
+| [06](06-embedded-lifecycle.md) | Stop, restart, PID, and process-exit monitoring | Yes |
 
 RavenDB version to .NET mapping: **7.1.x needs .NET 8, 7.2.x needs .NET 10.** The bundled server
 decides this, so it can change on a minor bump; check the lab for your version.

ravendb_embedded/__init__.py

@@ -1,9 +1,16 @@
-from ravendb_embedded.embedded_server import EmbeddedServer
-from ravendb_embedded.options import DatabaseOptions, ServerOptions, SecurityOptions
+from ravendb_embedded.embedded_server import (
+    EmbeddedServer,
+    ServerProcessExitedEvent,
+    ServerStartupError,
+    ServerStartupTimeoutError,
+)
+from ravendb_embedded.options import DatabaseOptions, LicensingOptions, ServerOptions, SecurityOptions
 from ravendb_embedded.on_demand import ensure_server
 from ravendb_embedded.provide import (
     CopyServerFromNugetProvider,
     CopyServerProvider,
     ExternalServerProvider,
+    ExtractFromPkgResourceServerProvider,
     ExtractFromZipServerProvider,
+    ProvideRavenDBServer,
 )