-
Notifications
You must be signed in to change notification settings - Fork 8
/
Copy pathchapter_10_commands.html
962 lines (897 loc) · 57.1 KB
/
chapter_10_commands.html
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
508
509
510
511
512
513
514
515
516
517
518
519
520
521
522
523
524
525
526
527
528
529
530
531
532
533
534
535
536
537
538
539
540
541
542
543
544
545
546
547
548
549
550
551
552
553
554
555
556
557
558
559
560
561
562
563
564
565
566
567
568
569
570
571
572
573
574
575
576
577
578
579
580
581
582
583
584
585
586
587
588
589
590
591
592
593
594
595
596
597
598
599
600
601
602
603
604
605
606
607
608
609
610
611
612
613
614
615
616
617
618
619
620
621
622
623
624
625
626
627
628
629
630
631
632
633
634
635
636
637
638
639
640
641
642
643
644
645
646
647
648
649
650
651
652
653
654
655
656
657
658
659
660
661
662
663
664
665
666
667
668
669
670
671
672
673
674
675
676
677
678
679
680
681
682
683
684
685
686
687
688
689
690
691
692
693
694
695
696
697
698
699
700
701
702
703
704
705
706
707
708
709
710
711
712
713
714
715
716
717
718
719
720
721
722
723
724
725
726
727
728
729
730
731
732
733
734
735
736
737
738
739
740
741
742
743
744
745
746
747
748
749
750
751
752
753
754
755
756
757
758
759
760
761
762
763
764
765
766
767
768
769
770
771
772
773
774
775
776
777
778
779
780
781
782
783
784
785
786
787
788
789
790
791
792
793
794
795
796
797
798
799
800
801
802
803
804
805
806
807
808
809
810
811
812
813
814
815
816
817
818
819
820
821
822
823
824
825
826
827
828
829
830
831
832
833
834
835
836
837
838
839
840
841
842
843
844
845
846
847
848
849
850
851
852
853
854
855
856
857
858
859
860
861
862
863
864
865
866
867
868
869
870
871
872
873
874
875
876
877
878
879
880
881
882
883
884
885
886
887
888
889
890
891
892
893
894
895
896
897
898
899
900
901
902
903
904
905
906
907
908
909
910
911
912
913
914
915
916
917
918
919
920
921
922
923
924
925
926
927
928
929
930
931
932
933
934
935
936
937
938
939
940
941
942
943
944
945
946
947
948
949
950
951
952
953
954
955
956
957
958
959
960
961
962
<html lang="en">
<head>
<meta charset="UTF-8">
<meta http-equiv="X-UA-Compatible" content="IE=edge">
<meta name="viewport" content="width=device-width, initial-scale=1.0">
<meta name="generator" content="Asciidoctor 2.0.20">
<title>Commands and Command Handler</title>
<style>
/* Asciidoctor default stylesheet | MIT License | https://asciidoctor.org */
@import url("//fonts.googleapis.com/css?family=Noto+Sans:300,600italic,400,400italic,600,600italic%7CNoto+Serif:400,400italic,700,700italic%7CDroid+Sans+Mono:400,700");
@import url(//asciidoctor.org/stylesheets/asciidoctor.css); /* Default asciidoc style framework - important */
/* customisations by harry */
h1, h2, h3, h4, h5, h6 {
position: relative;
}
a.anchor {
top: 0;
}
/* hide inline ditaa/plantuml source listings for images */
.image-source {
display: none
}
/* make formal codeblocks a bit nicer */
.exampleblock > .content {
padding: 2px;
background-color: white;
border: 0;
margin-bottom: 2em;
}
.exampleblock .title {
text-align: right;
}
/* prev/next chapter links at bottom of page */
.prev_and_next_chapter_links {
margin: 10px;
}
.prev_chapter_link {
float: left;
}
.next_chapter_link {
float: right;
}
/* a few tweaks to existing styles */
#toc li {
margin-top: 0.5em;
}
#footnotes hr {
width: 100%;
}
/* end customisations by harry */
/* CUSTOMISATIONS */
/* Change the values in root for quick customisation. If you want even more fine grain... venture further. */
:root{
--maincolor:#FFFFFF;
--primarycolor:#2c3e50;
--secondarycolor:#ba3925;
--tertiarycolor: #186d7a;
--sidebarbackground:#CCC;
--linkcolor:#b71c1c;
--linkcoloralternate:#f44336;
--white:#FFFFFF;
--black:#000000;
}
/* Text styles */
h1{color:var(--primarycolor) !important;}
h2,h3,h4,h5,h6{color:var(--secondarycolor) !important;}
.title{color:var(--tertiarycolor) !important; font-family:"Noto Sans",sans-serif !important;font-style: normal !important; font-weight: normal !important;}
p{font-family: "Noto Sans",sans-serif !important}
/* Table styles */
th{font-family: "Noto Sans",sans-serif !important}
/* Responsiveness fixes */
video {
max-width: 100%;
}
@media all and (max-width: 600px) {
table {
width: 55vw!important;
font-size: 3vw;
}
</style>
<style>
pre.pygments .hll { background-color: #ffffcc }
pre.pygments { background: #f0f0f0; }
pre.pygments .tok-c { color: #60a0b0; font-style: italic } /* Comment */
pre.pygments .tok-err { border: 1px solid #FF0000 } /* Error */
pre.pygments .tok-k { color: #007020; font-weight: bold } /* Keyword */
pre.pygments .tok-o { color: #666666 } /* Operator */
pre.pygments .tok-ch { color: #60a0b0; font-style: italic } /* Comment.Hashbang */
pre.pygments .tok-cm { color: #60a0b0; font-style: italic } /* Comment.Multiline */
pre.pygments .tok-cp { color: #007020 } /* Comment.Preproc */
pre.pygments .tok-cpf { color: #60a0b0; font-style: italic } /* Comment.PreprocFile */
pre.pygments .tok-c1 { color: #60a0b0; font-style: italic } /* Comment.Single */
pre.pygments .tok-cs { color: #60a0b0; background-color: #fff0f0 } /* Comment.Special */
pre.pygments .tok-gd { color: #A00000 } /* Generic.Deleted */
pre.pygments .tok-ge { font-style: italic } /* Generic.Emph */
pre.pygments .tok-gr { color: #FF0000 } /* Generic.Error */
pre.pygments .tok-gh { color: #000080; font-weight: bold } /* Generic.Heading */
pre.pygments .tok-gi { color: #00A000 } /* Generic.Inserted */
pre.pygments .tok-go { color: #888888 } /* Generic.Output */
pre.pygments .tok-gp { color: #c65d09; font-weight: bold } /* Generic.Prompt */
pre.pygments .tok-gs { font-weight: bold } /* Generic.Strong */
pre.pygments .tok-gu { color: #800080; font-weight: bold } /* Generic.Subheading */
pre.pygments .tok-gt { color: #0044DD } /* Generic.Traceback */
pre.pygments .tok-kc { color: #007020; font-weight: bold } /* Keyword.Constant */
pre.pygments .tok-kd { color: #007020; font-weight: bold } /* Keyword.Declaration */
pre.pygments .tok-kn { color: #007020; font-weight: bold } /* Keyword.Namespace */
pre.pygments .tok-kp { color: #007020 } /* Keyword.Pseudo */
pre.pygments .tok-kr { color: #007020; font-weight: bold } /* Keyword.Reserved */
pre.pygments .tok-kt { color: #902000 } /* Keyword.Type */
pre.pygments .tok-m { color: #40a070 } /* Literal.Number */
pre.pygments .tok-s { color: #4070a0 } /* Literal.String */
pre.pygments .tok-na { color: #4070a0 } /* Name.Attribute */
pre.pygments .tok-nb { color: #007020 } /* Name.Builtin */
pre.pygments .tok-nc { color: #0e84b5; font-weight: bold } /* Name.Class */
pre.pygments .tok-no { color: #60add5 } /* Name.Constant */
pre.pygments .tok-nd { color: #555555; font-weight: bold } /* Name.Decorator */
pre.pygments .tok-ni { color: #d55537; font-weight: bold } /* Name.Entity */
pre.pygments .tok-ne { color: #007020 } /* Name.Exception */
pre.pygments .tok-nf { color: #06287e } /* Name.Function */
pre.pygments .tok-nl { color: #002070; font-weight: bold } /* Name.Label */
pre.pygments .tok-nn { color: #0e84b5; font-weight: bold } /* Name.Namespace */
pre.pygments .tok-nt { color: #062873; font-weight: bold } /* Name.Tag */
pre.pygments .tok-nv { color: #bb60d5 } /* Name.Variable */
pre.pygments .tok-ow { color: #007020; font-weight: bold } /* Operator.Word */
pre.pygments .tok-w { color: #bbbbbb } /* Text.Whitespace */
pre.pygments .tok-mb { color: #40a070 } /* Literal.Number.Bin */
pre.pygments .tok-mf { color: #40a070 } /* Literal.Number.Float */
pre.pygments .tok-mh { color: #40a070 } /* Literal.Number.Hex */
pre.pygments .tok-mi { color: #40a070 } /* Literal.Number.Integer */
pre.pygments .tok-mo { color: #40a070 } /* Literal.Number.Oct */
pre.pygments .tok-sa { color: #4070a0 } /* Literal.String.Affix */
pre.pygments .tok-sb { color: #4070a0 } /* Literal.String.Backtick */
pre.pygments .tok-sc { color: #4070a0 } /* Literal.String.Char */
pre.pygments .tok-dl { color: #4070a0 } /* Literal.String.Delimiter */
pre.pygments .tok-sd { color: #4070a0; font-style: italic } /* Literal.String.Doc */
pre.pygments .tok-s2 { color: #4070a0 } /* Literal.String.Double */
pre.pygments .tok-se { color: #4070a0; font-weight: bold } /* Literal.String.Escape */
pre.pygments .tok-sh { color: #4070a0 } /* Literal.String.Heredoc */
pre.pygments .tok-si { color: #70a0d0; font-style: italic } /* Literal.String.Interpol */
pre.pygments .tok-sx { color: #c65d09 } /* Literal.String.Other */
pre.pygments .tok-sr { color: #235388 } /* Literal.String.Regex */
pre.pygments .tok-s1 { color: #4070a0 } /* Literal.String.Single */
pre.pygments .tok-ss { color: #517918 } /* Literal.String.Symbol */
pre.pygments .tok-bp { color: #007020 } /* Name.Builtin.Pseudo */
pre.pygments .tok-fm { color: #06287e } /* Name.Function.Magic */
pre.pygments .tok-vc { color: #bb60d5 } /* Name.Variable.Class */
pre.pygments .tok-vg { color: #bb60d5 } /* Name.Variable.Global */
pre.pygments .tok-vi { color: #bb60d5 } /* Name.Variable.Instance */
pre.pygments .tok-vm { color: #bb60d5 } /* Name.Variable.Magic */
pre.pygments .tok-il { color: #40a070 } /* Literal.Number.Integer.Long */
</style>
</head>
<body class="article toc2 toc-left">
<div id="buy_the_book" style="position: absolute; top: 0; right: 0; z-index:100">
<a href="/#buy_the_book">
<img src="/images/buy_the_book.svg" alt="buy the book ribbon">
</a>
</div>
<div id="header">
<div id="toc" class="toc2">
<div id="toctitle">Table of Contents</div>
<ul class="sectlevel1">
<li><a href="/book/preface.html">Preface</a></li>
<li><a href="/book/introduction.html">Introduction</a></li>
<li><a href="/book/part1.html">Part 1: Building an Architecture to Support Domain Modeling</a></li>
<li><a href="/book/chapter_01_domain_model.html">1. Domain Modeling</a></li>
<li><a href="/book/chapter_02_repository.html">2. Repository Pattern</a></li>
<li><a href="/book/chapter_03_abstractions.html">3. A Brief Interlude: On Coupling <span class="keep-together">and Abstractions</span></a></li>
<li><a href="/book/chapter_04_service_layer.html">4. Our First Use Case: <span class="keep-together">Flask API and Service Layer</span></a></li>
<li><a href="/book/chapter_05_high_gear_low_gear.html">5. TDD in High Gear and Low Gear</a></li>
<li><a href="/book/chapter_06_uow.html">6. Unit of Work Pattern</a></li>
<li><a href="/book/chapter_07_aggregate.html">7. Aggregates and Consistency Boundaries</a></li>
<li><a href="/book/part2.html">Part 2: Event-Driven Architecture</a></li>
<li><a href="/book/chapter_08_events_and_message_bus.html">8. Events and the Message Bus</a></li>
<li><a href="/book/chapter_09_all_messagebus.html">9. Going to Town on the Message Bus</a></li>
<li><a href="/book/chapter_10_commands.html">10. Commands and Command Handler</a></li>
<li><a href="/book/chapter_11_external_events.html">11. Event-Driven Architecture: Using Events to Integrate Microservices</a></li>
<li><a href="/book/chapter_12_cqrs.html">12. Command-Query Responsibility Segregation (CQRS)</a></li>
<li><a href="/book/chapter_13_dependency_injection.html">13. Dependency Injection (and Bootstrapping)</a></li>
<li><a href="/book/epilogue_1_how_to_get_there_from_here.html">Epilogue: Epilogue</a></li>
<li><a href="/book/appendix_ds1_table.html">Appendix A: Summary Diagram and Table</a></li>
<li><a href="/book/appendix_project_structure.html">Appendix B: A Template Project Structure</a></li>
<li><a href="/book/appendix_csvs.html">Appendix C: Swapping Out the Infrastructure: Do Everything with CSVs</a></li>
<li><a href="/book/appendix_django.html">Appendix D: Repository and Unit of Work Patterns with Django</a></li>
<li><a href="/book/appendix_validation.html">Appendix E: Validation</a></li>
</ul>
</div>
</div>
<div id="content">
<div class="sect1">
<h2 id="chapter_10_commands">10: Commands and Command Handler<a class="anchor" href="#chapter_10_commands"></a></h2>
<div class="sectionbody">
<div class="paragraph">
<p>
In the previous chapter, we talked about using events as a way of representing
the inputs to our system, and we turned our application into a message-processing
machine.</p>
</div>
<div class="paragraph">
<p>To achieve that, we converted all our use-case functions to event handlers.
When the API receives a POST to create a new batch, it builds a new <code>BatchCreated</code>
event and handles it as if it were an internal event.
This might feel counterintuitive. After all, the batch <em>hasn’t</em> been
created yet; that’s why we called the API. We’re going to fix that conceptual
wart by introducing commands and showing how they can be handled by the same
message bus but with slightly different rules.</p>
</div>
<div class="admonitionblock tip">
<table>
<tr>
<td class="icon">
<div class="title">Tip</div>
</td>
<td class="content">
<div class="paragraph">
<p>The code for this chapter is in the
chapter_10_commands branch <a href="https://oreil.ly/U_VGa">on GitHub</a>:</p>
</div>
<div class="listingblock">
<div class="content">
<pre>git clone https://github.com/cosmicpython/code.git
cd code
git checkout chapter_10_commands
# or to code along, checkout the previous chapter:
git checkout chapter_09_all_messagebus</pre>
</div>
</div>
</td>
</tr>
</table>
</div>
<div class="sect2">
<h3 id="_commands_and_events"><a class="anchor" href="#_commands_and_events"></a>Commands and Events</h3>
<div class="paragraph">
<p>
Like events, <em>commands</em> are a type of message—​instructions sent by one part of
a system to another. We usually represent commands with dumb data
structures and can handle them in much the same way as events.</p>
</div>
<div class="paragraph">
<p>The differences between commands and events, though, are important.</p>
</div>
<div class="paragraph">
<p>Commands are sent by one actor to another specific actor with the expectation that
a particular thing will happen as a result. When we post a form to an API handler,
we are sending a command. We name commands with imperative mood verb phrases like
"allocate stock" or "delay shipment."</p>
</div>
<div class="paragraph">
<p>Commands capture <em>intent</em>. They express our wish for the system to do something.
As a result, when they fail, the sender needs to receive error information.</p>
</div>
<div class="paragraph">
<p><em>Events</em> are broadcast by an actor to all interested listeners. When we publish
<code>BatchQuantityChanged</code>, we don’t know who’s going to pick it up. We name events
with past-tense verb phrases like "order allocated to stock" or "shipment delayed."</p>
</div>
<div class="paragraph">
<p>We often use events to spread the knowledge about successful commands.</p>
</div>
<div class="paragraph">
<p>Events capture <em>facts</em> about things that happened in the past. Since we don’t
know who’s handling an event, senders should not care whether the receivers
succeeded or failed. <a href="#events_vs_commands_table">Events versus commands</a> recaps the differences.</p>
</div>
<table id="events_vs_commands_table" class="tableblock frame-all grid-all stretch">
<caption class="title">Table 1. Events versus commands</caption>
<colgroup>
<col style="width: 33.3333%;">
<col style="width: 33.3333%;">
<col style="width: 33.3334%;">
</colgroup>
<thead>
<tr>
<th class="tableblock halign-left valign-top"></th>
<th class="tableblock halign-left valign-top">Event</th>
<th class="tableblock halign-left valign-top">Command</th>
</tr>
</thead>
<tbody>
<tr>
<td class="tableblock halign-left valign-top"><p class="tableblock">Named</p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock">Past tense</p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock">Imperative mood</p></td>
</tr>
<tr>
<td class="tableblock halign-left valign-top"><p class="tableblock">Error handling</p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock">Fail independently</p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock">Fail noisily</p></td>
</tr>
<tr>
<td class="tableblock halign-left valign-top"><p class="tableblock">Sent to</p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock">All listeners</p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock">One recipient</p></td>
</tr>
</tbody>
</table>
<div class="paragraph">
<p>
What kinds of commands do we have in our system right now?</p>
</div>
<div id="commands_dot_py" class="exampleblock">
<div class="title">Pulling out some commands (src/allocation/domain/commands.py)</div>
<div class="content">
<div class="listingblock">
<div class="content">
<pre class="pygments highlight"><code data-lang="python"><span></span><span class="tok-k">class</span> <span class="tok-nc">Command</span><span class="tok-p">:</span>
<span class="tok-k">pass</span>
<span class="tok-nd">@dataclass</span>
<span class="tok-k">class</span> <span class="tok-nc">Allocate</span><span class="tok-p">(</span><span class="tok-n">Command</span><span class="tok-p">):</span> #<b class="conum">(1)</b>
<span class="tok-n">orderid</span><span class="tok-p">:</span> <span class="tok-nb">str</span>
<span class="tok-n">sku</span><span class="tok-p">:</span> <span class="tok-nb">str</span>
<span class="tok-n">qty</span><span class="tok-p">:</span> <span class="tok-nb">int</span>
<span class="tok-nd">@dataclass</span>
<span class="tok-k">class</span> <span class="tok-nc">CreateBatch</span><span class="tok-p">(</span><span class="tok-n">Command</span><span class="tok-p">):</span> #<b class="conum">(2)</b>
<span class="tok-n">ref</span><span class="tok-p">:</span> <span class="tok-nb">str</span>
<span class="tok-n">sku</span><span class="tok-p">:</span> <span class="tok-nb">str</span>
<span class="tok-n">qty</span><span class="tok-p">:</span> <span class="tok-nb">int</span>
<span class="tok-n">eta</span><span class="tok-p">:</span> <span class="tok-n">Optional</span><span class="tok-p">[</span><span class="tok-n">date</span><span class="tok-p">]</span> <span class="tok-o">=</span> <span class="tok-kc">None</span>
<span class="tok-nd">@dataclass</span>
<span class="tok-k">class</span> <span class="tok-nc">ChangeBatchQuantity</span><span class="tok-p">(</span><span class="tok-n">Command</span><span class="tok-p">):</span> #<b class="conum">(3)</b>
<span class="tok-n">ref</span><span class="tok-p">:</span> <span class="tok-nb">str</span>
<span class="tok-n">qty</span><span class="tok-p">:</span> <span class="tok-nb">int</span></code></pre>
</div>
</div>
</div>
</div>
<div class="colist arabic">
<ol>
<li>
<p><code>commands.Allocate</code> will replace <code>events.AllocationRequired</code>.</p>
</li>
<li>
<p><code>commands.CreateBatch</code> will replace <code>events.BatchCreated</code>.</p>
</li>
<li>
<p><code>commands.ChangeBatchQuantity</code> will replace <code>events.BatchQuantityChanged</code>.</p>
</li>
</ol>
</div>
</div>
<div class="sect2">
<h3 id="_differences_in_exception_handling"><a class="anchor" href="#_differences_in_exception_handling"></a>Differences in Exception Handling</h3>
<div class="paragraph">
<p>
Just changing the names and verbs is all very well, but that won’t
change the behavior of our system. We want to treat events and commands similarly,
but not exactly the same. Let’s see how our message bus changes:</p>
</div>
<div id="messagebus_dispatches_differently" class="exampleblock">
<div class="title">Dispatch events and commands differently (src/allocation/service_layer/messagebus.py)</div>
<div class="content">
<div class="listingblock">
<div class="content">
<pre class="pygments highlight"><code data-lang="python"><span></span><span class="tok-n">Message</span> <span class="tok-o">=</span> <span class="tok-n">Union</span><span class="tok-p">[</span><span class="tok-n">commands</span><span class="tok-o">.</span><span class="tok-n">Command</span><span class="tok-p">,</span> <span class="tok-n">events</span><span class="tok-o">.</span><span class="tok-n">Event</span><span class="tok-p">]</span>
<span class="tok-k">def</span> <span class="tok-nf">handle</span><span class="tok-p">(</span> #<b class="conum">(1)</b>
<span class="tok-n">message</span><span class="tok-p">:</span> <span class="tok-n">Message</span><span class="tok-p">,</span>
<span class="tok-n">uow</span><span class="tok-p">:</span> <span class="tok-n">unit_of_work</span><span class="tok-o">.</span><span class="tok-n">AbstractUnitOfWork</span><span class="tok-p">,</span>
<span class="tok-p">):</span>
<span class="tok-n">results</span> <span class="tok-o">=</span> <span class="tok-p">[]</span>
<span class="tok-n">queue</span> <span class="tok-o">=</span> <span class="tok-p">[</span><span class="tok-n">message</span><span class="tok-p">]</span>
<span class="tok-k">while</span> <span class="tok-n">queue</span><span class="tok-p">:</span>
<span class="tok-n">message</span> <span class="tok-o">=</span> <span class="tok-n">queue</span><span class="tok-o">.</span><span class="tok-n">pop</span><span class="tok-p">(</span><span class="tok-mi">0</span><span class="tok-p">)</span>
<span class="tok-k">if</span> <span class="tok-nb">isinstance</span><span class="tok-p">(</span><span class="tok-n">message</span><span class="tok-p">,</span> <span class="tok-n">events</span><span class="tok-o">.</span><span class="tok-n">Event</span><span class="tok-p">):</span>
<span class="tok-n">handle_event</span><span class="tok-p">(</span><span class="tok-n">message</span><span class="tok-p">,</span> <span class="tok-n">queue</span><span class="tok-p">,</span> <span class="tok-n">uow</span><span class="tok-p">)</span> #<b class="conum">(2)</b>
<span class="tok-k">elif</span> <span class="tok-nb">isinstance</span><span class="tok-p">(</span><span class="tok-n">message</span><span class="tok-p">,</span> <span class="tok-n">commands</span><span class="tok-o">.</span><span class="tok-n">Command</span><span class="tok-p">):</span>
<span class="tok-n">cmd_result</span> <span class="tok-o">=</span> <span class="tok-n">handle_command</span><span class="tok-p">(</span><span class="tok-n">message</span><span class="tok-p">,</span> <span class="tok-n">queue</span><span class="tok-p">,</span> <span class="tok-n">uow</span><span class="tok-p">)</span> #<b class="conum">(2)</b>
<span class="tok-n">results</span><span class="tok-o">.</span><span class="tok-n">append</span><span class="tok-p">(</span><span class="tok-n">cmd_result</span><span class="tok-p">)</span>
<span class="tok-k">else</span><span class="tok-p">:</span>
<span class="tok-k">raise</span> <span class="tok-ne">Exception</span><span class="tok-p">(</span><span class="tok-sa">f</span><span class="tok-s2">"</span><span class="tok-si">{</span><span class="tok-n">message</span><span class="tok-si">}</span><span class="tok-s2"> was not an Event or Command"</span><span class="tok-p">)</span>
<span class="tok-k">return</span> <span class="tok-n">results</span></code></pre>
</div>
</div>
</div>
</div>
<div class="colist arabic">
<ol>
<li>
<p>It still has a main <code>handle()</code> entrypoint that takes a <code>message</code>, which may
be a command or an event.</p>
</li>
<li>
<p>We dispatch events and commands to two different helper functions, shown next.</p>
</li>
</ol>
</div>
<div class="paragraph">
<p>Here’s how we handle events:</p>
</div>
<div id="handle_event" class="exampleblock">
<div class="title">Events cannot interrupt the flow (src/allocation/service_layer/messagebus.py)</div>
<div class="content">
<div class="listingblock">
<div class="content">
<pre class="pygments highlight"><code data-lang="python"><span></span><span class="tok-k">def</span> <span class="tok-nf">handle_event</span><span class="tok-p">(</span>
<span class="tok-n">event</span><span class="tok-p">:</span> <span class="tok-n">events</span><span class="tok-o">.</span><span class="tok-n">Event</span><span class="tok-p">,</span>
<span class="tok-n">queue</span><span class="tok-p">:</span> <span class="tok-n">List</span><span class="tok-p">[</span><span class="tok-n">Message</span><span class="tok-p">],</span>
<span class="tok-n">uow</span><span class="tok-p">:</span> <span class="tok-n">unit_of_work</span><span class="tok-o">.</span><span class="tok-n">AbstractUnitOfWork</span><span class="tok-p">,</span>
<span class="tok-p">):</span>
<span class="tok-k">for</span> <span class="tok-n">handler</span> <span class="tok-ow">in</span> <span class="tok-n">EVENT_HANDLERS</span><span class="tok-p">[</span><span class="tok-nb">type</span><span class="tok-p">(</span><span class="tok-n">event</span><span class="tok-p">)]:</span> #<b class="conum">(1)</b>
<span class="tok-k">try</span><span class="tok-p">:</span>
<span class="tok-n">logger</span><span class="tok-o">.</span><span class="tok-n">debug</span><span class="tok-p">(</span><span class="tok-s2">"handling event </span><span class="tok-si">%s</span><span class="tok-s2"> with handler </span><span class="tok-si">%s</span><span class="tok-s2">"</span><span class="tok-p">,</span> <span class="tok-n">event</span><span class="tok-p">,</span> <span class="tok-n">handler</span><span class="tok-p">)</span>
<span class="tok-n">handler</span><span class="tok-p">(</span><span class="tok-n">event</span><span class="tok-p">,</span> <span class="tok-n">uow</span><span class="tok-o">=</span><span class="tok-n">uow</span><span class="tok-p">)</span>
<span class="tok-n">queue</span><span class="tok-o">.</span><span class="tok-n">extend</span><span class="tok-p">(</span><span class="tok-n">uow</span><span class="tok-o">.</span><span class="tok-n">collect_new_events</span><span class="tok-p">())</span>
<span class="tok-k">except</span> <span class="tok-ne">Exception</span><span class="tok-p">:</span>
<span class="tok-n">logger</span><span class="tok-o">.</span><span class="tok-n">exception</span><span class="tok-p">(</span><span class="tok-s2">"Exception handling event </span><span class="tok-si">%s</span><span class="tok-s2">"</span><span class="tok-p">,</span> <span class="tok-n">event</span><span class="tok-p">)</span>
<span class="tok-k">continue</span> #<b class="conum">(2)</b></code></pre>
</div>
</div>
</div>
</div>
<div class="colist arabic">
<ol>
<li>
<p>Events go to a dispatcher that can delegate to multiple handlers per
event.</p>
</li>
<li>
<p>It catches and logs errors but doesn’t let them interrupt
message processing.</p>
</li>
</ol>
</div>
<div class="paragraph">
<p>
And here’s how we do commands:</p>
</div>
<div id="handle_command" class="exampleblock">
<div class="title">Commands reraise exceptions (src/allocation/service_layer/messagebus.py)</div>
<div class="content">
<div class="listingblock">
<div class="content">
<pre class="pygments highlight"><code data-lang="python"><span></span><span class="tok-k">def</span> <span class="tok-nf">handle_command</span><span class="tok-p">(</span>
<span class="tok-n">command</span><span class="tok-p">:</span> <span class="tok-n">commands</span><span class="tok-o">.</span><span class="tok-n">Command</span><span class="tok-p">,</span>
<span class="tok-n">queue</span><span class="tok-p">:</span> <span class="tok-n">List</span><span class="tok-p">[</span><span class="tok-n">Message</span><span class="tok-p">],</span>
<span class="tok-n">uow</span><span class="tok-p">:</span> <span class="tok-n">unit_of_work</span><span class="tok-o">.</span><span class="tok-n">AbstractUnitOfWork</span><span class="tok-p">,</span>
<span class="tok-p">):</span>
<span class="tok-n">logger</span><span class="tok-o">.</span><span class="tok-n">debug</span><span class="tok-p">(</span><span class="tok-s2">"handling command </span><span class="tok-si">%s</span><span class="tok-s2">"</span><span class="tok-p">,</span> <span class="tok-n">command</span><span class="tok-p">)</span>
<span class="tok-k">try</span><span class="tok-p">:</span>
<span class="tok-n">handler</span> <span class="tok-o">=</span> <span class="tok-n">COMMAND_HANDLERS</span><span class="tok-p">[</span><span class="tok-nb">type</span><span class="tok-p">(</span><span class="tok-n">command</span><span class="tok-p">)]</span> #<b class="conum">(1)</b>
<span class="tok-n">result</span> <span class="tok-o">=</span> <span class="tok-n">handler</span><span class="tok-p">(</span><span class="tok-n">command</span><span class="tok-p">,</span> <span class="tok-n">uow</span><span class="tok-o">=</span><span class="tok-n">uow</span><span class="tok-p">)</span>
<span class="tok-n">queue</span><span class="tok-o">.</span><span class="tok-n">extend</span><span class="tok-p">(</span><span class="tok-n">uow</span><span class="tok-o">.</span><span class="tok-n">collect_new_events</span><span class="tok-p">())</span>
<span class="tok-k">return</span> <span class="tok-n">result</span> #<b class="conum">(3)</b>
<span class="tok-k">except</span> <span class="tok-ne">Exception</span><span class="tok-p">:</span>
<span class="tok-n">logger</span><span class="tok-o">.</span><span class="tok-n">exception</span><span class="tok-p">(</span><span class="tok-s2">"Exception handling command </span><span class="tok-si">%s</span><span class="tok-s2">"</span><span class="tok-p">,</span> <span class="tok-n">command</span><span class="tok-p">)</span>
<span class="tok-k">raise</span> #<b class="conum">(2)</b></code></pre>
</div>
</div>
</div>
</div>
<div class="colist arabic">
<ol>
<li>
<p>The command dispatcher expects just one handler per command.</p>
</li>
<li>
<p>If any errors are raised, they fail fast and will bubble up.</p>
</li>
<li>
<p><code>return result</code> is only temporary; as mentioned in <a href="/book/chapter_09_all_messagebus.html#temporary_ugly_hack">[temporary_ugly_hack]</a>,
it’s a temporary hack to allow the message bus to return the batch
reference for the API to use. We’ll fix this in <a href="/book/chapter_12_cqrs.html">[chapter_12_cqrs]</a>.</p>
</li>
</ol>
</div>
<div class="paragraph">
<p>
We also change the single <code>HANDLERS</code> dict into different ones for
commands and events. Commands can have only one handler, according
to our convention:</p>
</div>
<div id="new_handlers_dicts" class="exampleblock">
<div class="title">New handlers dicts (src/allocation/service_layer/messagebus.py)</div>
<div class="content">
<div class="listingblock">
<div class="content">
<pre class="pygments highlight"><code data-lang="python"><span></span><span class="tok-n">EVENT_HANDLERS</span> <span class="tok-o">=</span> <span class="tok-p">{</span>
<span class="tok-n">events</span><span class="tok-o">.</span><span class="tok-n">OutOfStock</span><span class="tok-p">:</span> <span class="tok-p">[</span><span class="tok-n">handlers</span><span class="tok-o">.</span><span class="tok-n">send_out_of_stock_notification</span><span class="tok-p">],</span>
<span class="tok-p">}</span> <span class="tok-c1"># type: Dict[Type[events.Event], List[Callable]]</span>
<span class="tok-n">COMMAND_HANDLERS</span> <span class="tok-o">=</span> <span class="tok-p">{</span>
<span class="tok-n">commands</span><span class="tok-o">.</span><span class="tok-n">Allocate</span><span class="tok-p">:</span> <span class="tok-n">handlers</span><span class="tok-o">.</span><span class="tok-n">allocate</span><span class="tok-p">,</span>
<span class="tok-n">commands</span><span class="tok-o">.</span><span class="tok-n">CreateBatch</span><span class="tok-p">:</span> <span class="tok-n">handlers</span><span class="tok-o">.</span><span class="tok-n">add_batch</span><span class="tok-p">,</span>
<span class="tok-n">commands</span><span class="tok-o">.</span><span class="tok-n">ChangeBatchQuantity</span><span class="tok-p">:</span> <span class="tok-n">handlers</span><span class="tok-o">.</span><span class="tok-n">change_batch_quantity</span><span class="tok-p">,</span>
<span class="tok-p">}</span> <span class="tok-c1"># type: Dict[Type[commands.Command], Callable]</span></code></pre>
</div>
</div>
</div>
</div>
</div>
<div class="sect2">
<h3 id="_discussion_events_commands_and_error_handling"><a class="anchor" href="#_discussion_events_commands_and_error_handling"></a>Discussion: Events, Commands, and Error Handling</h3>
<div class="paragraph">
<p>
Many developers get uncomfortable at this point and ask, "What happens when an
event fails to process? How am I supposed to make sure the system is in a
consistent state?" If we manage to process half of the events during <code>messagebus.handle</code> before an
out-of-memory error kills our process, how do we mitigate problems caused by the
lost messages?</p>
</div>
<div class="paragraph">
<p>Let’s start with the worst case: we fail to handle an event, and the system is
left in an inconsistent state. What kind of error would cause this? Often in our
systems we can end up in an inconsistent state when only half an operation is
completed.</p>
</div>
<div class="paragraph">
<p>For example, we could allocate three units of <code>DESIRABLE_BEANBAG</code> to a customer’s
order but somehow fail to reduce the amount of remaining stock. This would
cause an inconsistent state: the three units of stock are both allocated <em>and</em>
available, depending on how you look at it. Later, we might allocate those
same beanbags to another customer, causing a headache for customer support.</p>
</div>
<div class="paragraph">
<p>
In our allocation service, though, we’ve already taken steps to prevent that
happening. We’ve carefully identified <em>aggregates</em> that act as consistency
boundaries, and we’ve introduced a <em>UoW</em> that manages the atomic
success or failure of an update to an aggregate.</p>
</div>
<div class="paragraph">
<p>
For example, when we allocate stock to an order, our consistency boundary is the
<code>Product</code> aggregate. This means that we can’t accidentally overallocate: either
a particular order line is allocated to the product, or it is not—​there’s no
room for inconsistent states.</p>
</div>
<div class="paragraph">
<p>By definition, we don’t require two aggregates to be immediately consistent, so
if we fail to process an event and update only a single aggregate, our system
can still be made eventually consistent. We shouldn’t violate any constraints of
the system.</p>
</div>
<div class="paragraph">
<p>With this example in mind, we can better understand the reason for splitting
messages into commands and events. When a user wants to make the system do
something, we represent their request as a <em>command</em>. That command should modify
a single <em>aggregate</em> and either succeed or fail in totality. Any other bookkeeping, cleanup, and notification we need to do can happen via an <em>event</em>. We
don’t require the event handlers to succeed in order for the command to be
successful.</p>
</div>
<div class="paragraph">
<p>Let’s look at another example (from a different, imaginary project) to see why not.</p>
</div>
<div class="paragraph">
<p>Imagine we are building an ecommerce website that sells expensive luxury goods.
Our marketing department wants to reward customers for repeat visits. We will
flag customers as VIPs after they make their third purchase, and this will
entitle them to priority treatment and special offers. Our acceptance criteria
for this story reads as follows:</p>
</div>
<div class="listingblock skip">
<div class="content">
<pre class="pygments highlight"><code data-lang="gherkin"><span></span><span class="tok-k">Given </span><span class="tok-nf">a customer with two orders in their history,</span>
<span class="tok-k">When </span><span class="tok-nf">the customer places a third order,</span>
<span class="tok-k">Then </span><span class="tok-nf">they should be flagged as a VIP.</span>
<span class="tok-k">When </span><span class="tok-nf">a customer first becomes a VIP</span>
<span class="tok-k">Then </span><span class="tok-nf">we should send them an email to congratulate them</span></code></pre>
</div>
</div>
<div class="paragraph">
<p>
Using the techniques we’ve already discussed in this book, we decide that we
want to build a new <code>History</code> aggregate that records orders and can raise domain
events when rules are met. We will structure the code like this:</p>
</div>
<div id="vip_customer_listing" class="exampleblock">
<div class="title">VIP customer (example code for a different project)</div>
<div class="content">
<div class="listingblock skip">
<div class="content">
<pre class="pygments highlight"><code data-lang="python"><span></span><span class="tok-k">class</span> <span class="tok-nc">History</span><span class="tok-p">:</span> <span class="tok-c1"># Aggregate</span>
<span class="tok-k">def</span> <span class="tok-fm">__init__</span><span class="tok-p">(</span><span class="tok-bp">self</span><span class="tok-p">,</span> <span class="tok-n">customer_id</span><span class="tok-p">:</span> <span class="tok-nb">int</span><span class="tok-p">):</span>
<span class="tok-bp">self</span><span class="tok-o">.</span><span class="tok-n">orders</span> <span class="tok-o">=</span> <span class="tok-nb">set</span><span class="tok-p">()</span> <span class="tok-c1"># Set[HistoryEntry]</span>
<span class="tok-bp">self</span><span class="tok-o">.</span><span class="tok-n">customer_id</span> <span class="tok-o">=</span> <span class="tok-n">customer_id</span>
<span class="tok-k">def</span> <span class="tok-nf">record_order</span><span class="tok-p">(</span><span class="tok-bp">self</span><span class="tok-p">,</span> <span class="tok-n">order_id</span><span class="tok-p">:</span> <span class="tok-nb">str</span><span class="tok-p">,</span> <span class="tok-n">order_amount</span><span class="tok-p">:</span> <span class="tok-nb">int</span><span class="tok-p">):</span> #<b class="conum">(1)</b>
<span class="tok-n">entry</span> <span class="tok-o">=</span> <span class="tok-n">HistoryEntry</span><span class="tok-p">(</span><span class="tok-n">order_id</span><span class="tok-p">,</span> <span class="tok-n">order_amount</span><span class="tok-p">)</span>
<span class="tok-k">if</span> <span class="tok-n">entry</span> <span class="tok-ow">in</span> <span class="tok-bp">self</span><span class="tok-o">.</span><span class="tok-n">orders</span><span class="tok-p">:</span>
<span class="tok-k">return</span>
<span class="tok-bp">self</span><span class="tok-o">.</span><span class="tok-n">orders</span><span class="tok-o">.</span><span class="tok-n">add</span><span class="tok-p">(</span><span class="tok-n">entry</span><span class="tok-p">)</span>
<span class="tok-k">if</span> <span class="tok-nb">len</span><span class="tok-p">(</span><span class="tok-bp">self</span><span class="tok-o">.</span><span class="tok-n">orders</span><span class="tok-p">)</span> <span class="tok-o">==</span> <span class="tok-mi">3</span><span class="tok-p">:</span>
<span class="tok-bp">self</span><span class="tok-o">.</span><span class="tok-n">events</span><span class="tok-o">.</span><span class="tok-n">append</span><span class="tok-p">(</span>
<span class="tok-n">CustomerBecameVIP</span><span class="tok-p">(</span><span class="tok-bp">self</span><span class="tok-o">.</span><span class="tok-n">customer_id</span><span class="tok-p">)</span>
<span class="tok-p">)</span>
<span class="tok-k">def</span> <span class="tok-nf">create_order_from_basket</span><span class="tok-p">(</span><span class="tok-n">uow</span><span class="tok-p">,</span> <span class="tok-n">cmd</span><span class="tok-p">:</span> <span class="tok-n">CreateOrder</span><span class="tok-p">):</span> #<b class="conum">(2)</b>
<span class="tok-k">with</span> <span class="tok-n">uow</span><span class="tok-p">:</span>
<span class="tok-n">order</span> <span class="tok-o">=</span> <span class="tok-n">Order</span><span class="tok-o">.</span><span class="tok-n">from_basket</span><span class="tok-p">(</span><span class="tok-n">cmd</span><span class="tok-o">.</span><span class="tok-n">customer_id</span><span class="tok-p">,</span> <span class="tok-n">cmd</span><span class="tok-o">.</span><span class="tok-n">basket_items</span><span class="tok-p">)</span>
<span class="tok-n">uow</span><span class="tok-o">.</span><span class="tok-n">orders</span><span class="tok-o">.</span><span class="tok-n">add</span><span class="tok-p">(</span><span class="tok-n">order</span><span class="tok-p">)</span>
<span class="tok-n">uow</span><span class="tok-o">.</span><span class="tok-n">commit</span><span class="tok-p">()</span> <span class="tok-c1"># raises OrderCreated</span>
<span class="tok-k">def</span> <span class="tok-nf">update_customer_history</span><span class="tok-p">(</span><span class="tok-n">uow</span><span class="tok-p">,</span> <span class="tok-n">event</span><span class="tok-p">:</span> <span class="tok-n">OrderCreated</span><span class="tok-p">):</span> #<b class="conum">(3)</b>
<span class="tok-k">with</span> <span class="tok-n">uow</span><span class="tok-p">:</span>
<span class="tok-n">history</span> <span class="tok-o">=</span> <span class="tok-n">uow</span><span class="tok-o">.</span><span class="tok-n">order_history</span><span class="tok-o">.</span><span class="tok-n">get</span><span class="tok-p">(</span><span class="tok-n">event</span><span class="tok-o">.</span><span class="tok-n">customer_id</span><span class="tok-p">)</span>
<span class="tok-n">history</span><span class="tok-o">.</span><span class="tok-n">record_order</span><span class="tok-p">(</span><span class="tok-n">event</span><span class="tok-o">.</span><span class="tok-n">order_id</span><span class="tok-p">,</span> <span class="tok-n">event</span><span class="tok-o">.</span><span class="tok-n">order_amount</span><span class="tok-p">)</span>
<span class="tok-n">uow</span><span class="tok-o">.</span><span class="tok-n">commit</span><span class="tok-p">()</span> <span class="tok-c1"># raises CustomerBecameVIP</span>
<span class="tok-k">def</span> <span class="tok-nf">congratulate_vip_customer</span><span class="tok-p">(</span><span class="tok-n">uow</span><span class="tok-p">,</span> <span class="tok-n">event</span><span class="tok-p">:</span> <span class="tok-n">CustomerBecameVip</span><span class="tok-p">):</span> #<b class="conum">(4)</b>
<span class="tok-k">with</span> <span class="tok-n">uow</span><span class="tok-p">:</span>
<span class="tok-n">customer</span> <span class="tok-o">=</span> <span class="tok-n">uow</span><span class="tok-o">.</span><span class="tok-n">customers</span><span class="tok-o">.</span><span class="tok-n">get</span><span class="tok-p">(</span><span class="tok-n">event</span><span class="tok-o">.</span><span class="tok-n">customer_id</span><span class="tok-p">)</span>
<span class="tok-n">email</span><span class="tok-o">.</span><span class="tok-n">send</span><span class="tok-p">(</span>
<span class="tok-n">customer</span><span class="tok-o">.</span><span class="tok-n">email_address</span><span class="tok-p">,</span>
<span class="tok-sa">f</span><span class="tok-s1">'Congratulations </span><span class="tok-si">{</span><span class="tok-n">customer</span><span class="tok-o">.</span><span class="tok-n">first_name</span><span class="tok-si">}</span><span class="tok-s1">!'</span>
<span class="tok-p">)</span></code></pre>
</div>
</div>
</div>
</div>
<div class="colist arabic">
<ol>
<li>
<p>The <code>History</code> aggregate captures the rules indicating when a customer becomes a VIP.
This puts us in a good place to handle changes when the rules become more
complex in the future.</p>
</li>
<li>
<p>Our first handler creates an order for the customer and raises a domain
event <code>OrderCreated</code>.</p>
</li>
<li>
<p>Our second handler updates the <code>History</code> object to record that an order was
<span class="keep-together">created</span>.</p>
</li>
<li>
<p>Finally, we send an email to the customer when they become a VIP.</p>
</li>
</ol>
</div>
<div class="paragraph">
<p>Using this code, we can gain some intuition about error handling in an
event-driven system.</p>
</div>
<div class="paragraph">
<p>
In our current implementation, we raise events about an aggregate <em>after</em> we
persist our state to the database. What if we raised those events <em>before</em> we
persisted, and committed all our changes at the same time? That way, we could be
sure that all the work was complete. Wouldn’t that be safer?</p>
</div>
<div class="paragraph">
<p>What happens, though, if the email server is slightly overloaded? If all the work
has to complete at the same time, a busy email server can stop us from taking money
for orders.</p>
</div>
<div class="paragraph">
<p>What happens if there is a bug in the implementation of the <code>History</code> aggregate?
Should we fail to take your money just because we can’t recognize you as a VIP?</p>
</div>
<div class="paragraph">
<p>By separating out these concerns, we have made it possible for things to fail
in isolation, which improves the overall reliability of the system. The only
part of this code that <em>has</em> to complete is the command handler that creates an
order. This is the only part that a customer cares about, and it’s the part that
our business stakeholders should prioritize.</p>
</div>
<div class="paragraph">
<p>
Notice how we’ve deliberately aligned our transactional boundaries to the start
and end of the business processes. The names that we use in the code match the
jargon used by our business stakeholders, and the handlers we’ve written match
the steps of our natural language acceptance criteria. This concordance of names
and structure helps us to reason about our systems as they grow larger and more
complex.</p>
</div>
</div>
<div class="sect2">
<h3 id="recovering_from_errors"><a class="anchor" href="#recovering_from_errors"></a>Recovering from Errors Synchronously</h3>
<div class="paragraph">
<p>
Hopefully we’ve convinced you that it’s OK for events to fail independently
from the commands that raised them. What should we do, then, to make sure we
can recover from errors when they inevitably occur?</p>
</div>
<div class="paragraph">
<p>The first thing we need is to know <em>when</em> an error has occurred, and for that we
usually rely on logs.</p>
</div>
<div class="paragraph">
<p>
Let’s look again at the <code>handle_event</code> method from our message bus:</p>
</div>
<div id="messagebus_logging" class="exampleblock">
<div class="title">Current handle function (src/allocation/service_layer/messagebus.py)</div>
<div class="content">
<div class="listingblock">
<div class="content">
<pre class="pygments highlight"><code data-lang="python"><span></span><span class="tok-k">def</span> <span class="tok-nf">handle_event</span><span class="tok-p">(</span>
<span class="tok-n">event</span><span class="tok-p">:</span> <span class="tok-n">events</span><span class="tok-o">.</span><span class="tok-n">Event</span><span class="tok-p">,</span>
<span class="tok-n">queue</span><span class="tok-p">:</span> <span class="tok-n">List</span><span class="tok-p">[</span><span class="tok-n">Message</span><span class="tok-p">],</span>
<span class="tok-n">uow</span><span class="tok-p">:</span> <span class="tok-n">unit_of_work</span><span class="tok-o">.</span><span class="tok-n">AbstractUnitOfWork</span><span class="tok-p">,</span>
<span class="tok-p">):</span>
<span class="tok-k">for</span> <span class="tok-n">handler</span> <span class="tok-ow">in</span> <span class="tok-n">EVENT_HANDLERS</span><span class="tok-p">[</span><span class="tok-nb">type</span><span class="tok-p">(</span><span class="tok-n">event</span><span class="tok-p">)]:</span>
<span class="tok-k">try</span><span class="tok-p">:</span>
<span class="hll"> <span class="tok-n">logger</span><span class="tok-o">.</span><span class="tok-n">debug</span><span class="tok-p">(</span><span class="tok-s2">"handling event </span><span class="tok-si">%s</span><span class="tok-s2"> with handler </span><span class="tok-si">%s</span><span class="tok-s2">"</span><span class="tok-p">,</span> <span class="tok-n">event</span><span class="tok-p">,</span> <span class="tok-n">handler</span><span class="tok-p">)</span>
</span> <span class="tok-n">handler</span><span class="tok-p">(</span><span class="tok-n">event</span><span class="tok-p">,</span> <span class="tok-n">uow</span><span class="tok-o">=</span><span class="tok-n">uow</span><span class="tok-p">)</span>
<span class="tok-n">queue</span><span class="tok-o">.</span><span class="tok-n">extend</span><span class="tok-p">(</span><span class="tok-n">uow</span><span class="tok-o">.</span><span class="tok-n">collect_new_events</span><span class="tok-p">())</span>
<span class="tok-k">except</span> <span class="tok-ne">Exception</span><span class="tok-p">:</span>
<span class="hll"> <span class="tok-n">logger</span><span class="tok-o">.</span><span class="tok-n">exception</span><span class="tok-p">(</span><span class="tok-s2">"Exception handling event </span><span class="tok-si">%s</span><span class="tok-s2">"</span><span class="tok-p">,</span> <span class="tok-n">event</span><span class="tok-p">)</span>
</span> <span class="tok-k">continue</span></code></pre>
</div>
</div>
</div>
</div>
<div class="paragraph">
<p>When we handle a message in our system, the first thing we do is write a log
line to record what we’re about to do. For our <code>CustomerBecameVIP</code> use case, the
logs might read as follows:</p>
</div>
<div class="listingblock">
<div class="content">
<pre>Handling event CustomerBecameVIP(customer_id=12345)
with handler <function congratulate_vip_customer at 0x10ebc9a60></pre>
</div>
</div>
<div class="paragraph">
<p>
Because we’ve chosen to use dataclasses for our message types, we get a neatly
printed summary of the incoming data that we can copy and paste into a Python
shell to re-create the object.</p>
</div>
<div class="paragraph">
<p>When an error occurs, we can use the logged data to either reproduce the problem
in a unit test or replay the message into the system.</p>
</div>
<div class="paragraph">
<p>Manual replay works well for cases where we need to fix a bug before we can
re-process an event, but our systems will <em>always</em> experience some background
level of transient failure. This includes things like network hiccups, table
deadlocks, and brief downtime caused by deployments.</p>
</div>
<div class="paragraph">
<p>
For most of those cases, we can recover elegantly by trying again. As the
proverb says, "If at first you don’t succeed, retry the operation with an
exponentially increasing back-off period."</p>
</div>
<div id="messagebus_handle_event_with_retry" class="exampleblock">
<div class="title">Handle with retry (src/allocation/service_layer/messagebus.py)</div>
<div class="content">
<div class="listingblock skip">
<div class="content">
<pre class="pygments highlight"><code data-lang="python"><span></span><span class="tok-kn">from</span> <span class="tok-nn">tenacity</span> <span class="tok-kn">import</span> <span class="tok-n">Retrying</span><span class="tok-p">,</span> <span class="tok-n">RetryError</span><span class="tok-p">,</span> <span class="tok-n">stop_after_attempt</span><span class="tok-p">,</span> <span class="tok-n">wait_exponential</span> #<b class="conum">(1)</b>
<span class="tok-o">...</span>
<span class="tok-k">def</span> <span class="tok-nf">handle_event</span><span class="tok-p">(</span>
<span class="tok-n">event</span><span class="tok-p">:</span> <span class="tok-n">events</span><span class="tok-o">.</span><span class="tok-n">Event</span><span class="tok-p">,</span>
<span class="tok-n">queue</span><span class="tok-p">:</span> <span class="tok-n">List</span><span class="tok-p">[</span><span class="tok-n">Message</span><span class="tok-p">],</span>
<span class="tok-n">uow</span><span class="tok-p">:</span> <span class="tok-n">unit_of_work</span><span class="tok-o">.</span><span class="tok-n">AbstractUnitOfWork</span><span class="tok-p">,</span>
<span class="tok-p">):</span>
<span class="tok-k">for</span> <span class="tok-n">handler</span> <span class="tok-ow">in</span> <span class="tok-n">EVENT_HANDLERS</span><span class="tok-p">[</span><span class="tok-nb">type</span><span class="tok-p">(</span><span class="tok-n">event</span><span class="tok-p">)]:</span>
<span class="tok-k">try</span><span class="tok-p">:</span>
<span class="tok-k">for</span> <span class="tok-n">attempt</span> <span class="tok-ow">in</span> <span class="tok-n">Retrying</span><span class="tok-p">(</span> #<b class="conum">(2)</b>
<span class="tok-n">stop</span><span class="tok-o">=</span><span class="tok-n">stop_after_attempt</span><span class="tok-p">(</span><span class="tok-mi">3</span><span class="tok-p">),</span>
<span class="tok-n">wait</span><span class="tok-o">=</span><span class="tok-n">wait_exponential</span><span class="tok-p">()</span>
<span class="tok-p">):</span>
<span class="tok-k">with</span> <span class="tok-n">attempt</span><span class="tok-p">:</span>
<span class="tok-n">logger</span><span class="tok-o">.</span><span class="tok-n">debug</span><span class="tok-p">(</span><span class="tok-s2">"handling event </span><span class="tok-si">%s</span><span class="tok-s2"> with handler </span><span class="tok-si">%s</span><span class="tok-s2">"</span><span class="tok-p">,</span> <span class="tok-n">event</span><span class="tok-p">,</span> <span class="tok-n">handler</span><span class="tok-p">)</span>
<span class="tok-n">handler</span><span class="tok-p">(</span><span class="tok-n">event</span><span class="tok-p">,</span> <span class="tok-n">uow</span><span class="tok-o">=</span><span class="tok-n">uow</span><span class="tok-p">)</span>
<span class="tok-n">queue</span><span class="tok-o">.</span><span class="tok-n">extend</span><span class="tok-p">(</span><span class="tok-n">uow</span><span class="tok-o">.</span><span class="tok-n">collect_new_events</span><span class="tok-p">())</span>
<span class="tok-k">except</span> <span class="tok-n">RetryError</span> <span class="tok-k">as</span> <span class="tok-n">retry_failure</span><span class="tok-p">:</span>
<span class="tok-n">logger</span><span class="tok-o">.</span><span class="tok-n">error</span><span class="tok-p">(</span>
<span class="tok-s2">"Failed to handle event </span><span class="tok-si">%s</span><span class="tok-s2"> times, giving up!"</span><span class="tok-p">,</span>
<span class="tok-n">retry_failure</span><span class="tok-o">.</span><span class="tok-n">last_attempt</span><span class="tok-o">.</span><span class="tok-n">attempt_number</span>
<span class="tok-p">)</span>
<span class="tok-k">continue</span></code></pre>
</div>
</div>
</div>
</div>
<div class="colist arabic">
<ol>
<li>
<p>Tenacity is a Python library that implements common patterns for retrying.
</p>
</li>
<li>
<p>Here we configure our message bus to retry operations up to three times,
with an exponentially increasing wait between attempts.</p>
</li>
</ol>
</div>
<div class="paragraph">
<p>Retrying operations that might fail is probably the single best way to improve
the resilience of our software. Again, the Unit of Work and Command Handler
patterns mean that each attempt starts from a consistent state and won’t leave
things half-finished.</p>
</div>
<div class="admonitionblock warning">
<table>
<tr>
<td class="icon">
<div class="title">Warning</div>
</td>
<td class="content">
At some point, regardless of <code>tenacity</code>, we’ll have to give up trying to
process the message. Building reliable systems with distributed messages is
hard, and we have to skim over some tricky bits. There are pointers to more
reference materials in the <a href="/book/epilogue_1_how_to_get_there_from_here.html">epilogue</a>.
</td>
</tr>
</table>
</div>
</div>
<div class="sect2 pagebreak-before less_space">
<h3 id="_wrap_up"><a class="anchor" href="#_wrap_up"></a>Wrap-Up</h3>
<div class="paragraph">
<p>
In this book we decided to introduce the concept of events before the concept
of commands, but other guides often do it the other way around. Making
explicit the requests that our system can respond to by giving them a name
and their own data structure is quite a fundamental thing to do. You’ll
sometimes see people use the name <em>Command Handler</em> pattern to describe what
we’re doing with Events, Commands, and Message Bus.</p>
</div>
<div class="paragraph">
<p><a href="#chapter_10_commands_and_events_tradeoffs">Splitting commands and events: the trade-offs</a> discusses some of the things you
should think about before you jump on board.</p>
</div>
<table id="chapter_10_commands_and_events_tradeoffs" class="tableblock frame-all grid-all stretch">
<caption class="title">Table 2. Splitting commands and events: the trade-offs</caption>
<colgroup>
<col style="width: 50%;">
<col style="width: 50%;">
</colgroup>
<thead>
<tr>
<th class="tableblock halign-left valign-top">Pros</th>
<th class="tableblock halign-left valign-top">Cons</th>
</tr>
</thead>
<tbody>
<tr>
<td class="tableblock halign-left valign-top"><div class="content"><div class="ulist">
<ul>
<li>
<p>Treating commands and events differently helps us understand which things
have to succeed and which things we can tidy up later.</p>
</li>
<li>
<p><code>CreateBatch</code> is definitely a less confusing name than <code>BatchCreated</code>. We are
being explicit about the intent of our users, and explicit is better than
implicit, right?</p>
</li>
</ul>
</div></div></td>
<td class="tableblock halign-left valign-top"><div class="content"><div class="ulist">
<ul>
<li>
<p>The semantic differences between commands and events can be subtle. Expect
bikeshedding arguments over the differences.</p>
</li>
<li>
<p>We’re expressly inviting failure. We know that sometimes things will break, and
we’re choosing to handle that by making the failures smaller and more isolated.
This can make the system harder to reason about and requires better monitoring.
</p>
</li>
</ul>
</div></div></td>
</tr>
</tbody>
</table>
<div class="paragraph">
<p>In <a href="/book/chapter_11_external_events.html">[chapter_11_external_events]</a> we’ll talk about using events as an integration pattern.</p>
</div>
</div>
</div>
</div>
<div class="prev_and_next_chapter_links">
<hr>
<a class="prev_chapter_link" href="/book/chapter_09_all_messagebus.html"><< Previous - 9: Going to Town on the Message Bus</a>
<a class="next_chapter_link" href="/book/chapter_11_external_events.html">Next - 11: Event-Driven Architecture: Using Events to Integrate Microservices >></a>
</div>
</div>
<div id="footer">
<div id="footer-text">
Last updated 2023-11-24 02:20:52 UTC
</div>
</div>
<div><div id="disqus_thread" style="margin: 10px"></div>
<script>
var disqus_config = function () {
this.page.url = 'https://www.cosmicpython.com/book/chapter_10_commands.html';
this.page.identifier = 'cosmic-python-chapter_10_commands';
};
(function() { // DON'T EDIT BELOW THIS LINE
var d = document, s = d.createElement('script');
s.src = 'https://cosmic-python.disqus.com/embed.js';
s.setAttribute('data-timestamp', +new Date());
(d.head || d.body).appendChild(s);
})();
</script>
<noscript>Please enable JavaScript to view the <a href="https://disqus.com/?ref_noscript">comments powered by Disqus.</a></noscript>
</div><html><head><script async src="https://www.googletagmanager.com/gtag/js?id=UA-40928035-3"></script>
<script>
window.dataLayer = window.dataLayer || [];
function gtag(){dataLayer.push(arguments);}
gtag('js', new Date());
gtag('config', 'UA-40928035-3');
</script>
</head></html></body>
</html>