Vania Framework

The Counter Example demonstrates how to separate business logic from HTTP concerns using the Vania framework. The core logic is decoupled from the routing and controller layers.

lib/
  app/counter.dart                          # the counter logic (no HTTP)
  app/http/controllers/counter_controller.dart
  route/api_route.dart
  app/providers/route_service_provider.dart
  config/app.dart
bin/server.dart
test/counter_test.dart                       # unit tests for the counter

The vania_websocket package includes the following capabilities:

• Rooms: Lightweight groupings for broadcasting; supports joining, leaving, and listing members.
• Channels: High-level groupings for organizing subscriptions.
• Presence: Use WebSocketPresence() to track online users, receive change events, and send per-user messaging.
• Connection Introspection: Monitor and manage connections via connectionCount, connectionIds, hasConnection, getConnectionInfo, close, and closeAll.
• Middleware: Implement authentication or rate-limiting for socket connections before they are accepted.

The vania_elasticsearch package provides several tools for search integration:

• Searchable mixin: Provides .searchable(), .unsearchable(), and .search() methods.
• Query builder: Supports multi-match, match-all, and custom queries with pagination using from and size parameters.
• Direct client: Provides low-level access via Elasticsearch.search(...), Elasticsearch.index(...), and bulk helpers.
• Bulk indexing: Optimized helpers for backfilling large datasets.

By default, table names are derived from the class name using snake_case and pluralization (e.g., BlogPost becomes blog_posts).

Custom Table Names

You can set a specific table name in the constructor using super.table() or use a tablePrefix.

Custom Primary Keys

To change the primary key from the default id (auto-incrementing integer), override primaryKey, keyType, and incrementing.

class User extends Model {
  User() {
    super.table('app_users');
  }

  @override
  String get tablePrefix => 'app_'; // Results in table: app_users

  @override
  String get primaryKey => 'user_id';

  @override
  String get keyType => 'string'; // Use for UUIDs

  @override
  bool get incrementing => false;
}

When using Redis within the framework, follow these patterns:

• Use Atomic Operations: Leverage Redis atomic commands like INCR to handle concurrency. This avoids race conditions inherent in read-modify-write cycles.
• Namespace Your Keys: Always use a prefix for your keys (e.g., views:home instead of just home) to prevent data collisions if multiple applications share the same Redis instance.
• Test with Fakes: Because your logic depends on an interface rather than the Redis client directly, you can test your application logic using in-memory fakes without requiring a running Redis server.

Controllers are classes used to organize request handling logic. Each public method in a controller class corresponds to a specific route and must return a Response object. To use a controller, you should instantiate it as a top-level singleton in its file and then reference its methods in your router definitions.

// 1. Define the controller
class PostController extends Controller {
  Future<Response> index() async {
    return Response.json({'data': 'example'});
  }
}

// 2. Instantiate as a singleton
final PostController postController = PostController();

// 3. Reference in routes
Router.get('/posts', postController.index);

A core architectural pattern in Vania is the strict separation of logic from transport.

In this pattern, the core business logic (e.g., a Counter class, a ChatHub, or a Wallet aggregate) remains independent of how it is accessed. The HTTP or WebSocket layer acts only as a thin adapter on top of this logic.

Benefits of this pattern:

• Testability: You can run tests on your business logic without needing to spin up a server, a socket, or a database.
• Flexibility: You can easily swap or add new transport layers (e.g., moving from REST to gRPC) without changing the core application logic.

You can support multiple authentication contexts (e.g., 'users' and 'admins') by configuring additional guards.

Use Auth().configureGuard(name, ...) to set up a new context with its own tokenStore and userProvider. To interact with a specific guard, use Auth().guard(name) instead of the default Auth() methods.

// Configure multiple guards
Auth().configureGuard('admin', 
  tokenStore: ModelPersonalAccessTokenStore(model: PersonalAccessToken()),
  userProvider: ModelUserProvider(model: Admin()),
);

// Login as admin
Auth().guard('admin').login(adminUser);
var token = await Auth().guard('admin').createToken();

// Check admin auth
Auth().guard('admin').check(token);