RxDBDotNet 1.2.1

RxDBDotNet

RxDBDotNet is a powerful .NET library that implements the RxDB replication protocol, enabling real-time data synchronization between RxDB clients and .NET servers using GraphQL and Hot Chocolate. It extends the standard RxDB replication protocol with .NET-specific enhancements.

Table of Contents

• RxDBDotNet
  • Table of Contents
  • Key Features
  • Getting Started
    • Installation
    • Basic Usage
  • Advanced Features
    • Policy-Based Security
    • Subscription Topics
    • Custom Error Types
    • Authentication Schemes for Subscriptions
  • Example Application
    • Prerequisites for Running the Example Application
    • Running the Full Stack
  • Contributing
  • License
  • Code of Conduct
  • Security
  • Acknowledgments

Key Features

• 🔄 Full RxDB Protocol Support
• 🌶️ Hot Chocolate GraphQL Integration
• 🌐 Real-Time & Offline-First Capabilities
• ⚡ Quick Setup with Minimal Configuration
• 🧩 Extensible Design for Custom Types
• ⚠️ Structured Error Handling
• 🎯 Subscription Topic Filtering
• 🔒 ASP.NET Core Authorization Integration
• 🔍 GraphQL Filtering for Optimized Data Transfer
• 🚀 Actively Developed & Community-Driven

Getting Started

Installation

Install the RxDBDotNet package via NuGet:

dotnet add package RxDBDotNet

Basic Usage

1. Implement IReplicatedDocument for your document type:

   public class Workspace : IReplicatedDocument
   {
       public required Guid Id { get; init; }
       public required string Name { get; set; }
       public required DateTimeOffset UpdatedAt { get; set; }
       public required bool IsDeleted { get; set; }
       public List<string>? Topics { get; set; }
   }
   

2. Implement the document service:

   public class WorkspaceService : IReplicatedDocumentService<Workspace>
   {
       // Implement the required methods
       // ...
   }
   

3. Configure services in Program.cs:

   // Add your document service to the DI container
   builder.Services
       .AddSingleton<IReplicatedDocumentService<Workspace>, WorkspaceService>();
   
   // Configure the Hot Chocolate GraphQL server
   builder.Services
       .AddGraphQLServer()
        // Mutation conventions must be enabled for replication to work
       .AddMutationConventions()
       // Enable RxDBDotNet replication services
       .AddReplication()
       // Register the document to be replicated
       .AddReplicatedDocument<Workspace>()
       .AddInMemorySubscriptions();
   
   var app = builder.Build();
   
   app.UseWebSockets();
   app.MapGraphQL();
   
   app.Run();
   

Advanced Features

Policy-Based Security

RxDBDotNet supports policy-based security using the Microsoft.AspNetCore.Authorization infrastructure.

Configuration:

1. Define authorization policies:

   builder.Services.AddAuthorization(options =>
   {
       options.AddPolicy("IsWorkspaceAdmin", policy =>
           policy.RequireClaim("WorkspaceRole", "Admin"));
   
       options.AddPolicy("CanReadWorkspace", policy =>
           policy.RequireClaim("WorkspaceRole", "Admin", "Reader"));
   });
   

2. Configure security options for documents:

   builder.Services
       .AddGraphQLServer()
       .AddReplicatedDocument<Workspace>(options =>
       {
           options.Security = new SecurityOptions()
               .RequirePolicyToRead("CanReadWorkspace")
               .RequirePolicyToWrite("IsWorkspaceAdmin");
       });
   

Subscription Topics

RxDBDotNet supports subscription topics for fine-grained control over real-time updates.

Usage:

1. Specify topics when creating or updating a document:

   var liveDoc = new LiveDoc
   {
       Id = Guid.NewGuid(),
       Content = "New document content",
       UpdatedAt = DateTimeOffset.UtcNow,
       IsDeleted = false,
       WorkspaceId = workspaceId,
       Topics = new List<string> { $"workspace-{workspaceId}" }
   };
   
   await documentService.CreateAsync(liveDoc, CancellationToken.None);
   

2. Subscribe to specific topics:

   subscription StreamLiveDocs {
     streamLiveDoc(topics: ["workspace-123e4567-e89b-12d3-a456-426614174000"]) {
       documents {
         id
         content
         updatedAt
         isDeleted
         workspaceId
       }
       checkpoint {
         updatedAt
         lastDocumentId
       }
     }
   }
   

