RavenDB-27140 Sync Python Embedded with C#

[poissoncorp]

Breaking changes

None.

New public APIs

• Lifecycle: EmbeddedServer.stop_server(), restart_server(), and get_server_process_id().
• Process monitoring: add_server_process_exited(callback), remove_server_process_exited(callback), and ServerProcessExitedEvent(process_id, exit_code, expected).
• Startup failures: ServerStartupError and ServerStartupTimeoutError.
• Shutdown configuration: ServerOptions.process_kill_timeout.
• Licensing: ServerOptions.licensing and LicensingOptions fields for inline/path licenses, automatic-update controls, support checks, and fail-fast validation.
• Certificate loading: ServerOptions.secured_with_certificate_exec().
• Custom server sources: configurable ExtractFromPkgResourceServerProvider(package, resource_name); ProvideRavenDBServer and this provider are now exported from ravendb_embedded.

Implements the complete Embedded synchronization scope and documents the supported customer workflows.

Major

Process lifecycle and correctness

• Send RavenDB's graceful shutdown no-confirmation command through redirected stdin
• Bound graceful shutdown, termination, and force-kill waits with configurable timeouts
• Add stop_server() without disposing the EmbeddedServer or its stores
• Add restart_server() using the existing server options
• Expose the RavenDB process ID
• Expose expected and unexpected server-process exit callbacks
• Use the RavenDB-compatible SHA-1 certificate thumbprint for well-known admin access
• Close open document stores safely without mutating the collection during iteration
• Make document-store removal safe when a store has already been removed
• Handle existing databases through the typed ConcurrencyException
• Keep failed starts retryable on the same EmbeddedServer instance

Concurrency and isolation

• Make server startup thread-safe
• Make lazy initialization thread-safe
• Make document-store creation, lookup, removal, and shutdown thread-safe
• Support multiple independent embedded servers in one Python process

Runtime and platform support

• Detect and run Windows Raven.Server.exe self-contained builds
• Detect and run POSIX Raven.Server self-contained builds
• Add opt-in runtime-configuration detection that selects a compatible installed .NET patch
• Preserve the default dotnet host runtime selection and explicit framework-version overrides
• Report actionable errors when the required .NET host or runtime is unavailable
• Preserve the original runtime-enumeration failure
• Format available .NET runtimes clearly

Licensing and EULA

• Preserve the existing EULA acceptance default
• Add inline license configuration
• Add license-path configuration
• Add automatic license-update control
• Add API-triggered license-update control
• Add license-support-check control
• Add fail-fast handling for an invalid or missing license

Secured server support

• Preserve secured(server_pfx) for HTTPS server configuration without a managed client certificate
• Configure returned DocumentStore instances when an optional client PEM is supplied
• Keep the server PFX separate instead of assuming it is a usable client identity
• Expose external certificate-loader configuration through secured_with_certificate_exec()
• Use the current Security.Certificate.Load.Exec server arguments
• Validate that a supplied client PEM contains an X.509 certificate and unencrypted private key
• Validate that the client certificate and private key match
• Validate Client Authentication EKU when Extended Key Usage is present
• Validate explicit CA certificate bundles before starting RavenDB
• Keep secured examples compatible with strict TLS certificate-chain validation
• Continue using the operating-system trust store when no custom CA bundle is supplied
• Propagate a supplied client certificate and CA trust path to every returned DocumentStore

Data and log locations

• Preserve the existing package-directory data location by default
• Derive logs from an explicitly changed data_directory until logs_path is set
• Keep explicit data and log locations configurable per server instance

Medium

Startup handling and diagnostics

• Fail immediately when the server process exits or closes its output streams during startup
• Drain stdout and stderr concurrently before and after the server becomes available
• Include captured stdout, stderr, command, and configuration guidance in startup failures
• Distinguish startup timeouts with ServerStartupTimeoutError
• Integrate Embedded logging with the standard Python logging hierarchy

Server sources and archive safety

• Retain bundled, local-directory, ZIP, package-resource, and self-contained server providers
• Run external server directories in place without copying or deleting user-owned files
• Make package-resource server providers configurable and publicly reusable
• Reject ZIP path traversal when extracting external server archives
• Cover automatic platform mapping, cache reuse, interrupted downloads, and concurrent cache creation

Customer documentation and examples

• Rewrite the README around bundled, external self-contained, and on-demand workflows
• Document system .NET requirements and no-.NET alternatives
• Document licensing and EULA configuration
• Document server-only HTTPS and managed client-certificate workflows
• Document lifecycle controls and multi-instance usage
• Document providers and persistent-data behavior
• Provide a runnable bundled-server lab
• Provide a runnable external self-contained-server lab
• Provide a runnable on-demand platform-detection and cache lab
• Provide a runnable secured mTLS lab
• Provide a runnable persistent-data lab
• Provide a runnable lifecycle and process-monitoring lab

Test coverage

• Add integration coverage for real RavenDB startup and persistence
• Add integration coverage for restart and multi-server isolation
• Add integration coverage for server-only HTTPS startup
• Add integration coverage for secured and separate-certificate mTLS
• Add real child-process coverage for startup failures and stderr pressure
• Add real child-process coverage for graceful shutdown and process exits
• Add real child-process coverage for licensing arguments and startup retry
• Add archive safety, interrupted-download, and concurrent-cache coverage
• black --check . passes with Black 26.5.1
• Lab 06 passes against a real RavenDB process
• Local validation: all 52 integration and end-to-end tests pass on Windows

Minor

API and behavior polish

• Open the canonical Studio URL with analytics disabled
• Retain context-manager ownership
• Document the synchronous execution model
• Deprecate the misleading ServerOptions.INSTANCE() constructor alias
• Pass process arguments as an argv list without manual command-line escaping
• Use the current Python process ID directly for RavenDB parent-process monitoring
• Link to the current RavenDB Commercial License EULA