Packages
Vyuh Server is split across one core package, shared wire-contract packages, and a catalog of shipped plugins. Pull only what you need.
Core
| Package | Purpose |
|---|---|
vyuh_server | The runtime: VyuhServer.bootstrap, runtime.start, Plugin subtypes, FeatureDescriptor, contribution slots, DescriptorHandler, the vyuh global accessor, and the Relic-based transport |
The core package depends on relic for HTTP and vyuh_errors for the structured-error wire format. No database driver, no auth library, no observability library. Everything else is opt-in.
Wire Contracts
| Package | Purpose |
|---|---|
vyuh_entity_crud_types | Shared response envelopes and DTOs used by vyuh_server_plugin_entity_crud and client-side entity readers |
Plugins
Each plugin either claims a singleton role (DbPlugin, StoragePlugin, TelemetryPlugin, QueryPlugin), contributes into a chain (AuthPlugin), or claims a descriptor type via DescriptorHandler<D>.
Database (relational, OLTP)
Backs vyuh.db — at most one per server.
| Package | Singleton role | Notes |
|---|---|---|
vyuh_server_plugin_postgres | DbPlugin | Ships PostgresDbPlugin, backed by the official postgres Dart driver. Supports transactions, DDL batching, parameterized SQL, and LISTEN/NOTIFY |
Storage (files, blobs)
Backs vyuh.storage — at most one per server, optional.
| Package | Singleton role | Notes |
|---|---|---|
vyuh_server_plugin_storage | StoragePlugin | Bucket+path file ops (upload, download, delete, move, copy, list, public/signed URLs). Ships with SupabaseStoragePlugin; same plugin shape works for any S3/GCS adapter you add |
Auth
| Package | Strategy | Notes |
|---|---|---|
vyuh_server_plugin_auth_jwt | Bearer-token | Callback-based verifier — bring your own JWT library (dart_jsonwebtoken, jose, an OAuth provider SDK) |
vyuh_server_plugin_auth_apikey | API key | Header or query-param lookup. Lookup callback resolves against any backing store |
Multiple auth plugins can coexist — the framework concatenates their strategies into a single chain. A request walks the chain until one strategy returns an Actor or one throws AuthFailed.
Telemetry
| Package | Sink | Notes |
|---|---|---|
vyuh_server_plugin_telemetry_console | IOSink (stdout by default) | JSON-line output. Perfect for dev and tests |
vyuh_server_plugin_telemetry_otel | OpenTelemetry SDK | Production tracing. Configures itself from standard OTEL_* env vars |
Filters
| Package | Compiler | Notes |
|---|---|---|
cdx_query_server_postgres | PostgresQueryCompiler | Ships PostgresQueryPlugin, translating the cdx_query JSON AST into parameterized Postgres WHERE clauses |
Capability plugins
| Package | Claims descriptor | Notes |
|---|---|---|
vyuh_server_plugin_entity_crud | EntityCrudDescriptor<T> | Emits the standard list/get/create/update/delete/count/grouped/schema/saved-view/versioning/drafts/relationship route table from a typed config |
vyuh_server_plugin_realtime | RealtimeChannelDescriptor | Mounts /live and /live/status, subscribes to feature-declared ChannelSources, and fans changes out over SSE |
vyuh_server_plugin_openapi | n/a | Auto-generates /openapi.json from the live router and mounts a docs explorer at /docs (Scalar or Swagger UI) |
Picking a Set
A minimal HTTP service needs only vyuh_server. As soon as you persist relational data, add the Postgres DB plugin. As soon as you upload files, add the storage plugin. The rest is optional:
| You want… | Add… |
|---|---|
| A health-check endpoint | vyuh_server |
| Relational state | vyuh_server + vyuh_server_plugin_postgres |
| File/blob storage | + vyuh_server_plugin_storage |
| Authenticated users | vyuh_server + auth plugin |
| CRUD over entities | vyuh_server + vyuh_server_plugin_postgres + vyuh_server_plugin_entity_crud |
| Query filters on list endpoints | + cdx_query_server_postgres |
| SSE realtime updates | + vyuh_server_plugin_realtime |
/docs explorer | + vyuh_server_plugin_openapi |
| Production tracing | + vyuh_server_plugin_telemetry_otel |
See Installation for the actual pubspec.yaml snippets.