Custom Error Types

Configure custom error types to provide more detailed error information to clients:

builder.Services
    .AddGraphQLServer()
    .AddReplicatedDocument<User>(options =>
    {
        options.Errors = new List<Type>
        {
            typeof(UserNameTakenException),
            typeof(InvalidUserNameException)
        };
    });

Authentication Schemes for Subscriptions

RxDBDotNet supports configuring multiple authentication schemes for GraphQL subscriptions over WebSocket connections. This feature provides flexibility in token validation and supports scenarios where you need to handle tokens from different authentication sources.

Basic Configuration

By default, RxDBDotNet uses the standard JWT Bearer authentication scheme ("Bearer"). You can use this with minimal configuration:

builder.Services
    .AddAuthentication(JwtBearerDefaults.AuthenticationScheme)
    .AddJwtBearer(options =>
    {
        options.TokenValidationParameters = // ... your token validation parameters
    });

builder.Services
    .AddGraphQLServer()
    .AddMutationConventions()
    .AddReplication() // Uses default Bearer scheme

Custom Authentication Schemes

You can configure multiple authentication schemes to validate subscription tokens:

// Configure multiple JWT Bearer schemes
builder.Services
    .AddAuthentication()
    .AddJwtBearer("Bearer", options => 
    {
        options.Audience = "DefaultAudience";
        options.TokenValidationParameters = // ... default scheme parameters
    })
    .AddJwtBearer("CustomScheme", options =>
    {
        options.Audience = "CustomAudience";
        options.TokenValidationParameters = // ... custom scheme parameters
    });

// Configure RxDBDotNet to use both schemes
builder.Services
    .AddGraphQLServer()
    .AddMutationConventions()
    .AddReplication(options => 
    {
        options.Security
            .TryAddSubscriptionAuthenticationScheme("CustomScheme");
        // The default "Bearer" scheme is already included
    });

When a client attempts to establish a WebSocket connection, RxDBDotNet will:

1. Try to validate the token using each configured scheme in order
2. Accept the connection with the first scheme that successfully validates the token
3. Reject the connection if no scheme can validate the token

OIDC Support

The subscription authentication system fully supports OpenID Connect configuration, including dynamic key retrieval and rotation:

builder.Services
    .AddAuthentication()
    .AddJwtBearer("OidcScheme", options =>
    {
        options.Authority = "https://your-identity-provider.com";
        options.Audience = "your-api";
        options.RequireHttpsMetadata = true;
    });

builder.Services
    .AddGraphQLServer()
    .AddMutationConventions()
    .AddReplication(options => 
    {
        options.Security
            .TryAddSubscriptionAuthenticationScheme("OidcScheme");
    });

The system will automatically:

• Retrieve OIDC configuration from the authority
• Use the latest signing keys
• Handle key rotation without requiring application restarts

Client Usage

Clients should include the JWT token in the WebSocket connection initialization:

const client = createClient({
  url: 'ws://your-api/graphql',
  connectionParams: {
    headers: {
      Authorization: `Bearer ${jwtToken}`
    }
  }
});

Error Handling

The subscription authentication system provides detailed error information:

• If authentication fails, the WebSocket connection is closed with code 4403 (Forbidden)
• Error details are included in the close message
• Connection attempts are logged for debugging purposes

Example Application

The example directory contains a full-stack application demonstrating RxDBDotNet usage in a real-world scenario:

• example/livedocs-client: A Next.js frontend app using RxDB with RxDBDotNet
• example/LiveDocs.GraphQLApi: A .NET backend API using RxDBDotNet
• example/LiveDocs.AppHost: A .NET Aspire AppHost for running the full stack

For more details on running and debugging the example client app, see the livedocs-client README.

Prerequisites for Running the Example Application

To run the example application, you'll need the following installed:

• Node.js (v14 or later)
• npm (v6 or later)
• .NET 8.0 or later
• .NET Aspire workload
• Docker Desktop (latest stable version)

Note:

• Docker Desktop is required to run the Redis and SQL Server instances used by the example application.
• For detailed instructions on installing .NET Aspire and its dependencies, please refer to the official .NET Aspire setup documentation.

