Devolutions.Now.Policy.Api 2026.9.3

Devolutions NOW package broker API for .NET

Devolutions.Now.Policy.Api contains the .NET DTOs for the Devolutions NOW package broker API. It is the C# mirror of the Rust now-policy-api model crate and is validated against the OpenAPI schema generated from Rust.

Purpose

This package contains request, response, status, health, capabilities, active-policy inspection and management, and error DTOs for package broker clients and implementations. It does not perform HTTP transport, named-pipe I/O, policy validation/evaluation, persistence, or package-manager execution.

Top-level request DTOs carry RequestKind and RequestVersion; top-level response DTOs carry ResponseKind and ResponseVersion. Kind properties are fixed discriminators that serialize automatically and reject mismatched values on deserialization. This is required for further protocol evolution and allows the client to switch transport from HTTP to other mechanisms without changing the wire schema.

The DTOs are used to:

• serialize package broker requests from .NET clients;
• deserialize broker health, capability, active-policy, evaluation, execution, status, and error responses;
• share the same JSON wire shape as the Rust source-of-truth model;
• provide compatibility conversions between package broker API enums and the Devolutions.Now.Policy.Model policy enums.

Architecture

• RequestModels.cs defines PackageRequest and request context/options.
• ResponseModels.cs defines active-policy, evaluation, and execution responses plus shared response context, summaries, decisions, policy info, diagnostics, and operation submission. PolicyResponse embeds the canonical Devolutions.Now.Policy.Model.PolicyDocument.
• PolicyManagementModels.cs defines atomic management snapshots, raw JSON draft requests, versioned validation findings/receipts, optimistic replacement intents, and management responses.
• StatusModels.cs defines status query request/response DTOs.
• MetaModels.cs defines health, capabilities, manager capability, and error DTOs.
• Enums.cs defines package broker API enums and JSON string enum converters.
• BrokerSerializer.cs defines source-generated serializer options for the broker wire format. Public BrokerSerializer.Options and BrokerSerializer.PrettyOptions support every broker DTO, including the embedded policy model, without reflection and reject JSON null for non-nullable contract members.
• PolicyCompatibility.cs maps compatible API enums to and from Devolutions.Now.Policy.Model enums.

Opaque policy store tokens and validation receipts are restricted to safe printable ASCII (A-Z, a-z, 0-9, ., _, ~, :, -) beginning with an ASCII alphanumeric character, so Rust and .NET enforce identical bounds.

BrokerApi.MaxPolicyManagementBodyBytes exposes the fixed 16 MiB limit for the complete serialized HTTP body of policy validation and replacement requests. It is separate from the package-operation limit advertised by broker capabilities.

Because policy documents are JSON-only, configured .yaml, .yml, extensionless, and other non-JSON paths use PolicyReadOnlyReason.UnsupportedFormat in management snapshots and ErrorCode.UnsupportedPolicyFormat for structured HTTP 422 errors.

OpenAPI relationship

The OpenAPI document is generated by the Rust server template and published under:

policies\rust\now-policy-api\openapi\now-policy-api.yaml

Regenerate it with:

cargo run -p now-policy-server-template --bin generate-now-policy-api-openapi --locked

After schema changes, run the .NET client tests to verify these DTOs still match the Rust contract.

Validation

Useful targeted checks:

dotnet test policies\dotnet\Devolutions.Now.Policy.Client.Tests\Devolutions.Now.Policy.Client.Tests.csproj
dotnet format policies\dotnet\Devolutions.Now.Policy.slnx --verify-no-changes

Run the Rust now-policy-api and now-policy-server-template tests when changing shared API semantics.