10000 Draft of overview documentation · aaronjensen/messaging-postgres@74e0701 · GitHub
[go: up one dir, main page]
Skip to content

Commit 74e0701

Browse files
sbellwaresbellware
committed
Draft of overview documentation
1 parent 4d6759a commit 74e0701

File tree

1 file changed

+123
-0
lines changed

1 file changed

+123
-0
lines changed

‎README.md

Lines changed: 123 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -2,6 +2,129 @@
22

33
Postgres messaging for Eventide
44

5+
## Summary
6+
7+
The `messaging-postgres` library contains primitives for writing and reading messages, as well as message handlers and mixins for message schemas and stream name utilities.
8+
9+
## Example
10+
11+
```ruby
12+
account_id = ‘123’
13+
14+
deposit = Deposit.new
15+
deposit.account_id = account_id
16+
deposit.amount = 11
17+
18+
stream_name = StreamName.stream_name(account_id, 'account')
19+
# => 'account-123'
20+
21+
Messaging::Postgres::Write.(deposit, stream_name)
22+
23+
Messaging::Postgres::Read.(stream_name) do |message_data|
24+
AccountComponent::Handlers::Command.(message_data)
25+
end
26+
```
27+
28+
## Elements
29+
30+
### Handlers
31+
32+
A Handler is the mechanism that receives messages, and takes action based on them.
33+
34+
By including `Messaging::Handle`, a class becomes a handler. By including `Messaging::Postgres::StreamName` the handler class receives some useful utilities for composing stream names from constituent parts (category and an entity's ID), and for declaring a the category name that the handler is concerned with (eg: `account`, `fundsTransfer`, `userProfile`, etc).
35+
36+
```ruby
37+
module AccountComponent
38+
module Handlers
39+
class Commands
40+
include Messaging::Handle
41+
include Messaging::Postgres::StreamName
42+
43+
category :account
44+
45+
handle Deposit do |deposit|
46+
account_id = deposit.account_id
47+
48+
time = clock.iso8601
49+
50+
deposited = Deposited.follow(deposit)
51+
52+
stream_name = stream_name(account_id)
53+
54+
write.(deposited, stream_name, expected_version: version)
55+
end
56+
end
57+
end
58+
end
59+
```
60+
61+
### Messages
62+
63+
Messages are typically simplistic data structures that carry instructions and responses to and from services.
64+
65+
By including `Messaging::Message`, a message class can declare attributes that will become part of a message's payload.
66+
67+
```ruby
68+
module AccountComponent
69+
module Messages
70+
module Commands
71+
class Deposit
72+
include Messaging::Message
73+
74+
attribute :deposit_id, String
75+
attribute :account_id, String
76+
attribute :amount, Numeric
77+
attribute :time, String
78+
end
79+
end
80+
end
81+
end
82+
83+
deposit = AccountComponent::Messages::Commands::Deposit.new
84+
85+
deposit.deposit_id = Identifier::UUID::Random.get
86+
deposit.account_id = account_id
87+
deposit.amount = 11
88+
deposit.time = clock.iso8601
89+
```
90+
91+
### Reading Messages
92+
93+
The `Messaging::Postgres::Read` class provides access to streams stored in Postgres. The reader takes a block that receives raw _message data_, and executes the block for each message data received.
94+
95+
```ruby
96+
stream_name = 'account-123'
97+
98+
Messaging::Postgres::Read.(stream_name) do |message_data|
99+
puts message_data.type
100+
end
101+
```
102+
103+
### Writing Messages
104+
105+
The `Messaging::Postgres::Write` class writes a message to a stream. The message is converted to raw _message data_ first, then written to the data store.
106+
107+
```ruby
108+
deposit = AccountComponent::Messages::Commands::Deposit.new
109+
110+
deposit.deposit_id = Identifier::UUID::Random.get
111+
deposit.account_id = account_id
112+
deposit.amount = 11
113+
deposit.time = clock.iso8601
114+
115+
stream_name = 'account-123'
116+
117+
Messaging::Postgres::Write.(deposit, stream_name)
118+
```
119+
120+
## Detailed Examples
121+
122+
For a more in-depth example of the use of this library, see the example projects in the Eventide Examples org on GitHub: https://github.com/eventide-examples
123+
124+
## Complete Documentation
125+
126+
The complete Eventide project documentation can be found at http://eventide-project.org
127+
5128
## License
6129

7130
The `messaging-postgres` library is released under the [MIT License](https://github.com/eventide-project/messaging-postgres/blob/master/MIT-License.txt).

0 commit comments

Comments
 (0)
0