-
Notifications
You must be signed in to change notification settings - Fork 8
/
Copy pathappendix_validation.html
862 lines (817 loc) · 51 KB
/
appendix_validation.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
<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>Validation</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="appendix_validation">Appendix E: Validation<a class="anchor" href="#appendix_validation"></a></h2>
<div class="sectionbody">
<div class="paragraph">
<p>
Whenever we’re teaching and talking about these techniques, one question that
comes up over and over is "Where should I do validation? Does that belong with
my business logic in the domain model, or is that an infrastructural concern?"</p>
</div>
<div class="paragraph">
<p>As with any architectural question, the answer is: it depends!</p>
</div>
<div class="paragraph">
<p>The most important consideration is that we want to keep our code well separated
so that each part of the system is simple. We don’t want to clutter our code
with irrelevant detail.</p>
</div>
<div class="sect2">
<h3 id="_what_is_validation_anyway"><a class="anchor" href="#_what_is_validation_anyway"></a>What Is Validation, Anyway?</h3>
<div class="paragraph">
<p>When people use the word <em>validation</em>, they usually mean a process whereby they
test the inputs of an operation to make sure that they match certain criteria.
Inputs that match the criteria are considered <em>valid</em>, and inputs that don’t
are <em>invalid</em>.</p>
</div>
<div class="paragraph">
<p>If the input is invalid, the operation can’t continue but should exit with
some kind of error. In other words, validation is about creating <em>preconditions</em>. We find it useful
to separate our preconditions into three subtypes: syntax, semantics, and
pragmatics.</p>
</div>
</div>
<div class="sect2">
<h3 id="_validating_syntax"><a class="anchor" href="#_validating_syntax"></a>Validating Syntax</h3>
<div class="paragraph">
<p>In linguistics, the <em>syntax</em> of a language is the set of rules that govern the
structure of grammatical sentences. For example, in English, the sentence
"Allocate three units of <code>TASTELESS-LAMP</code> to order twenty-seven" is grammatically
sound, while the phrase "hat hat hat hat hat hat wibble" is not. We can describe
grammatically correct sentences as <em>well formed</em>.</p>
</div>
<div class="paragraph pagebreak-before">
<p>How does this map to our application? Here are some examples of syntactic rules:</p>
</div>
<div class="ulist">
<ul>
<li>
<p>An <code>Allocate</code> command must have an order ID, a SKU, and a quantity.</p>
</li>
<li>
<p>A quantity is a positive integer.</p>
</li>
<li>
<p>A SKU is a string.</p>
</li>
</ul>
</div>
<div class="paragraph">
<p>These are rules about the shape and structure of incoming data. An <code>Allocate</code>
command without a SKU or an order ID isn’t a valid message. It’s the equivalent
of the phrase "Allocate three to."</p>
</div>
<div class="paragraph">
<p>We tend to validate these rules at the edge of the system. Our rule of thumb is
that a message handler should always receive only a message that is well-formed
and contains all required information.</p>
</div>
<div class="paragraph">
<p>One option is to put your validation logic on the message type itself:</p>
</div>
<div id="validation_on_message" class="exampleblock">
<div class="title">Validation on the message class (src/allocation/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-kn">from</span> <span class="tok-nn">schema</span> <span class="tok-kn">import</span> <span class="tok-n">And</span><span class="tok-p">,</span> <span class="tok-n">Schema</span><span class="tok-p">,</span> <span class="tok-n">Use</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>
<span class="tok-n">_schema</span> <span class="tok-o">=</span> <span class="tok-n">Schema</span><span class="tok-p">({</span> #<b class="conum">(1)</b>
<span class="tok-s1">'orderid'</span><span class="tok-p">:</span> <span class="tok-nb">str</span><span class="tok-p">,</span>
<span class="tok-s1">'sku'</span><span class="tok-p">:</span> <span class="tok-nb">str</span><span class="tok-p">,</span>
<span class="tok-s1">'qty'</span><span class="tok-p">:</span> <span class="tok-n">And</span><span class="tok-p">(</span><span class="tok-n">Use</span><span class="tok-p">(</span><span class="tok-nb">int</span><span class="tok-p">),</span> <span class="tok-k">lambda</span> <span class="tok-n">n</span><span class="tok-p">:</span> <span class="tok-n">n</span> <span class="tok-o">></span> <span class="tok-mi">0</span><span class="tok-p">)</span>
<span class="tok-p">},</span> <span class="tok-n">ignore_extra_keys</span><span class="tok-o">=</span><span class="tok-kc">True</span><span class="tok-p">)</span>
<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">@classmethod</span>
<span class="tok-k">def</span> <span class="tok-nf">from_json</span><span class="tok-p">(</span><span class="tok-bp">cls</span><span class="tok-p">,</span> <span class="tok-n">data</span><span class="tok-p">):</span> #<b class="conum">(2)</b>
<span class="tok-n">data</span> <span class="tok-o">=</span> <span class="tok-n">json</span><span class="tok-o">.</span><span class="tok-n">loads</span><span class="tok-p">(</span><span class="tok-n">data</span><span class="tok-p">)</span>
<span class="tok-k">return</span> <span class="tok-bp">cls</span><span class="tok-p">(</span><span class="tok-o">**</span><span class="tok-n">_schema</span><span class="tok-o">.</span><span class="tok-n">validate</span><span class="tok-p">(</span><span class="tok-n">data</span><span class="tok-p">))</span></code></pre>
</div>
</div>
</div>
</div>
<div class="colist arabic">
<ol>
<li>
<p>The <a href="https://pypi.org/project/schema">schema library</a> lets us
describe the structure and validation of our messages in a nice declarative way.</p>
</li>
<li>
<p>The <code>from_json</code> method reads a string as JSON and turns it into our message
type.</p>
</li>
</ol>
</div>
<div class="paragraph">
<p>This can get repetitive, though, since we need to specify our fields twice,
so we might want to introduce a helper library that can unify the validation and
declaration of our message types:</p>
</div>
<div id="command_factory" class="exampleblock">
<div class="title">A command factory with schema (src/allocation/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">def</span> <span class="tok-nf">command</span><span class="tok-p">(</span><span class="tok-n">name</span><span class="tok-p">,</span> <span class="tok-o">**</span><span class="tok-n">fields</span><span class="tok-p">):</span> #<b class="conum">(1)</b>
<span class="tok-n">schema</span> <span class="tok-o">=</span> <span class="tok-n">Schema</span><span class="tok-p">(</span><span class="tok-n">And</span><span class="tok-p">(</span><span class="tok-n">Use</span><span class="tok-p">(</span><span class="tok-n">json</span><span class="tok-o">.</span><span class="tok-n">loads</span><span class="tok-p">),</span> <span class="tok-n">fields</span><span class="tok-p">),</span> <span class="tok-n">ignore_extra_keys</span><span class="tok-o">=</span><span class="tok-kc">True</span><span class="tok-p">)</span>
<span class="tok-bp">cls</span> <span class="tok-o">=</span> <span class="tok-n">make_dataclass</span><span class="tok-p">(</span><span class="tok-n">name</span><span class="tok-p">,</span> <span class="tok-n">fields</span><span class="tok-o">.</span><span class="tok-n">keys</span><span class="tok-p">())</span> #<b class="conum">(2)</b>
<span class="tok-bp">cls</span><span class="tok-o">.</span><span class="tok-n">from_json</span> <span class="tok-o">=</span> <span class="tok-k">lambda</span> <span class="tok-n">s</span><span class="tok-p">:</span> <span class="tok-bp">cls</span><span class="tok-p">(</span><span class="tok-o">**</span><span class="tok-n">schema</span><span class="tok-o">.</span><span class="tok-n">validate</span><span class="tok-p">(</span><span class="tok-n">s</span><span class="tok-p">))</span> #<b class="conum">(3)</b>
<span class="tok-k">return</span> <span class="tok-bp">cls</span>
<span class="tok-k">def</span> <span class="tok-nf">greater_than_zero</span><span class="tok-p">(</span><span class="tok-n">x</span><span class="tok-p">):</span>
<span class="tok-k">return</span> <span class="tok-n">x</span> <span class="tok-o">></span> <span class="tok-mi">0</span>
<span class="tok-n">quantity</span> <span class="tok-o">=</span> <span class="tok-n">And</span><span class="tok-p">(</span><span class="tok-n">Use</span><span class="tok-p">(</span><span class="tok-nb">int</span><span class="tok-p">),</span> <span class="tok-n">greater_than_zero</span><span class="tok-p">)</span> #<b class="conum">(4)</b>
<span class="tok-n">Allocate</span> <span class="tok-o">=</span> <span class="tok-n">command</span><span class="tok-p">(</span> #<b class="conum">(5)</b>
<span class="tok-s1">'Allocate'</span><span class="tok-p">,</span>
<span class="tok-n">orderid</span><span class="tok-o">=</span><span class="tok-nb">int</span><span class="tok-p">,</span>
<span class="tok-n">sku</span><span class="tok-o">=</span><span class="tok-nb">str</span><span class="tok-p">,</span>
<span class="tok-n">qty</span><span class="tok-o">=</span><span class="tok-n">quantity</span>
<span class="tok-p">)</span>
<span class="tok-n">AddStock</span> <span class="tok-o">=</span> <span class="tok-n">command</span><span class="tok-p">(</span>
<span class="tok-s1">'AddStock'</span><span class="tok-p">,</span>
<span class="tok-n">sku</span><span class="tok-o">=</span><span class="tok-nb">str</span><span class="tok-p">,</span>
<span class="tok-n">qty</span><span class="tok-o">=</span><span class="tok-n">quantity</span></code></pre>
</div>
</div>
</div>
</div>
<div class="colist arabic">
<ol>
<li>
<p>The <code>command</code> function takes a message name, plus kwargs for the fields of
the message payload, where the name of the kwarg is the name of the field and
the value is the parser.</p>
</li>
<li>
<p>We use the <code>make_dataclass</code> function from the dataclass module to dynamically
create our message type.</p>
</li>
<li>
<p>We patch the <code>from_json</code> method onto our dynamic dataclass.</p>
</li>
<li>
<p>We can create reusable parsers for quantity, SKU, and so on to keep things DRY.</p>
</li>
<li>
<p>Declaring a message type becomes a one-liner.</p>
</li>
</ol>
</div>
<div class="paragraph">
<p>This comes at the expense of losing the types on your dataclass, so bear that
trade-off in mind.</p>
</div>
</div>
<div class="sect2">
<h3 id="_postels_law_and_the_tolerant_reader_pattern"><a class="anchor" href="#_postels_law_and_the_tolerant_reader_pattern"></a>Postel’s Law and the Tolerant Reader Pattern</h3>
<div class="paragraph">
<p><em>Postel’s law</em>, or the <em>robustness principle</em>, tells us, "Be liberal in what you
accept, and conservative in what you emit." We think this applies particularly
well in the context of integration with our other systems. The idea here is
that we should be strict whenever we’re sending messages to other systems, but
as lenient as possible when we’re receiving messages from others.</p>
</div>
<div class="paragraph">
<p>For example, our system <em>could</em> validate the format of a SKU. We’ve been using
made-up SKUs like <code>UNFORGIVING-CUSHION</code> and <code>MISBEGOTTEN-POUFFE</code>. These follow
a simple pattern: two words, separated by dashes, where the second word is the
type of product and the first word is an adjective.</p>
</div>
<div class="paragraph">
<p>Developers <em>love</em> to validate this kind of thing in their messages, and reject
anything that looks like an invalid SKU. This causes horrible problems down the
line when some anarchist releases a product named <code>COMFY-CHAISE-LONGUE</code> or when
a snafu at the supplier results in a shipment of <code>CHEAP-CARPET-2</code>.</p>
</div>
<div class="paragraph">
<p>Really, as the allocation system, it’s <em>none of our business</em> what the format of
a SKU might be. All we need is an identifier, so we can simply describe it as a
string. This means that the procurement system can change the format whenever
they like, and we won’t care.</p>
</div>
<div class="paragraph">
<p>This same principle applies to order numbers, customer phone numbers, and much
more. For the most part, we can ignore the internal structure of strings.</p>
</div>
<div class="paragraph">
<p>Similarly, developers <em>love</em> to validate incoming messages with tools like JSON
Schema, or to build libraries that validate incoming messages and share them
among systems. This likewise fails the robustness test.</p>
</div>
<div class="paragraph">
<p>Let’s imagine, for example, that the procurement system adds new fields to the
<code>ChangeBatchQuantity</code> message that record the reason for the change and the
email of the user responsible for the change.</p>
</div>
<div class="paragraph">
<p>Since these fields don’t matter to the allocation service, we should simply
ignore them. We can do that in the <code>schema</code> library by passing the keyword arg
<code>ignore_extra_keys=True</code>.</p>
</div>
<div class="paragraph">
<p>This pattern, whereby we extract only the fields we care about and do minimal
validation of them, is the Tolerant Reader pattern.</p>
</div>
<div class="admonitionblock tip">
<table>
<tr>
<td class="icon">
<div class="title">Tip</div>
</td>
<td class="content">
Validate as little as possible. Read only the fields you need, and don’t
overspecify their contents. This will help your system stay robust when other
systems change over time. Resist the temptation to share message
definitions between systems: instead, make it easy to define the data you
depend on. For more info, see Martin Fowler’s article on the
<a href="https://oreil.ly/YL_La">Tolerant Reader pattern</a>.
</td>
</tr>
</table>
</div>
<div class="sidebarblock pagebreak-before less_space">
<div class="content">
<div class="title">Is Postel Always Right?</div>
<div class="paragraph">
<p>Mentioning Postel can be quite triggering to some people. They will
<a href="https://oreil.ly/bzLmb">tell you</a>
that Postel is the precise reason that everything on the internet is broken and
we can’t have nice things. Ask Hynek about SSLv3 one day.</p>
</div>
<div class="paragraph">
<p>We like the Tolerant Reader approach in the particular context of event-based
integration between services that we control, because it allows for independent
evolution of those services.</p>
</div>
<div class="paragraph">
<p>If you’re in charge of an API that’s open to the public on the big bad
internet, there might be good reasons to be more conservative about what
inputs you allow.</p>
</div>
</div>
</div>
</div>
<div class="sect2">
<h3 id="_validating_at_the_edge"><a class="anchor" href="#_validating_at_the_edge"></a>Validating at the Edge</h3>
<div class="paragraph">
<p>Earlier, we said that we want to avoid cluttering our code with irrelevant
details. In particular, we don’t want to code defensively inside our domain model.
Instead, we want to make sure that requests are known to be valid before our
domain model or use-case handlers see them. This helps our code stay clean
and maintainable over the long term. We sometimes refer to this as <em>validating
at the edge of the system</em>.</p>
</div>
<div class="paragraph">
<p>In addition to keeping your code clean and free of endless checks and asserts,
bear in mind that invalid data wandering through your system is a time bomb;
the deeper it gets, the more damage it can do, and the fewer tools
you have to respond to it.</p>
</div>
<div class="paragraph">
<p>Back in <a href="/book/chapter_08_events_and_message_bus.html">[chapter_08_events_and_message_bus]</a>, we said that the message bus was a great place to put
cross-cutting concerns, and validation is a perfect example of that. Here’s how
we might change our bus to perform validation for us:</p>
</div>
<div id="validation_on_bus" class="exampleblock">
<div class="title">Validation</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">MessageBus</span><span class="tok-p">:</span>
<span class="tok-k">def</span> <span class="tok-nf">handle_message</span><span class="tok-p">(</span><span class="tok-bp">self</span><span class="tok-p">,</span> <span class="tok-n">name</span><span class="tok-p">:</span> <span class="tok-nb">str</span><span class="tok-p">,</span> <span class="tok-n">body</span><span class="tok-p">:</span> <span class="tok-nb">str</span><span class="tok-p">):</span>
<span class="tok-k">try</span><span class="tok-p">:</span>
<span class="tok-n">message_type</span> <span class="tok-o">=</span> <span class="tok-nb">next</span><span class="tok-p">(</span><span class="tok-n">mt</span> <span class="tok-k">for</span> <span class="tok-n">mt</span> <span class="tok-ow">in</span> <span class="tok-n">EVENT_HANDLERS</span> <span class="tok-k">if</span> <span class="tok-n">mt</span><span class="tok-o">.</span><span class="tok-vm">__name__</span> <span class="tok-o">==</span> <span class="tok-n">name</span><span class="tok-p">)</span>
<span class="tok-n">message</span> <span class="tok-o">=</span> <span class="tok-n">message_type</span><span class="tok-o">.</span><span class="tok-n">from_json</span><span class="tok-p">(</span><span class="tok-n">body</span><span class="tok-p">)</span>
<span class="tok-bp">self</span><span class="tok-o">.</span><span class="tok-n">handle</span><span class="tok-p">([</span><span class="tok-n">message</span><span class="tok-p">])</span>
<span class="tok-k">except</span> <span class="tok-ne">StopIteration</span><span class="tok-p">:</span>
<span class="tok-k">raise</span> <span class="tok-ne">KeyError</span><span class="tok-p">(</span><span class="tok-sa">f</span><span class="tok-s2">"Unknown message name </span><span class="tok-si">{</span><span class="tok-n">name</span><span class="tok-si">}</span><span class="tok-s2">"</span><span class="tok-p">)</span>
<span class="tok-k">except</span> <span class="tok-n">ValidationError</span> <span class="tok-k">as</span> <span class="tok-n">e</span><span class="tok-p">:</span>
<span class="tok-n">logging</span><span class="tok-o">.</span><span class="tok-n">error</span><span class="tok-p">(</span>
<span class="tok-sa">f</span><span class="tok-s1">'invalid message of type </span><span class="tok-si">{</span><span class="tok-n">name</span><span class="tok-si">}</span><span class="tok-se">\n</span><span class="tok-s1">'</span>
<span class="tok-sa">f</span><span class="tok-s1">'</span><span class="tok-si">{</span><span class="tok-n">body</span><span class="tok-si">}</span><span class="tok-se">\n</span><span class="tok-s1">'</span>
<span class="tok-sa">f</span><span class="tok-s1">'</span><span class="tok-si">{</span><span class="tok-n">e</span><span class="tok-si">}</span><span class="tok-s1">'</span>
<span class="tok-p">)</span>
<span class="tok-k">raise</span> <span class="tok-n">e</span></code></pre>
</div>
</div>
</div>
</div>
<div class="paragraph">
<p>Here’s how we might use that method from our Flask API endpoint:</p>
</div>
<div id="validation_bubbles_up" class="exampleblock">
<div class="title">API bubbles up validation errors (src/allocation/flask_app.py)</div>
<div class="content">
<div class="listingblock">
<div class="content">
<pre class="pygments highlight"><code data-lang="python"><span></span><span class="tok-nd">@app</span><span class="tok-o">.</span><span class="tok-n">route</span><span class="tok-p">(</span><span class="tok-s2">"/change_quantity"</span><span class="tok-p">,</span> <span class="tok-n">methods</span><span class="tok-o">=</span><span class="tok-p">[</span><span class="tok-s1">'POST'</span><span class="tok-p">])</span>
<span class="tok-k">def</span> <span class="tok-nf">change_batch_quantity</span><span class="tok-p">():</span>
<span class="tok-k">try</span><span class="tok-p">:</span>
<span class="tok-n">bus</span><span class="tok-o">.</span><span class="tok-n">handle_message</span><span class="tok-p">(</span><span class="tok-s1">'ChangeBatchQuantity'</span><span class="tok-p">,</span> <span class="tok-n">request</span><span class="tok-o">.</span><span class="tok-n">body</span><span class="tok-p">)</span>
<span class="tok-k">except</span> <span class="tok-n">ValidationError</span> <span class="tok-k">as</span> <span class="tok-n">e</span><span class="tok-p">:</span>
<span class="tok-k">return</span> <span class="tok-n">bad_request</span><span class="tok-p">(</span><span class="tok-n">e</span><span class="tok-p">)</span>
<span class="tok-k">except</span> <span class="tok-n">exceptions</span><span class="tok-o">.</span><span class="tok-n">InvalidSku</span> <span class="tok-k">as</span> <span class="tok-n">e</span><span class="tok-p">:</span>
<span class="tok-k">return</span> <span class="tok-n">jsonify</span><span class="tok-p">({</span><span class="tok-s1">'message'</span><span class="tok-p">:</span> <span class="tok-nb">str</span><span class="tok-p">(</span><span class="tok-n">e</span><span class="tok-p">)}),</span> <span class="tok-mi">400</span>
<span class="tok-k">def</span> <span class="tok-nf">bad_request</span><span class="tok-p">(</span><span class="tok-n">e</span><span class="tok-p">:</span> <span class="tok-n">ValidationError</span><span class="tok-p">):</span>
<span class="tok-k">return</span> <span class="tok-n">e</span><span class="tok-o">.</span><span class="tok-n">code</span><span class="tok-p">,</span> <span class="tok-mi">400</span></code></pre>
</div>
</div>
</div>
</div>
<div class="paragraph">
<p>And here’s how we might plug it in to our asynchronous message processor:</p>
</div>
<div id="validation_pubsub" class="exampleblock">
<div class="title">Validation errors when handling Redis messages (src/allocation/redis_pubsub.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_change_batch_quantity</span><span class="tok-p">(</span><span class="tok-n">m</span><span class="tok-p">,</span> <span class="tok-n">bus</span><span class="tok-p">:</span> <span class="tok-n">messagebus</span><span class="tok-o">.</span><span class="tok-n">MessageBus</span><span class="tok-p">):</span>
<span class="tok-k">try</span><span class="tok-p">:</span>
<span class="tok-n">bus</span><span class="tok-o">.</span><span class="tok-n">handle_message</span><span class="tok-p">(</span><span class="tok-s1">'ChangeBatchQuantity'</span><span class="tok-p">,</span> <span class="tok-n">m</span><span class="tok-p">)</span>
<span class="tok-k">except</span> <span class="tok-n">ValidationError</span><span class="tok-p">:</span>
<span class="tok-nb">print</span><span class="tok-p">(</span><span class="tok-s1">'Skipping invalid message'</span><span class="tok-p">)</span>
<span class="tok-k">except</span> <span class="tok-n">exceptions</span><span class="tok-o">.</span><span class="tok-n">InvalidSku</span> <span class="tok-k">as</span> <span class="tok-n">e</span><span class="tok-p">:</span>
<span class="tok-nb">print</span><span class="tok-p">(</span><span class="tok-sa">f</span><span class="tok-s1">'Unable to change stock for missing sku </span><span class="tok-si">{</span><span class="tok-n">e</span><span class="tok-si">}</span><span class="tok-s1">'</span><span class="tok-p">)</span></code></pre>
</div>
</div>
</div>
</div>
<div class="paragraph">
<p>Notice that our entrypoints are solely concerned with how to get a message from
the outside world and how to report success or failure. Our message bus takes
care of validating our requests and routing them to the correct handler, and
our handlers are exclusively focused on the logic of our use case.</p>
</div>
<div class="admonitionblock tip">
<table>
<tr>
<td class="icon">
<div class="title">Tip</div>
</td>
<td class="content">
When you receive an invalid message, there’s usually little you can do but
log the error and continue. At MADE we use metrics to count the number of
messages a system receives, and how many of those are successfully
processed, skipped, or invalid. Our monitoring tools will alert us if we
see spikes in the numbers of bad messages.
</td>
</tr>
</table>
</div>
</div>
<div class="sect2">
<h3 id="_validating_semantics"><a class="anchor" href="#_validating_semantics"></a>Validating Semantics</h3>
<div class="paragraph">
<p>While syntax is concerned with the structure of messages, <em>semantics</em> is the study
of <em>meaning</em> in messages. The sentence "Undo no dogs from ellipsis four" is
syntactically valid and has the same structure as the sentence "Allocate one
teapot to order five,"" but it is meaningless.</p>
</div>
<div class="paragraph">
<p>We can read this JSON blob as an <code>Allocate</code> command but can’t successfully
execute it, because it’s <em>nonsense</em>:</p>
</div>
<div id="invalid_order" class="exampleblock">
<div class="title">A meaningless message</div>
<div class="content">
<div class="listingblock">
<div class="content">
<pre class="pygments highlight"><code data-lang="python"><span></span><span class="tok-p">{</span>
<span class="tok-s2">"orderid"</span><span class="tok-p">:</span> <span class="tok-s2">"superman"</span><span class="tok-p">,</span>
<span class="tok-s2">"sku"</span><span class="tok-p">:</span> <span class="tok-s2">"zygote"</span><span class="tok-p">,</span>
<span class="tok-s2">"qty"</span><span class="tok-p">:</span> <span class="tok-o">-</span><span class="tok-mi">1</span>
<span class="tok-p">}</span></code></pre>
</div>
</div>
</div>
</div>
<div class="paragraph">
<p>We tend to validate semantic concerns at the message-handler layer with a kind
of contract-based programming:</p>
</div>
<div id="ensure_dot_py" class="exampleblock">
<div class="title">Preconditions (src/allocation/ensure.py)</div>
<div class="content">
<div class="listingblock">
<div class="content">
<pre class="pygments highlight"><code data-lang="python"><span></span><span class="tok-sd">"""</span>
<span class="tok-sd">This module contains preconditions that we apply to our handlers.</span>
<span class="tok-sd">"""</span>
<span class="tok-k">class</span> <span class="tok-nc">MessageUnprocessable</span><span class="tok-p">(</span><span class="tok-ne">Exception</span><span class="tok-p">):</span> #<b class="conum">(1)</b>
<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">message</span><span class="tok-p">):</span>
<span class="tok-bp">self</span><span class="tok-o">.</span><span class="tok-n">message</span> <span class="tok-o">=</span> <span class="tok-n">message</span>
<span class="tok-k">class</span> <span class="tok-nc">ProductNotFound</span><span class="tok-p">(</span><span class="tok-n">MessageUnprocessable</span><span class="tok-p">):</span> #<b class="conum">(2)</b>
<span class="tok-w"> </span><span class="tok-sd">""""</span>
<span class="tok-sd"> This exception is raised when we try to perform an action on a product</span>
<span class="tok-sd"> that doesn't exist in our database.</span>
<span class="tok-sd"> """</span><span class="tok-s2">"</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">message</span><span class="tok-p">):</span>
<span class="tok-nb">super</span><span class="tok-p">()</span><span class="tok-o">.</span><span class="tok-fm">__init__</span><span class="tok-p">(</span><span class="tok-n">message</span><span class="tok-p">)</span>
<span class="tok-bp">self</span><span class="tok-o">.</span><span class="tok-n">sku</span> <span class="tok-o">=</span> <span class="tok-n">message</span><span class="tok-o">.</span><span class="tok-n">sku</span>
<span class="tok-k">def</span> <span class="tok-nf">product_exists</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-p">):</span> #<b class="conum">(3)</b>
<span class="tok-n">product</span> <span class="tok-o">=</span> <span class="tok-n">uow</span><span class="tok-o">.</span><span class="tok-n">products</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">sku</span><span class="tok-p">)</span>
<span class="tok-k">if</span> <span class="tok-n">product</span> <span class="tok-ow">is</span> <span class="tok-kc">None</span><span class="tok-p">:</span>
<span class="tok-k">raise</span> <span class="tok-n">ProductNotFound</span><span class="tok-p">(</span><span class="tok-n">event</span><span class="tok-p">)</span></code></pre>
</div>
</div>
</div>
</div>
<div class="colist arabic">
<ol>
<li>
<p>We use a common base class for errors that mean a message is invalid.</p>
</li>
<li>
<p>Using a specific error type for this problem makes it easier to report on
and handle the error. For example, it’s easy to map <code>ProductNotFound</code> to a 404
in Flask.</p>
</li>
<li>
<p><code>product_exists</code> is a precondition. If the condition is <code>False</code>, we raise an
error.</p>
</li>
</ol>
</div>
<div class="paragraph">
<p>This keeps the main flow of our logic in the service layer clean and declarative:</p>
</div>
<div id="ensure_in_services" class="exampleblock">
<div class="title">Ensure calls in services (src/allocation/services.py)</div>
<div class="content">
<div class="listingblock">
<div class="content">
<pre class="pygments highlight"><code data-lang="python"><span></span><span class="tok-c1"># services.py</span>
<span class="tok-kn">from</span> <span class="tok-nn">allocation</span> <span class="tok-kn">import</span> <span class="tok-n">ensure</span>
<span class="tok-k">def</span> <span class="tok-nf">allocate</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-p">):</span>
<span class="tok-n">line</span> <span class="tok-o">=</span> <span class="tok-n">model</span><span class="tok-o">.</span><span class="tok-n">OrderLine</span><span class="tok-p">(</span><span class="tok-n">event</span><span class="tok-o">.</span><span class="tok-n">orderid</span><span class="tok-p">,</span> <span class="tok-n">event</span><span class="tok-o">.</span><span class="tok-n">sku</span><span class="tok-p">,</span> <span class="tok-n">event</span><span class="tok-o">.</span><span class="tok-n">qty</span><span class="tok-p">)</span>
<span class="tok-k">with</span> <span class="tok-n">uow</span><span class="tok-p">:</span>
<span class="hll"> <span class="tok-n">ensure</span><span class="tok-o">.</span><span class="tok-n">product_exists</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-p">)</span>
</span>
<span class="tok-n">product</span> <span class="tok-o">=</span> <span class="tok-n">uow</span><span class="tok-o">.</span><span class="tok-n">products</span><span class="tok-o">.</span><span class="tok-n">get</span><span class="tok-p">(</span><span class="tok-n">line</span><span class="tok-o">.</span><span class="tok-n">sku</span><span class="tok-p">)</span>
<span class="tok-n">product</span><span class="tok-o">.</span><span class="tok-n">allocate</span><span class="tok-p">(</span><span class="tok-n">line</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></code></pre>
</div>
</div>
</div>
</div>
<div class="paragraph">
<p>We can extend this technique to make sure that we apply messages idempotently.
For example, we want to make sure that we don’t insert a batch of stock more
than once.</p>
</div>
<div class="paragraph">
<p>If we get asked to create a batch that already exists, we’ll log a warning and
continue to the next message:</p>
</div>
<div id="skipmessage" class="exampleblock">
<div class="title">Raise SkipMessage exception for ignorable events (src/allocation/services.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">SkipMessage</span> <span class="tok-p">(</span><span class="tok-ne">Exception</span><span class="tok-p">):</span>
<span class="tok-w"> </span><span class="tok-sd">""""</span>
<span class="tok-sd"> This exception is raised when a message can't be processed, but there's no</span>
<span class="tok-sd"> incorrect behavior. For example, we might receive the same message multiple</span>
<span class="tok-sd"> times, or we might receive a message that is now out of date.</span>
<span class="tok-sd"> """</span><span class="tok-s2">"</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">reason</span><span class="tok-p">):</span>
<span class="tok-bp">self</span><span class="tok-o">.</span><span class="tok-n">reason</span> <span class="tok-o">=</span> <span class="tok-n">reason</span>
<span class="tok-k">def</span> <span class="tok-nf">batch_is_new</span><span class="tok-p">(</span><span class="tok-bp">self</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-p">):</span>
<span class="tok-n">batch</span> <span class="tok-o">=</span> <span class="tok-n">uow</span><span class="tok-o">.</span><span class="tok-n">batches</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">batchid</span><span class="tok-p">)</span>
<span class="tok-k">if</span> <span class="tok-n">batch</span> <span class="tok-ow">is</span> <span class="tok-ow">not</span> <span class="tok-kc">None</span><span class="tok-p">:</span>
<span class="tok-k">raise</span> <span class="tok-n">SkipMessage</span><span class="tok-p">(</span><span class="tok-sa">f</span><span class="tok-s2">"Batch with id </span><span class="tok-si">{</span><span class="tok-n">event</span><span class="tok-o">.</span><span class="tok-n">batchid</span><span class="tok-si">}</span><span class="tok-s2"> already exists"</span><span class="tok-p">)</span></code></pre>
</div>
</div>
</div>
</div>
<div class="paragraph">
<p>Introducing a <code>SkipMessage</code> exception lets us handle these cases in a generic
way in our message bus:</p>
</div>
<div id="skip_in_bus" class="exampleblock">
<div class="title">The bus now knows how to skip (src/allocation/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">class</span> <span class="tok-nc">MessageBus</span><span class="tok-p">:</span>
<span class="tok-k">def</span> <span class="tok-nf">handle_message</span><span class="tok-p">(</span><span class="tok-bp">self</span><span class="tok-p">,</span> <span class="tok-n">message</span><span class="tok-p">):</span>
<span class="tok-k">try</span><span class="tok-p">:</span>
<span class="tok-o">...</span>
<span class="tok-k">except</span> <span class="tok-n">SkipMessage</span> <span class="tok-k">as</span> <span class="tok-n">e</span><span class="tok-p">:</span>
<span class="tok-n">logging</span><span class="tok-o">.</span><span class="tok-n">warn</span><span class="tok-p">(</span><span class="tok-sa">f</span><span class="tok-s2">"Skipping message </span><span class="tok-si">{</span><span class="tok-n">message</span><span class="tok-o">.</span><span class="tok-n">id</span><span class="tok-si">}</span><span class="tok-s2"> because </span><span class="tok-si">{</span><span class="tok-n">e</span><span class="tok-o">.</span><span class="tok-n">reason</span><span class="tok-si">}</span><span class="tok-s2">"</span><span class="tok-p">)</span></code></pre>
</div>
</div>
</div>
</div>
<div class="paragraph">
<p>There are a couple of pitfalls to be aware of here. First, we need to be sure
that we’re using the same UoW that we use for the main logic of our
use case. Otherwise, we open ourselves to irritating concurrency bugs.</p>
</div>
<div class="paragraph">
<p>Second, we should try to avoid putting <em>all</em> our business logic into these
precondition checks. As a rule of thumb, if a rule <em>can</em> be tested inside our
domain model, then it <em>should</em> be tested in the domain model.</p>
</div>
</div>
<div class="sect2">
<h3 id="_validating_pragmatics"><a class="anchor" href="#_validating_pragmatics"></a>Validating Pragmatics</h3>
<div class="paragraph">
<p><em>Pragmatics</em> is the study of how we understand language in context. After we have
parsed a message and grasped its meaning, we still need to process it in
context. For example, if you get a comment on a pull request saying, "I think
this is very brave," it may mean that the reviewer admires your courage—unless
they’re British, in which case, they’re trying to tell you that what you’re doing
is insanely risky, and only a fool would attempt it. Context is everything.</p>
</div>
<div class="sidebarblock nobreakinside less_space">
<div class="content">
<div class="title">Validation Recap</div>
<div class="dlist">
<dl>
<dt class="hdlist1">Validation means different things to different people</dt>
<dd>
<p>When talking about validation, make sure you’re clear about what you’re
validating.
We find it useful to think about syntax, semantics, and pragmatics: the
structure of messages, the meaningfulness of messages, and the business
logic governing our response to messages.</p>
</dd>
<dt class="hdlist1">Validate at the edge when possible</dt>
<dd>
<p>Validating required fields and the permissible ranges of numbers is <em>boring</em>,
and we want to keep it out of our nice clean codebase. Handlers should always
receive only valid messages.</p>
</dd>
<dt class="hdlist1">Only validate what you require</dt>
<dd>
<p>Use the Tolerant Reader pattern: read only the fields your application needs
and don’t overspecify their internal structure. Treating fields as opaque
strings buys you a lot of flexibility.</p>
</dd>
<dt class="hdlist1">Spend time writing helpers for validation</dt>
<dd>
<p>Having a nice declarative way to validate incoming messages and apply
preconditions to your handlers will make your codebase much cleaner.
It’s worth investing time to make boring code easy to maintain.</p>
</dd>
<dt class="hdlist1">Locate each of the three types of validation in the right place</dt>
<dd>
<p>Validating syntax can happen on message classes, validating
semantics can happen in the service layer or on the message bus,
and validating pragmatics belongs in the domain model.</p>
</dd>
</dl>
</div>
</div>
</div>
<div class="admonitionblock tip">
<table>
<tr>
<td class="icon">
<div class="title">Tip</div>
</td>
<td class="content">
Once you’ve validated the syntax and semantics of your commands
at the edges of your system, the domain is the place for the rest
of your validation. Validation of pragmatics is often a core part
of your business rules.
</td>
</tr>
</table>
</div>
<div class="paragraph">
<p>In software terms, the pragmatics of an operation are usually managed by the
domain model. When we receive a message like "allocate three million units of
<code>SCARCE-CLOCK</code> to order 76543," the message is <em>syntactically</em> valid and
<em>semantically</em> valid, but we’re unable to comply because we don’t have the stock
available.
</p>
</div>
</div>
</div>
</div>
<div class="prev_and_next_chapter_links">
<hr>
<a class="prev_chapter_link" href="/book/appendix_django.html"><< Previous - Appendix D: Repository and Unit of Work Patterns with Django</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/appendix_validation.html';
this.page.identifier = 'cosmic-python-appendix_validation';
};
(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>