Bitwarden Server

Concept

ExtendedCache is a wrapper around FusionCache designed to provide named, isolated caches with sensible defaults. It simplifies the registration of subsystem-specific caches that can include optional distributed caching (L2) and backplane support for multi-instance synchronization.

Mental Model: L1 vs L2

• L1 (In-process memory cache): The first layer of caching. It is fast but bounded by the application heap.
• L2 (Distributed cache): The second layer, implemented via IDistributedCache (e.g., Redis, Cosmos DB, SQL Server, or EF).

Data Flow: FusionCache reads from L1 first. If a miss occurs, it falls back to L2. When data is retrieved or set, it writes through to both layers.

Key Features

• Stampede Protection: Prevents multiple concurrent requests for the same key from hitting the backend simultaneously; only one request executes the factory, while others wait for the result.
• Fail-safe Mode: Allows the system to serve stale data from the cache if the backend (factory) fails.
• Eager Refresh: Automatically refreshes cache entries in the background before they expire (based on EagerRefreshThreshold) to prevent latency spikes at TTL boundaries.
• Backplane Support: Uses Redis pub/sub to synchronize cache invalidations across multiple application instances (only available with Redis L2).

Bitwarden uses a two-tier messaging architecture to decouple event generation from event consumption. This allows for high scalability (fan-out) and robust error handling through retries.

1. Event Tier (First Tier)

Events are broadcast from the IEventWriteService (specifically the EventIntegrationEventWriteService) to an AMQP exchange or topic.

• EventRepositoryHandler: Responsible for long-term storage of all events into the database or Azure Tables.
• EventIntegrationHandler: A generic handler that checks for organization-specific configurations. It parses events into template strings and produces an IntegrationMessage<T>, which is then published to the second tier.

2. Integration Tier (Second Tier)

This tier handles the actual delivery to external services (e.g., Slack, Webhooks).

• Integration Handlers: Specific logic for a single integration (e.g., SlackIntegrationHandler). They receive an IntegrationMessage<T> and return an IntegrationHandlerResult.
• Integration Listeners: Manage the messaging platform (RabbitMQ/ASB) and execute the handler. They handle the outcome of the handler: success acknowledges the message, while failure triggers the retry logic.

When an organization policy is created or updated via ISavePolicyCommand, the system executes an ordered sequence of steps. You can hook into these steps by implementing specific IPolicyUpdateEvent interfaces. If no handler is implemented, the policy is simply upserted to the database with an audit log event.

The workflow sequence is:

1. Validate organization can use policies
2. Validate policy dependencies (via IEnforceDependentPoliciesEvent)
3. Run policy-specific validation (via IPolicyValidationEvent)
4. Execute pre-save side effects (via IOnPolicyPreUpdateEvent)
5. Upsert policy + log event
6. Execute post-save side effects (via IOnPolicyPostUpdateEvent)

Important Limitation: The workflow is not atomic. If an exception occurs at any step, changes made by prior steps (like pre-save side effects) are not automatically rolled back.

SaveAsync()
  ├─ 1. Validate organization can use policies
  ├─ 2. Validate policy dependencies     ← IEnforceDependentPoliciesEvent
  ├─ 3. Run policy-specific validation   ← IPolicyValidationEvent
  ├─ 4. Execute pre-save side effects    ← IOnPolicyPreUpdateEvent
  ├─ 5. Upsert policy + log event
  └─ 6. Execute post-save side effects  ← IOnPolicyPostUpdateEvent

Organization abilities (which control plan-based access) should work alongside feature flags (which control rollout). For a new feature, you should typically check both to ensure the feature is both enabled for the system and permitted by the user's plan.

// 1. Check feature flag first (controls rollout)
if (!_featureService.IsEnabled(FeatureFlagKeys.MyFeature))
{
    throw new BadRequestException("This feature is not available.");
}

// 2. Then check organization ability (controls plan-based access)
var orgAbility = await _applicationCacheService.GetOrganizationAbilityAsync(organizationId);
if (!orgAbility.UseMyFeature)
{
    throw new BadRequestException("Your organization's plan does not support this feature.");
}

// Check feature flag first (controls rollout)
if (!_featureService.IsEnabled(FeatureFlagKeys.MyFeature))
{
    throw new BadRequestException("This feature is not available.");
}

// Then check organization ability (controls plan-based access)
if (!orgAbility.UseMyFeature)
{
    throw new BadRequestException("Your organization's plan does not support this feature.");
}