Grain-to-grain call policy enforcement for Microsoft Orleans applications.

The library lets a silo declare the grain calls it permits, blocks missing transitions before target grain code runs, and keeps enough request context to detect unsafe runtime call cycles.

• Fluent builder API for source grain, target grain, method, client-call, and reentrancy rules.
• Attribute-based graph configuration for colocating policies with grain contracts.
• Incoming and outgoing Orleans call filters for runtime enforcement.
• Deadlock detection for active grain call chains, with opt-in self-reentrancy.
• Mermaid policy and live-call diagrams.
• Policy edge snapshots through GetPolicyEdges() for diagnostics and custom visualizers.
• .NET 10, Orleans 10, central package management, TUnit tests, and CI coverage reporting.

• .NET SDK 10
• Microsoft Orleans 10

dotnet add package ManagedCode.Orleans.Graph

Register the graph filters on the silo and configure allowed transitions.

using ManagedCode.Orleans.Graph;
using ManagedCode.Orleans.Graph.Extensions;
using ManagedCode.Orleans.Graph.Interfaces;

siloBuilder.AddOrleansGraph(graph =>
{
    graph.AllowClientCallGrain<IOrderGrain>();

    graph.AddGrainTransition<IOrderGrain, IPaymentGrain>()
        .Method(
            source => source.SubmitAsync(GraphParam.Any<Order>()),
            target => target.ChargeAsync(GraphParam.Any<Payment>()))
        .And();

    graph.AddGrain<IPaymentGrain>()
        .WithReentrancy();
});

Register the client-side outgoing filter when Orleans clients should participate in the same call-history tracking. This is only required for client-originated edges such as ORLEANS_GRAIN_CLIENT -> IOrderGrain. Grain-to-grain calls that start inside a silo, for example from another grain, timer, reminder, hosted service, or injected IGrainFactory, are tracked by the silo filters.

clientBuilder.AddOrleansGraph();

Use AllowAll() when you want to discover real traffic before enforcing a strict policy. In this mode, unconfigured transitions are allowed, but the filters still send observed calls to stateless telemetry workers. Those workers aggregate calls and periodically flush them into an in-memory telemetry grain used by the live graph.

AllowAll() is useful for documenting expected traffic without blocking unconfigured transitions. It is not a requirement for live telemetry: the live graph is recorded in both enforcing and observe modes.

using ManagedCode.Orleans.Graph.Extensions;
using ManagedCode.Orleans.Graph.Interfaces;

siloBuilder.AddOrleansGraph(
    configureFilters: filters =>
    {
        filters.LiveGraphFlushPeriod = TimeSpan.FromSeconds(1);
    },
    configureGraph: graph =>
    {
        graph.AllowAll();
    });

clientBuilder.AddOrleansGraph();

After your app receives traffic, read the observed graph from the telemetry grain.

var telemetry = grainFactory.GetGrain<IOrleansGraphTelemetryGrain>(Constants.LiveGraphTelemetryGrainKey);

var observedGraph = await telemetry.GetObservedGraphAsync();
var liveMermaidDiagram = await telemetry.GenerateLiveMermaidDiagramAsync();

The live telemetry pipeline records one observed edge from the incoming side, after Orleans has both sides of the call pair. The filters send the edge to stateless telemetry workers, workers aggregate repeated calls in memory, and a timer flushes the aggregated counts into the telemetry grain. The timer does not keep stateless workers alive.

Orleans.Graph internal telemetry calls are excluded by default so the graph shows application traffic. Set TrackOrleansGraphInternalCalls = true only when debugging the telemetry pipeline itself.

siloBuilder.AddOrleansGraph(
    configureFilters: filters =>
    {
        filters.TrackOrleansGraphInternalCalls = true;
    },
    configureGraph: graph =>
    {
        graph.AllowAll();
    });

Attributes are scanned automatically from loaded assemblies. Pass explicit assemblies when startup should avoid scanning the full AppDomain.

using ManagedCode.Orleans.Graph.Attributes;

[AllowClientCall]
[AllowGrainCall(
    typeof(IPaymentGrain),
    AllowAllMethods = false,
    SourceMethods = [nameof(IOrderGrain.SubmitAsync)],
    TargetMethods = [nameof(IPaymentGrain.ChargeAsync)])]
public interface IOrderGrain : IGrainWithStringKey
{
    Task SubmitAsync(Order order);
}

[AllowSelfReentrancy]
public interface IPaymentGrain : IGrainWithStringKey
{
    Task ChargeAsync(Payment payment);
}

Generate configured-policy and per-request Mermaid diagrams from the registered GrainTransitionManager. For the cluster-wide live graph, use the telemetry grain API because it reads the aggregated runtime graph from all filters and stateless workers.

var manager = serviceProvider.GetRequiredService<GrainTransitionManager>();

var policyDiagram = manager.GeneratePolicyMermaidDiagram();
var liveDiagram = manager.GenerateLiveMermaidDiagram(callHistory);

var telemetry = grainFactory.GetGrain<IOrleansGraphTelemetryGrain>(Constants.LiveGraphTelemetryGrainKey);
var liveGraph = await telemetry.GetObservedGraphAsync();
var liveMermaidGraph = await telemetry.GenerateLiveMermaidDiagramAsync();

liveGraph.Vertices contains grain identities. liveGraph.Edges contains observed runtime transitions between those vertices, including SourceMethod, TargetMethod, hit count, and timestamps. The Mermaid API renders the same graph for visualization.

Runtime vertices are exact graph identities. The client is represented as ORLEANS_GRAIN_CLIENT; grain vertices use the concrete Orleans grain interface or implementation identity resolved from Orleans call context. The runtime graph does not fall back to the base Grain class or wildcard methods when caller identity is required.

Inspect the configured policy without parsing Mermaid.

foreach (var edge in manager.GetPolicyEdges())
{
    Console.WriteLine($"{edge.Source} -> {edge.Target}: {edge.Transitions.Count} rule(s)");
}

Mermaid arrows:

• --> configured transition
• -.-> reentrant transition
• ==> active live-call edge

dotnet tool restore
dotnet restore Orleans.Graph.slnx
dotnet format Orleans.Graph.slnx
dotnet build Orleans.Graph.slnx --configuration Release --no-restore -p:RunAnalyzers=true
dotnet test --solution Orleans.Graph.slnx --configuration Release --no-build --verbosity normal

Coverage uses the local tool manifest:

dotnet tool run coverlet ManagedCode.Orleans.Graph.Tests/bin/Release/net10.0/ManagedCode.Orleans.Graph.Tests.dll \
  --target "dotnet" \
  --targetargs "test --project ManagedCode.Orleans.Graph.Tests/ManagedCode.Orleans.Graph.Tests.csproj --configuration Release --no-build --no-restore" \
  --format cobertura \
  --output artifacts/coverage/coverage.cobertura.xml \
  --exclude "[ManagedCode.Orleans.Graph.Tests]*" \
  --threshold 80 \
  --threshold-type line \
  --threshold-stat total

MIT - see LICENSE.