Add Multi-Context Support for EF Core Adapter

[thoraj]

Add Multi-Context Support for EF Core Adapter

Summary

This PR adds multi-context support to the EFCore adapter, allowing Casbin policies to be stored across multiple database contexts. This enables scenarios like separating policy types (p/p2/p3) and grouping types (g/g2/g3) into different databases, schemas, or tables.

Motivation

Users may need to:

• Store different policy types in separate databases for organizational reasons
• Use different database providers for different policy types
• Separate read-heavy grouping policies from write-heavy permission policies
• Comply with data residency or security requirements

Key Features

1. Multi-Context Provider Interface

• New ICasbinDbContextProvider<TKey> interface for context routing
• Built-in SingleContextProvider<TKey> maintains backward compatibility
• Custom providers can route policy types to any number of contexts

2. Adaptive Transaction Handling

• Shared transactions: Used when all contexts share the same database connection
• Individual transactions: Used when contexts use separate databases (e.g., SQLite files)
• Automatic detection based on connection strings

3. 100% Backward Compatible

• All existing code continues to work without changes
• Default behavior unchanged (single context)
• All 180 tests pass across .NET Core 3.1, .NET 5, 6, 7, 8, and 9

Implementation Details

Architecture

• EFCoreAdapter now accepts ICasbinDbContextProvider<TKey> in constructor
• Policy operations (Load, Save, Add, Remove, Update) route to appropriate contexts
• Transaction coordinator handles atomic operations across multiple contexts

Database Support & Limitations

Database	Multiple Contexts	Shared Transactions	Individual Transactions
SQL Server	✅ Same server	✅ Supported	✅ Supported
PostgreSQL	✅ Same server	✅ Supported	✅ Supported
MySQL	✅ Same server	✅ Supported	✅ Supported
SQLite	⚠️ Separate files only	❌ Not supported	✅ Supported

Note: SQLite cannot share transactions across separate database files. The adapter automatically detects this and uses individual transactions per context.

Usage Example

// Create separate contexts for policies and groupings
var policyContext = new CasbinDbContext<int>(policyOptions);
var groupingContext = new CasbinDbContext<int>(groupingOptions);

// Create a provider that routes 'p' types to one context, 'g' types to another
var contextProvider = new CustomContextProvider(policyContext, groupingContext);

// Create adapter with multi-context provider
var adapter = new EFCoreAdapter<int>(contextProvider);

// Build enforcer - works exactly the same as before!
var enforcer = new Enforcer("path/to/model.conf", adapter);

// All policy operations automatically route to the correct context
await enforcer.AddPolicyAsync("alice", "data1", "read");  // → policyContext
await enforcer.AddGroupingPolicyAsync("alice", "admin");   // → groupingContext

Testing

Test Coverage

• 17 new multi-context tests covering all CRUD operations
• 12 backward compatibility tests ensuring existing code works
• 180 total tests passing across 6 .NET versions (.NET Core 3.1, .NET 5, 6, 7, 8, 9)
• 100% pass rate on all frameworks (30 tests × 6 frameworks)

Test Scenarios

• Policy routing to correct contexts
• Filtered policy loading across contexts
• Batch operations (AddPolicies, RemovePolicies, UpdatePolicies)
• Transaction handling (shared and individual)
• Backward compatibility with single-context usage

Documentation

This PR includes comprehensive documentation:

1. MULTI_CONTEXT_DESIGN.md - Architecture, design decisions, and implementation details
2. MULTI_CONTEXT_USAGE_GUIDE.md - Step-by-step usage guide with complete examples
3. README.md - Updated with multi-context section and links to detailed docs

Breaking Changes

None - This is a fully backward-compatible addition. Existing code requires no changes.

Files Changed

Core Implementation

• EFCoreAdapter.cs - Updated to support context providers and adaptive transactions
• EFCoreAdapter.Internal.cs - Added transaction coordination logic
• ICasbinDbContextProvider.cs - New interface for context providers
• SingleContextProvider.cs - Default single-context implementation

Tests

• MultiContextTest.cs - 17 comprehensive multi-context tests
• BackwardCompatibilityTest.cs - 12 backward compatibility tests
• MultiContextProviderFixture.cs - Test infrastructure
• PolicyTypeContextProvider.cs - Example provider implementation
• CasbinDbContextExtension.cs - Enhanced for reliable test database initialization
• DbContextProviderFixture.cs - Added model initialization

