Skip to content

Add query health endpoint with Route attribute support#2281

Merged
einari merged 17 commits into
mainfrom
copilot/add-query-health-endpoint
Jun 10, 2026
Merged

Add query health endpoint with Route attribute support#2281
einari merged 17 commits into
mainfrom
copilot/add-query-health-endpoint

Conversation

Copilot AI commented Jun 8, 2026

Copy link
Copy Markdown
Contributor

Summary

Implements observable query health monitoring at /.cratis/queries/health with a new Route attribute for custom endpoint paths.

Added

  • [Route] attribute for specifying custom routes on query classes or methods (method takes precedence)
  • IQueryHealthTracker service tracking all active observable query subscriptions
  • QueryHealth read model exposing connection health via observable query at /.cratis/queries/health
  • Connection metadata capture: established time, client info (IP, User-Agent, User ID), protocol type, ping/pong timestamps, last data served timestamp
  • Connection ID generation: ws-{counter} for WebSocket, GUID for SSE

Fixed

  • Frontend validation code now uses === instead of just double == for truthy checks.

Changed

  • ObservableQueryDemultiplexer now tracks subscription lifecycle (register, unregister, ping, pong, data served)
  • IQueryPerformer includes CustomRoute property
  • ModelBoundQueryPerformer and ControllerQueryPerformer detect Route attribute via reflection
  • QueryEndpointMapper prefers custom routes over conventional route generation
  • Proxy generator QueryExtensions detects Route attribute and uses custom route in generated code

Usage

// Define a query with custom route
[Route("/.cratis/special-endpoint")]
[ReadModel]
public sealed record MyQuery
{
    public static IObservable<MyQuery> Observe() => ...;
}

// Access query health
[Route("/.cratis/queries/health")]
[ReadModel]
public sealed record QueryHealth
{
    public IEnumerable<QueryConnectionHealth> Connections { get; init; } = [];
    
    public static ISubject<QueryHealth> ObserveHealth(IQueryHealthTracker healthTracker) => ...;
}

Health data includes per-connection subscriptions with query identifiers, read model types, timestamps, and client details.

Copilot AI linked an issue Jun 8, 2026 that may be closed by this pull request
Comment thread Source/DotNET/Arc.Core/Queries/QueryHealth.cs Fixed
- Created Route attribute for custom query routes
- Implemented QueryHealthTracker service for tracking observable query subscriptions
- Created QueryHealth read model with custom route /.cratis/queries/health
- Integrated health tracking into ObservableQueryDemultiplexer
- Updated proxy generator and runtime mapper to support Route attribute
- Added CustomRoute property to IQueryPerformer, ModelBoundQueryPerformer, and ControllerQueryPerformer
Comment thread Source/DotNET/Arc.Core/Queries/QueryHealth.cs Fixed
Copilot AI changed the title [WIP] Add query health endpoint to retrieve observable query status Add query health endpoint with Route attribute support Jun 8, 2026
Copilot AI requested a review from einari June 8, 2026 11:48
Copilot finished work on behalf of einari June 8, 2026 11:48
@einari einari added the minor label Jun 9, 2026
@github-actions

github-actions Bot commented Jun 9, 2026

Copy link
Copy Markdown

NuGet packages for this PR, e.g. Cratis.Arc:
https://github.com/cratis/arc/packages/1655206?version=20.40.2

einari added 11 commits June 10, 2026 15:07
JsonSerializer.deserializeFromInstance and deserializeArrayFromInstance
break when called with String, Number, or Boolean as the instanceType —
they return empty values instead of passing the data through unchanged.

Skip deserialization entirely for primitive types and pass the raw data
(or Array.from for enumerables and changeSet arrays) directly through.
…ixtures

QueryPerformerProvider uses QueryMetadataRegistry when populated, falling
back to ITypes.All only when the registry is empty. ITypes.All is populated
by source-generated providers — test assemblies don't run source generators,
so their [ReadModel] types are invisible and no HTTP endpoints are registered,
causing 404 failures in the integration specs.

Scanning the test assembly for [ReadModel] types and registering each query
method with QueryMetadataRegistry before the host starts ensures performers
are created and endpoints are mapped correctly.
Reflects the [Route("/.cratis/queries/health")] attribute added to the
ObserveHealth query method, replacing the conventional route.
Introduce QuerySubscriber and QuerySubscriptionAggregate records that group all
active subscriptions by query name — matching the queryName property on generated
TypeScript proxies exactly ({TypeFullName}.{MethodName} format).

The new QuerySubscriptions property on QueryHealth provides a query-centric view
across all transport modes (multiplexed WebSocket and direct SSE), enabling tooling
to correlate frontend cache diagnostics with backend subscription state using the
same query identifier on both sides.

Also fix ReadModelType in CreateSubscriptionMetadata: was incorrectly set to the
full QueryIdentifier; now strips the trailing .{MethodName} segment so the type
name refers to the read model type only.
Comment thread Source/DotNET/Arc.Core/Queries/QueryHealth.cs
Document the /.cratis/queries/health observable endpoint: response shape,
both connection-centric and query-centric views, how transport modes affect
the output, and the cross-stack correlation approach using the shared
{TypeFullName}.{MethodName} query identifier format.

Extend the frontend observable query diagnostics page with a step-by-step
investigation flow that shows how to match a frontend cache entry to its
backend subscribers using the same queryName identifier on both sides.
@einari einari marked this pull request as ready for review June 10, 2026 19:30
…ariable'

Co-authored-by: Copilot Autofix powered by AI <223894421+github-code-quality[bot]@users.noreply.github.com>
@einari einari merged commit bc2df34 into main Jun 10, 2026
9 of 10 checks passed
@einari einari deleted the copilot/add-query-health-endpoint branch June 10, 2026 19:32
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

Projects

None yet

Development

Successfully merging this pull request may close these issues.

Add query health endpoint

2 participants