diff --git a/website/src/pages/documentation/broker.md b/website/src/pages/documentation/broker.md index 4821d39fe..81e634e26 100644 --- a/website/src/pages/documentation/broker.md +++ b/website/src/pages/documentation/broker.md @@ -16,7 +16,7 @@ npm install @deepkit/broker ## Broker Classes -Deepkit Broker provides four main broker classes: +Deepkit Broker provides these main broker classes: - **BrokerCache** - L2 cache abstraction with cache invalidation - **BrokerBus** - Message bus (Pub/Sub) @@ -26,6 +26,11 @@ Deepkit Broker provides four main broker classes: These classes are designed to take a broker adapter to communicate with a broker server in a type-safe way. +A default adapter `BrokerDeepkitAdapter` that communicates with Deepkit Broker server is included in the package, but you can write your own adapter to communicate with other broker servers (e.g. Redis). + +The FrameworkModule provides and registers the default adapter and connects to Deepkit Broker server, which runs per default in the same process. +In a production environment, you would run the broker server in a separate process or even on a different machine. + To give a high level overview of how the classes can be used outside the framework, here is an example: ```typescript @@ -43,6 +48,7 @@ class MyAdapter implements BrokerAdapterBus { } } +// or BrokerDeepkitAdapter for the default adapter const adapter = new MyAdapter; const bus = new BrokerBus(adapter); @@ -59,41 +65,26 @@ await channel.subscribe((message) => { await channel.publish({ foo: 'bar' }); ``` -In this example we write our own adapter to communicate with a broker server. The adapter is then passed to the BrokerBus class, which is used to create a channel. The channel can then be used to subscribe to messages and publish messages. +In this example we write our own adapter to communicate with a broker server. The adapter is then passed to the BrokerBus class, which is used to create a channel. +This is the common pattern all Broker classes follow: They take an adapter in the constructor and use it to communicate with the broker server. + +The channel can then be used to subscribe to messages and publish messages. Thanks to runtime types and the call `channel('my-channel-name');` everything is type-safe and the message can be validated and serialized automatically in the adapter directly. The default implementation `BrokerDeepkitAdapter` handles this automatically for you (and uses BSON for serialization). Note that each broker class has its own adapter interface, so you can implement only the methods you need. The `BrokerDeepkitAdapter` implements all of these interfaces and can be used in all broker classes. -To use these classes in a Deepkit application with dependency injection, you can use the `FrameworkModule` which provides a default adapter for the broker server and registers all broker classes as providers. See next chapter Usage for more information. - -Here is an example on how to manually set up an application with BrokerBus. - -```typescript -type MyBusChannel = BrokerBusChannel; - -const app = new App({ - providers: [ - MyAdapter, - provide((adapter: MyAdapter) => new BrokerBus(adapter)), - provide((bus: BrokerBus) => bus.channel('my-channel-name')), - ] -}); - -await app.get().subscribe((message) => { - console.log('received message', message); -}); - -await app.get().publish({ foo: 'bar' }); +To use these classes in a Deepkit application with dependency injection, you can use the `FrameworkModule` which provides several things: -app.get(MyAdapter).disconnect(); -``` +- a default adapter for the broker server +- the broker server itself (and starts it automatically) +- and registers all broker classes as providers ## Usage -The FrameworkModule provides a default broker adapter for the configured broker server based on the given configuration. -It also registers providers for all the broker classes, so you can inject them into your services directly. +The `FrameworkModule` provides a default broker adapter for the configured broker server based on the given configuration. +It also registers providers for all the broker classes, so you can inject them (e.g. BrokerBus) into your services and provider factories directly. ```typescript // in an extra file, e.g. broker-channels.ts @@ -115,8 +106,6 @@ const app = new App({ }, })], }); - -void app.run(); ``` You can then inject the broker derived classes (or the broker class directly) into your services: @@ -147,3 +136,22 @@ If you need more connections or a custom adapter, you can create your own adapte export type BrokerAdapter = BrokerAdapterCache & BrokerAdapterBus & BrokerAdapterLock & BrokerAdapterQueue & BrokerAdapterKeyValue; ``` +## Broker Server + +The Broker server starts automatically per default as soon as you import the `FrameworkModule` and run the `server:start` command. +All Broker classes are configured per default to connect to this server. + +In a production environment, you would run the broker server in a separate process or even on a different machine. Instead of doing `server:start` you would start the broker server with `server:broker:start`. + +```bash +ts-node app.ts server:broker:start +``` + +This starts the server on the host configured via for example `new FrameworkModule({broker: {listen: 'localhost:8811'}})`. +You could change the address also via environment variables if you enabled `app.loadConfigFromEnv({prefix: 'APP_', namingStrategy: 'upper'});`: + +```bash +APP_FRAMEWORK_BROKER_LISTEN=localhost:8811 ts-node app.ts server:broker:start +``` + +If you start the server manually, make sure to disable automatic broker server start via `startOnBootstrap: false` in your application configuration.