Running the Full Stack

1. Ensure you have .NET Aspire installed and Docker Desktop is running on your machine.

2. Navigate to the example/LiveDocs.AppHost directory.

3. Run the following command:

   dotnet run --launch-profile full-stack
   

4. Open the .NET Aspire dashboard (typically at http://localhost:15041).

5. Access the frontend at http://localhost:3001 and the GraphQL API at http://localhost:5414/graphql.

RxDB Replication Protocol Details

RxDBDotNet implements the RxDB replication protocol with additional error handling conventions:

1. Document-Level Replication: Supports the git-like replication model for local changes and server state merging.

2. Transfer-Level Protocol:

   • Pull Handler: Implemented via the Pull query with checkpoint-based iteration.
   • Push Handler: Implemented via the Push mutation for client-side writes and conflict detection.
   • Event Stream: Implemented via the Stream subscription for real-time updates.

3. Checkpoint Iteration: Supports efficient data synchronization using checkpoints.

4. Data Layout:

   • Ensures documents are sortable by their last write time (UpdatedAt).
   • Uses soft deletes (IsDeleted flag) instead of physical deletion.

5. Conflict Handling: Implements server-side conflict detection during push operations.

6. Offline-First Support: Allows clients to continue operations offline and sync when back online.

7. Advanced Error Handling: Utilizes Hot Chocolate GraphQL mutation conventions for detailed error information.

Custom Implementations for RxDB Clients

RxDBDotNet requires custom implementations for RxDB clients due to its advanced features and integration with Hot Chocolate GraphQL. These customizations include:

1. Custom Query Builders:

   • Pull Query Builder: Supports Hot Chocolate's filtering capabilities for efficient and selective data synchronization.
   • Push Query Builder: Adapts to Hot Chocolate's mutation conventions for sending local changes to the server.

2. Subscription Topics and Pull Stream Builder: Enables fine-grained control over real-time updates, allowing clients to subscribe to specific subsets of data.

These customizations enable RxDB clients to effectively communicate with RxDBDotNet backends, leveraging advanced features like filtered synchronization and topic-based real-time updates.

For detailed examples and explanations of these custom implementations, including code snippets and usage guidelines, please refer to the Example Client App README.

Security Considerations

Server-Side Timestamp Overwriting

RxDBDotNet implements a crucial security measure to prevent potential issues with untrusted client-side clocks. The server always overwrites the UpdatedAt timestamp with its own server-side timestamp for document creation or update requests. This ensures:

1. The integrity of the document's timeline is maintained.
2. Potential time-based attacks or inconsistencies due to client clock discrepancies are mitigated.
3. The server maintains authoritative control over the timestamp for all document changes.

This security measure is implemented in the MutationResolver<TDocument> class. Developers should be aware that any client-provided UpdatedAt value will be ignored and replaced with the server's timestamp.

Important: While the IReplicatedDocument interface defines UpdatedAt with both a getter and a setter, developers should not manually set this property in their application code. Always rely on the server to set the correct UpdatedAt value during replication operations. The setter is present solely to allow the server to overwrite the timestamp as a security measure.

Contributing

We welcome contributions to RxDBDotNet! Here's how you can contribute:

1. Fork the repository.
2. Create a new branch (git checkout -b feature/amazing-feature).
3. Make your changes.
4. Commit your changes using Conventional Commits syntax.
5. Push to the branch (git push origin feature/amazing-feature).
6. Open a Pull Request with a title that follows the Conventional Commits syntax.

Please ensure your code meets our coding standards and includes appropriate tests and documentation.

We use squash merges for all pull requests. The pull request title will be used as the commit message in the main branch, so it must follow the Conventional Commits syntax.

Please refer to our Contributing Guide for more detailed guidelines.

License

This project is licensed under the MIT License - see the LICENSE file for details.

Code of Conduct

This project adheres to the Contributor Covenant Code of Conduct. By participating, you are expected to uphold this code.

Security

Please see our Security Policy for information on reporting security vulnerabilities and which versions are supported.

Acknowledgments

• Thanks to the RxDB project for inspiring this .NET implementation.
• Thanks to the Hot Chocolate team for their excellent GraphQL server implementation.

Ready to dive in? Get started or contribute to shape the future of .NET-based data replication!