Documentation

• MULTI_CONTEXT_DESIGN.md - Complete design documentation
• MULTI_CONTEXT_USAGE_GUIDE.md - User guide with examples
• README.md - Updated with multi-context section
• .gitignore - Added .claude/ directory

Other

• global.json - Added to ensure consistent .NET SDK version
• EFCore-Adapter.sln - Updated with new test files

Checklist

• All tests pass (180/180 across .NET Core 3.1, .NET 5, 6, 7, 8, 9)
• Backward compatibility maintained
• Documentation added (design doc, usage guide, README)
• Code follows existing patterns and conventions
• No breaking changes introduced
• Multi-framework support verified (.NET Core 3.1, .NET 5, 6, 7, 8, 9)
• Transaction handling tested for both shared and individual contexts
• SQLite limitations documented

Migration Guide

For existing users, no migration is needed. The adapter works exactly as before when using the single-context constructor:

// Existing code - continues to work unchanged
var adapter = new EFCoreAdapter<int>(dbContext);

To adopt multi-context support, use the new constructor:

// New multi-context usage
var contextProvider = new YourCustomProvider(context1, context2);
var adapter = new EFCoreAdapter<int>(contextProvider);

See MULTI_CONTEXT_USAGE_GUIDE.md for detailed migration examples.

---

Stats: +2,676 additions, -71 deletions across 16 files

[Copilot]

Pull Request Overview

Copilot reviewed 16 out of 17 changed files in this pull request and generated 10 comments.

Comments suppressed due to low confidence (2)

Casbin.Persist.Adapter.EFCore.UnitTest/Extensions/CasbinDbContextExtension.cs:1

• Line 32 references undefined variable context (should be dbContext). This will cause a compilation error.

using System;

MULTI_CONTEXT_USAGE_GUIDE.md:1

• [nitpick] The emphasis on 'YOU' and 'YOUR' (capitalized multiple times) reads as overly aggressive. While it's important to communicate responsibility clearly, consider rephrasing in a more professional tone, such as: 'For atomic operations across contexts, ensure all contexts share the same connection string. The adapter detects connection compatibility and automatically coordinates shared transactions, but providing identical connection strings is the application's responsibility.'

# Multi-Context Enforcer Setup Guide

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

[Copilot]

[nitpick] The composite key (DbContext context, string policyType) in the dictionary uses reference equality for DbContext, which is correct. However, consider potential memory growth if many policy types are used, as each (context, policyType) combination is cached separately. While this is likely acceptable for typical Casbin scenarios with limited policy types (p, p2, g, g2, etc.), consider documenting the caching strategy or adding a comment about the expected size bounds.

Suggested change

	private readonly ICasbinDbContextProvider<TKey> _contextProvider;
	private readonly ICasbinDbContextProvider<TKey> _contextProvider;
	// Caching strategy: Each (DbContext, policyType) combination is cached separately using reference equality for DbContext.
	// This is correct and efficient for typical Casbin scenarios, where the number of policy types (e.g., "p", "g", etc.) and contexts is small.
	// If used with many policy types or contexts, memory usage may grow; consider this when integrating in large/multi-tenant systems.
	// Expected size bounds: usually a handful of entries; unbounded growth is not expected in normal usage.

[hsluoyz]

@thoraj have you tested the PR?

[thoraj]

@hsluoyz
I have not integrated the PR into our staging and production environments yet. This a part of a larger refactoring, so this is not easily done (if we hope to avoid a big-bang update of our production environment)

There are of course tests in the PR.

In addition we have done integration testing related to the refactoring:

• Created a new assembly "...AccessControl.MultiContext"
• Built a new nuget package from the PR => EFCoreAdapter<>
• Integrated the multicontext EFCoreAdapter<> into the AccessControl.MultiContext
• Wrote integration tests for AccessControl.MultiContext
  • Verify proper distribution of policies to the correct CasbinDbContexts
    • Verify writing (non-filtered)
    • Verify reading/enforcing (filtered)
    • Verify transactional integrity when requirements are met (contexts share connection and transaction)

I have made changes to the PR based on the CoPilot review, so I intend to repeat:

• Build a new nuget from the updated PR
• Run integration tests again