From b90127e29064a46f8763e9bfa743c2cf7c08d2db Mon Sep 17 00:00:00 2001 From: Marcos Oliveira Date: Tue, 17 Nov 2026 08:16:35 -0500 Subject: [PATCH] =?UTF-8?q?feat(demo14):=20compensation=20under=20fire=20?= =?UTF-8?q?=E2=80=94=20late=20holds,=20duplicate=20releases,=20replayed=20?= =?UTF-8?q?events?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit A second LinkedIn reader asked to see duplicate events and timeouts during compensation. - Inventory demo switch (slow_reserve / slow_release, 6 s, past order's 3 s timeout). - A release for a hold inventory never saw is recorded as RELEASED (and logged), so a hold that arrives late holds nothing. Before, that late hold kept the stock held for good. - Release counts every copy it receives (releases_received), so the page shows the timed-out direct call and its event copy both arrived and the stock came back once. - POST /api/order/sagas//replay resends a checkout's events with the same ids; inventory counts what it skipped (duplicates_skipped) and what is not its business (not_handled). - Demo switches share shop_common.flask_support.DemoSwitch and one switches_off() answer. - Page /patterns/compensation, README section 14, smoke tests for the 3 live cases. Co-Authored-By: Claude Opus 5.5 --- CLAUDE.md | 10 +- README.md | 28 ++- docs/screenshots/p14-compensation.jpg | Bin 0 -> 74577 bytes frontend/src/api/gatewayClient.ts | 35 +++ frontend/src/pages/Home.tsx | 2 +- frontend/src/pages/PatternPage.tsx | 2 + frontend/src/pages/Patterns.tsx | 6 +- frontend/src/patterns/content.ts | 23 ++ .../src/patterns/demos/CompensationDemo.tsx | 213 ++++++++++++++++++ services/inventory/application/__init__.py | 3 + services/inventory/application/consumer.py | 5 + services/inventory/application/models.py | 7 + services/inventory/application/routes.py | 35 ++- services/inventory/application/stock.py | 30 ++- services/inventory/tests/test_compensation.py | 135 +++++++++++ .../order/application/order_api/routes.py | 29 ++- services/order/tests/test_saga_and_outbox.py | 24 ++ services/payment/application/routes.py | 20 +- .../payment/tests/test_contract_provider.py | 2 +- services/payment/tests/test_payment.py | 6 +- shared/shop_common/flask_support.py | 28 +++ tests/smoke/test_post_run.py | 62 +++++ 22 files changed, 661 insertions(+), 44 deletions(-) create mode 100644 docs/screenshots/p14-compensation.jpg create mode 100644 frontend/src/patterns/demos/CompensationDemo.tsx create mode 100644 services/inventory/tests/test_compensation.py diff --git a/CLAUDE.md b/CLAUDE.md index 242b334..4ebd105 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -27,7 +27,7 @@ history, monolith dropped). The full agreed plan is in [`docs/PLAN.md`](docs/PLA - Name prefix: `ms12p` (parent uses `flaskms`). Teardown deletes the whole resource group, so a shared name would delete the other project. -## Current state (complete: 12 of 12 live, plus demo 13; one Azure run done and torn down, #11) +## Current state (complete: 12 of 12 live, plus demos 13 and 14; one Azure run done and torn down, #11) - Folders: `services/{user,catalog,order,payment,inventory}/` (Flask, one DB each), `gateway/` (FastAPI), `registry/` (FastAPI), `shared/` (`shop_common`), `contracts/`, `frontend/`, `infra/`, `scripts/`, `tests/`. @@ -49,6 +49,14 @@ history, monolith dropped). The full agreed plan is in [`docs/PLAN.md`](docs/PLA are returned as they are. `saga.settle_charge`: APPROVED confirms, DECLINED 402, VOIDED 503 (both release), PROCESSING/no answer writes `pending_payment` (checkout and add-item answer 409) and returns 202; `reconcile.py` settles pending rows every 5 s (deleting and committing the row is the claim). Page `/patterns/slow-payment`. +- Demo 14 (compensation, from a LinkedIn comment): inventory switch `POST /api/inventory/chaos` + (`healthy|slow_reserve|slow_release`, 6 s, past order's 3 s inventory timeout). `stock.release` of an + unknown hold records a RELEASED row (order_id `NEVER_HELD` = 0, no items, logged), so a late reserve + returns it and holds nothing; release never 404s now (ids must be 8-36 chars). `releases_received` + counts release copies (old DBs gain it via `add_missing_columns`). `consumer.counts` has + `duplicates_skipped` and `not_handled` (in `/api/inventory/events`). Demo switches use + `shop_common.flask_support.DemoSwitch` and `switches_off()`. `POST /api/order/sagas//replay` (chaos, own + checkout) clears `published_at` so the relay resends the same ids. Page `/patterns/compensation`. - Events (pattern 7): `shop_common/events.py` (Redis Stream `shop.events`, consumer groups, at least once). Order writes `outbox_event` in the same transaction; `outbox.py` relays every 1 s; inventory's `consumer.py` commits the hold on OrderConfirmed and dedupes via `consumed_event`. `POST /debug/bus` diff --git a/README.md b/README.md index eef5009..a03671e 100644 --- a/README.md +++ b/README.md @@ -6,8 +6,8 @@ can click. > **Status: complete.** All 12 patterns are live, each with a working demo, locally and in one > real Azure run: provision, deploy through GitHub Actions with OIDC, smoke tests, screenshots, -> teardown. Demo 13, a slow payment in the middle of checkout, came from a reader's comment on -> the project's LinkedIn post. The foundation is copied from +> teardown. Demos 13 (a slow payment in the middle of checkout) and 14 (the saga's undo under +> timeouts and duplicate events) came from readers' comments on the project's LinkedIn post. The foundation is copied from > [Azure-Ecommerce-Monolith-Microservices-Migration](https://github.com/MAOFILHO/Azure-Ecommerce-Monolith-Microservices-Migration). ## Project summary @@ -27,15 +27,16 @@ React frontend with one page per pattern. Every demo calls the real services: no | M3a: async and packaging | 7, 8, 9 | [#4](https://github.com/MAOFILHO/Microservices-12-Patterns/pull/4) | | M3b: delivery and the Azure run | 3 | [#12](https://github.com/MAOFILHO/Microservices-12-Patterns/pull/12), [#13](https://github.com/MAOFILHO/Microservices-12-Patterns/pull/13), [#14](https://github.com/MAOFILHO/Microservices-12-Patterns/pull/14) | | Demo 13: a slow payment mid-checkout | 4 and 8, under a timeout | [#16](https://github.com/MAOFILHO/Microservices-12-Patterns/pull/16) | +| Demo 14: compensation under fire | 7 and 8, under timeouts and duplicates | [#17](https://github.com/MAOFILHO/Microservices-12-Patterns/pull/17) | M3b was planned as 7 GitHub issues ([#5 to #11](https://github.com/MAOFILHO/Microservices-12-Patterns/issues?q=is%3Aissue)), all closed. **How it was checked.** -- **181 unit tests** across 8 suites, each in its own virtualenv, built test-first from M3a on. +- **194 unit tests** across 8 suites, each in its own virtualenv, built test-first from M3a on. - **Pact contract tests**: the order service's contracts with payment, catalog and inventory, verified against the real providers in CI. -- **25 local smoke tests** against the running stack, and **4 Azure smoke tests** against the real +- **28 local smoke tests** against the running stack, and **4 Azure smoke tests** against the real deployment. - **CI on every pull request** runs only what the change touches; every image is built for linux/amd64, started, and rejected if it runs as root. `main` requires the "CI ok" check. @@ -62,6 +63,7 @@ or the cheapest SKUs, with a $25/month budget alert, then torn down and verified | 11 | [Contract Testing](#11-contract-testing) | Checks that APIs stay compatible across services | M2 | | 12 | [Service Discovery](#12-service-discovery) | Finds service instances automatically at runtime | M2 | | 13 | [Saga under a slow payment](#13-saga-under-a-slow-payment) | Follows the money and the stock when payment times out mid-checkout | Demo 13 | +| 14 | [Compensation under fire](#14-compensation-under-fire) | Times out and duplicates the saga's undo, then checks the stock ends where it began | Demo 14 | ## Architecture @@ -213,6 +215,24 @@ payment still said PROCESSING, so the order waited; 5 s later it settled as 1 ch Demo 13: payment slowed mid-checkout; the order waits as pending, then settles as 1 charge, 1 order, 2 mugs sold +### 14. Compensation under fire +An undo is a new action, not a rewind, and it crosses the same unreliable network. A second +reader asked for duplicate events and timeouts during compensation. Three cases: + +- **A release that beats its hold.** Inventory holds slowly (6 s); the saga gives up after 3 s and + sends a release as an event, which arrives first (about 4 s). Inventory records the release, so + the late hold holds nothing. Before this demo, that late hold kept the stock held for good. +- **A release that times out but goes through.** The saga also sends it as an event. The event copy + lands first, the slow direct call second. Release only acts on a hold still RESERVED, so the + stock comes back once; the page shows both copies arrived. +- **Duplicate events.** A replay button sends a checkout's events again with the same ids. + Inventory acts on 2 event types: one it has acted on before is skipped and counted. The other + types are not its business, so it ignores them (also counted). + +Here the hold arrived late: the release came first, the stock went 473 to 473, nothing held, 1 release received. + +Demo 14: inventory holds slowly; the saga's release arrives first, the late hold holds nothing, and the stock ends where it began + ## Run locally (no Docker) ```bash diff --git a/docs/screenshots/p14-compensation.jpg b/docs/screenshots/p14-compensation.jpg new file mode 100644 index 0000000000000000000000000000000000000000..4a3d71fd44a07a92e385afee0a50d25daefc67b2 GIT binary patch literal 74577 zcmb@tcUTi!)Gr)5q4y4g5FtQNsx*;KNT{I~kt#Jn=pcBM4pKr0APNXbC`yo$gaC^4 zF1<+r=|~k&QPgw1ocF!=zV9F3{hsGO&t0=;<~Mt-ti5J3vuE$M*8Exgvj*UR8Jijd zsHgw{s>=oNXM-&E*rlz*7g$f`2HvM`xkru zCyxIYM@NK4T*{#T#bLGxgG*d>iDi8M8}|Hf*ef*bU-_|18Es@xSu zAnZ~i__F36z~>SJ{=I&e`YtJH6#%%^`RC7{j{mBIbpilQY5)LJ+ke%`XaNA6EC9gJ z`~Rx@uWK6W5$5q9>S!;w)c5WI0B1D-0IL%Kz&&}X$K^kGmz)2?xrtx0L@sR&xm>Ru*Pv7C|msAP~sH%p$#k;yGR>z4|JE?fE!`d^J*-Y);Dr@!P~=e)Fnnu>~^j)s=z zKkcES=A_}GmIkY-3lj#Cp8W6h~5bZ z(l(+=U&MT+-bw#lml9~9WXx#w#gvvKUa$T~#!b4D-}89roW}fxS*fm{?D4_JIoemp zcz*WKmBG~4Lojb()c3WDG(KT?JWloDYS(9MoxyEetB8Gak6Fr%y1d?D+PdaXvj9Lz z)(>j-k9K13x^*8`iyBt%jBuhinPJnsIM{O1H}kNCGVWqce%`ute6{x;QoXm>xaO(8 z(1=p_LzsPu9P+z>syzdXYljVDiYrj)7^1m`A@6}j(=(|vV4cZe zLTQX768U_!f{ohcmu|$b1HNO@u4fy#?bJcEC8fOxW0ilT(e+xH7+P>F0=aTiyKV~d zd5~WJMO5^BIsJ{~gHW08o#?EX-ME4rfp+q<7Z`}ms0Cwyj|9p&28@$0pcM}rFR5v7 zcrn<;@S-iURh6^N!ZI^`Tts498=Z2+W1Q6^@{L}zizs;_0b(3P?XX++07hF__d>Jr{Mu&Nb5QhzAV*{!BqCF3zP;_;MF?s`KyLJM~Rh=R&|F#jA3%K5x?3`%)w% zG>8>}*JC>PL$9gkz z7eA0M3IUgbBn;k33?j*VTwTkHS)6CEL>M zHIYAGJm?&GGLd>M-PncNS}2LGyFT~Ut-!Q5q5csl!4$t7-mCMyH%1W2f6K-e556>+ z`rN9wZD-R{q}YF5!7#R=BHDI5*d{Qiu!oA4x)O7&D-@BPehPTXu759H<9d59*OSPd z91$cN9a!u{(|R=dnold|hoGzQBpDwI0P%jBjcW+ghhVjF@hkr*qShp89@%0>W>df( zx+)u5`=-mKUbke4pVJx;*W5O5`f`c2!F)a~m?Iwvf?@O*n%#P^bRdJq_sQtYXS|Rv zydZS8&s!req13RFi^HgMJ2>*3ZfCLWe0N3yTTr!UHI9IaUqqaqh%ZP%qOrr-!D>ak zqObOMU*1*ibn<~alZ1%A?-CW)T^VsLuJ4*U>L&oMx2LkND`5L z=hmtu-e6Z}ES8G`&mKf=@s?z*xuajl487vo>3cXCTNZ6Nc1V-uUplk1OGXsJqbp3CmKt#|x7GDedv>0eCPELSgO z7AsT{xI~m)}bB>gN$AX!}-1EuHw&ov^4XX>jhNQ7A zm7>SasS&T#2a74{XWgd_#=||#_q;)7qypn$+A3O@jRoKQX1AU?6ezlUnD=N#^)|DU z0^c({@k7*1l20!0LLxd=q4kx7%hr|*z&Oq-ip?^0mS7m>!iZTL5wv*-F<30C&Ynm; zY`uCDoH88b6NKxs&pQ$|3e`68?zG&vS>m}|xqwVRuvB`o2YaTEwzbD4C{(1lv#@wA z$*w#dMWytw&mTPwVAp{+v`J&uOr4~_1vPtGea8hXRILxo4_BVEWaL)kE2< z=!sBikY=fQt}4sX_c^C{6W^4OB8}0kNJUP~G6Thmlf(oe8_BfZZdmd2#z@ZN?7b8j0 zXrRNo9;7v0-1T{!rkFvPbHcm^8$=>tvJz8XvMX#i@7tRvv3LmgSXlad(=U`)a+Q9A z{O*Gj7-@Nx#_vgkgtA6g&0Q(-{SOl_<08-PblBEivYQWrZ9lbeY|*diZ}ASYYT9jA zX!q~mI{xQ|Nk;kCOazwq%0F^{Cw)=PY`3@k1K|Cq`{HT;9XV*rl^;?64Asf1{{i&2 zo*S7uA+R`VERHVLX1yC~+ZJR(%f;M4>&@c(`ppB?(^tvTE2wIp#?5SitG)=Y`MjE`?D&3(euVC2e)6463taB*8#J(fK6MpxA+)Dp^5 zI2SbSmC4JKagzM-_$s===Yq2ZXFbm%W$6+k4w9eh{kMBt#Mg4hZVBEKk1*Iv15 z>svPiZ%+xzy1JbK+i89;&aryB~tZ=&82MRbX; z(nhNB{p2Ff*OvF3RqJHb1*N3hO$UC(1S_ard}q&3!@pn3Z zDX%ZYv1Qy;XTo01Xv)e*3$oR?ncQh9eF=1^%`$mH61!(}%3-_7+WD|4mj*-q;I{+# z7X$>3{Ys&5^Y)oO6&;B@i%pUpPjEe2_~4v!@^;IptvAijB}jt}?$2f0gXJSqV+s4A zl?5XCV}mIS_aist5^(RTW10W5@jv{8(jJ5O>uQG2$nwT2uQvo#RJ+h4jBz(agu1?f z58Pr=>!VMLbYvQVmhYki0;3hY+(G38k>E%=5Ewk5n0tk3WUi-G<~MA5+vG{?&70Lg zKi3FCRc&qd*Dt0LdLZeLU_kj-K?lZAxTh;gvWN}K;0m0LPmP;bSYA_sZR^;^Hxcp4)K1oKE- zpUw$RuGk@w2{@>d6ts*dbtYx4?xSjO_rE;SkaMl|}t{3wJ}Hvf&}gl%2}48;zV z$VfM^@s)h-sy{y0SP1+}jh|I^-YH*jP*8tyXV@UF8C~`zVY=M-MW?n}`B#B6L2S?6 zoG&3NO<3|$A||2FwqPW*O0dum_agWSr z)h~RKTXB^Bp0pgO`jhFqeL!Qqos+#RUQ(trzwFdLfN|3zc7ZJw+;f7G~+1Js`Wd*2d~|J?fmFSCk~o z`J~$lrh)wQQA6CfdTS%;zW;`L>wVn#>ZoM}<^D3R4haT3L`sY2<(_(pjeQkgm_->C zkJgc@1I*CtfkM1590g^V2QcMS6pf`91j;qa=hn1&M^}yUimx0m#$ZW)dZq#cTE*k> zarVtu*jGJqzwA3=30e~0+jg!0g5zM*+*x#V*QY1+rjy(!1W$e^LtUbIuqHkTzRIO8 z8~?9`7?T9a_ZqL8ehl=2jUbkSOvqb1^Ce$+aZG~3Ri%lkt4muA%a8;IR!Cjq)tNv7 zG=ulXx4L0j8xH^$t#bI>&^LS`pcU2RD%D%8^HV_InIvF66@nbJx3w)`P}v)jfEsft zXMZn0av~d}4@r)pkfBV*7{L9PU?v)!4Yt+D%A|pF;u10}n7vvhqsbXvJ)MGw&}9>4 zSfqU2?Q#kNQ;=sBC!6Y-av2#rM13+9k+zMN$(%R?sf=YM!{>4=F2O#Xix=Pp1 zJe)Ah%`4c0sKQCeIAal&DzE4OBHUTCu=Ut`BGm?20dZefxVqYYIReKp_#DxvSoyA89Vs;|@W4n>8tK-W1O)fnGwDO6er zV@qGP+vjbcr|sSP*+C$SG-{?_*k>Nbu@8UjjAmoY`YRXU8=lmtQUAjwt)Vb5>2bo) zp&m=v44Zb^ouJqDkyYwC>0U^nRLEidcIfQjGPzEnk@i`i>8D{WiSqICsIR$T$CKp{ zJwFsK#hkoxt=^Vxu&K z3W~+w{I1C-9RpIO^W}6r8CB7}+n4 z+I<-4BA0sX!1zYLX3ThN1&Qy6SrNf9C~&9<1|6~O)q5+doYK*E9u?fPxHX$$P_hU_>g)!gMhL5~Cm|^*b*SuGbEw_7`Z4^U z(jSOxt%|THuRTa!Ro;jxqxFa$layCbQYHoElbW!yI8K=o(4GmFxc(B}wBq+l0PGSw ztF|KLz80c){V0OZ$2GatYT0pIiJ~AWXVX8>(*@I&Dm|xB^=Xi6dMj#K8K>drG0Y5- z6|(x!GfeBvgHh7_JWY^W*Xj-Lf8U1kwzy}&{-P8M+IX^Eu-~O=It!Iluf4N&Ke=%% zZOh28=9oE8gLPj!zoNeT?Lo-Buc0)L8~r)mn(9OXRk}LctKkIqCb&dKWrL#8U!SqY*iUKbBlJ7X7OiL*nMG^YVYDUd+x%SRk-s!n^TEoY)L)5i~`TIk2u)xY|9_ zO;Rluc+p;wt#1H_pC|3i4kFEqKc$N>?H3qd5BO~?XZ>J381!bqCa{QkZv#?5m`!^@ zn0blFY2^Ghl}OK}F5RqtM1VLJTwi2yxQ`#IV$K7}Cz0zO*-ZD^*)k~jnASoeqT4R56rewY*Q$1=o zf?R2bw|?<%i1nI#!hD(EzI12_ZuavhIpN)e{Uld*$g6`K`NrSU3Zn0xY_;}a!e3Eg z(TV!)GS6dFM7c#=JoCXrN6W(Vi%zl#Tda)a%yhHLE6W^Uzu|(=$(JT67(XD@3&$Kv zo}Sd_2`vDW15I@#17@0fT3_^zuGg`<%mf+wzGwwe!D2mhlesVeQ^Ak4yC0tRgfM-) z4zu|Va&d|!9~t{|&JrcuwbS@;TxgTyE@1b7#aH3={&Pv--aUVKP|^t?d(K8r{^u0Zdhj37cg?b}5iCxI*G>CJ*vEt? z(~Gf-`_pH_pkI9V|{j!SRpx}8G2r0g!=d?6(%M20C_P1_S5 zkcmqHGin;|>h3dCy<{CxCk9n46gnxdSebT?P5@|k9z4qo0Kwrlou}FvG9g60Q)Us=at9K3{kIj`M2$YHxkh#3Nh*t91&>ZF_jc{h_aDU@#C2y4? zuG&uR1x~2QOvF+o0NO$no*uWO32GsfU4$Q?R&VK(aJdMYg zo5bKea+~Gu#wfqltAO3d`7IhE{kY0BLAZ}5As=lVp8a?6;?3rmkzSs1E%p7o$}oy5pJk#AAP8LSMGRUo)X%TxfE0hUlh-3C>&kRse&dve&F z2fDEXo+I0*0;8azfO3r9vWQpLuLGL1XdOB8t6ELl4C2-D$sOPypO~1OGam+hpZS{X zum0)g@?^Aw)?DX=U@>O~&S0XE-( z-@<=dH*YWe0~lBwvVwf=rWIn#bP#a#Ac`&o%Rq(#OO~GL7iv6cCnVu?W**u8$jyO7 zsWPhFMOFT0Qa_3j%GED0;V)m6V%kd&YEZ1(#oT~Fltg*Cr$!L|8A2AY=$+r)Zo zt-DCpq4DbdujNlE15r-r-%M?1Rh+VluczRkKs_-G?BQ(5mbbV4z})@T)n}2RcNO@s zTpN5#&zymRg0P2@k|@%*F*ouxyLm~LYX*=oy#6&ktDm;y>6sY@%PDlI-YTi&x@Uf1 zTu@zBBjqgC|EETXDM*GvsBmw>P6R-Ii$MRQXR%MQ%gB;FPhyM5!U zFXm?<7q;$Odx2E))}|Yih4QYQP4~^(6Ns5%oG{m>{yn7{Wr_Lu#H3Cu`XZaQ9=j~> zi^<3$muX})+}oGN-_z;-ll{3WHI5H%e{EFU&#G7KrTef%bCiaF!+WeOsEb-rQeS1e zRBayrusp9D4dD9&06!T)1tM(q6Ehk0XexRdp;{vLm}t7yn$ZWg4L!eFUa0jE&WBmm zFj+NL`igj2)A9T)k*v>pGp`>XnlBen*>s_cl9)t@d+;;?Q+t)fFva|LDZU<;)4y*M zhEdOhdePOq@BK~Zayg(^(yTY<+tgy>zG>}_dJ1RuH<-_=x0cQq>2nE7>kjais?+9W z|6FkJB$*LMJ8&C4FJOgrW)LRLfksu3ZWaq?6YZ`J&lRVQ4&gH~5AJE65fNuB0W1SH z9tB%d$pTNi)nD#AbdFGI0YLuby?WTD&XrU`#X;u%v5LQ;$Uvxn>~wQg zB6XBj=__;ol+RJI<`b>5tG_WB^5o?dybL4in`R0%mxXaXXZG*&*Lmt@NXFBxX5VA;uuve}`jf7RwtaUQ11-bNK+j4S%E8 zLRi{quL`%TAXE_5aV5UqRa{Ymdv4)<912;_@R`)2D1L_G7@U=e8*aT3uaL8566*bm z*8OO@Lr0o;MZf>WzdtcO!_>H z!qQX$;-bLu5B8c@WIMt;dI&ctEq7$#k0+O`mP!zFS!*Ei{6=YybyrPwq3=R7A=$j2 z%-`n=XmaN;X6r#HSUf?}z1ID6 zt`KXV;8cUv(_+@Gx1zKA`ZJT6P0kivEklhbvw;zosr>3yMz}Pvz3IzzhZ6;wA?L!9qInR{WeZ7dz$Qg9A6T$Dt}ts z?{|7Rl^}g)!km8!M8GI`m92G2G3L*}bK%G*FPBM8Ni!qG>Xgumx%IzkOyo-I%p zjYUbTOh#e}1=1x;iRfdt4-{I?M8H{j%DCbY!d+Rk##37Xnyr{Y1v1qyM!6?qjM?(Y zI<&SYG5a5Hbzu!ku$nzvMovg+qJ(G!Ev9}gk@}&OP>wWh1$OYdX^#DD->_9SkVQgQ zjo{xC{RbeZA@%nh?D}wrV);8-3#8(h&w!6v53&_g5X7`BT>q#wHG14njUlI;Ce)yTP5*R}NQF7c-p-2mRgO=#(*u z`oc4rz;MIw0CE3r%7eD@Po*0!_v6*xf1?}p)F~VVBL!VjylJbX=cOKHF1*g(AZS=n z6l6-ID#6KCiJuUYIPpU~NJ{GSbJo)&2cMHoL=5tozIPo?anuDNj0A#FL^_bOE^uGd zovCV&QR7QeGP8q&6Dh&(cK?d_}wn|uJ`AzRcWbM`grB^cNT6=+M5qBmv+nC_Z z&ky%>>EdV0{b@`7N*bK#=?pbWIpEEMVhgUpj|;F6JtI;V(7)Mu5XP0)n&WrvE?=ML z!6L4&n3u^WJs3U=Mfw0`?dkEl{;+hAxCnCH`C>VY^dl;A1cKRMwwhB=L@y!I(6{^1 z`1Yiv6t8ksY8?y5iw{a=PcO$lpWCfJAVfno3vi|`ZL{@(l^P@A-zzzE}UWR{YurQ5y()YNa( zoI7~?t;6Qjvr?q41rz`=$-)-!T)Grs=>V3TnmXPZ@`?B3mL`6+eM$;?)zwT2G+W0s z?(7z}8a07C>_>*Ene4t#3w?CE$s)5z*dWtSGesh1wm>Rx1B(vRvLKXdbDC2{wGalSCfawh z2h492W;AHxdR%>Z2rPIw$^!iU&1?(NS1W~EIeE>ouTe|L35Y_{Rg62*Fzcx!EN%*x zw}!k^jUvE{1Y4b=G)w#k%7C+!48iVc=qVSTb&wN9LJTAL@t*CHXUy3$4 z1xt&Gt99p4&dXdn`2%37?hhzsG=;y#Z@;lk<(js#MKi*TyI7Ea0H5Yewb{jdnmEI*F{ff$0C z_co0D1~s*~oQG)JveDzuPX)$*RP>hk`8t;io=9J{Isa$ANCP}04YlZWMwpJ<-e43Q zpKEJ#a!@;^-x_P~*(4mu=>^HFQ=XcN8nap5#JiR;2Ah|ygxqAXdJ?rO&cKlc*7Mho zjHFEN9hJWh-RxJU+a72cJF16fQJTsiTN2xQOhaxrm#IpUvL4>VZ%=R4HaMNNN}jjr z;ckw?hJUKQg5})r%(X5ZBoR3Ou{2O@0P@p2$KAb$F!O`@lL~uAruC^lN(&Bu`8Znn z+~2O>p4cG`M|%V5Oie!XjyhlVt1}b1Fs5_1YhLLlN-E%N6NE;#&c02>?5;3R?b_dV z?!ROe`?ESCil`y&5d}slGxC9{9yCw{6Eb#ypE_^?J z;fy^Iyr}EAUt|O!dB74!+5kMH6AR_eZOw$@iIk8ddsJZ5TH|RrNk>e)MksWNGdHB- zd1q2iBMLVVK9ATQnbC-*!@i}LGrDdhWE+`}ccDhJ=^h|LKk_XH&(DrsEK$^)Qd|EC z%;kiJ)=NtWjiwFKOyS4a*aDUw%f5h3U0q61X*JM|O2ujoSxr1KWr*il7`@H1f{Y^J z;qTJKi6V^;XLV=l1iGx;UL;Xu|hZ)j5T30W6Cwh>dyOHo@_8cV2tKOH)3X zLCBAq(fhiHqE*fDUSwJ`UaQwZgG8h>I8;~NfEx)((2qnwWIuL>m#Y8zq|%!eY*xKd zz2g!*h40Q_H%p#k+y;AVW(8W!W3yu!YOL*lT!uFE?#zXXWTrQA@-ipvjC4irBG~nn zxIQpkakM|X&DJEe84<}Wnz{AxO4^H#*Fvzt!m2gST$cHU+cfEK#5#l>q?r#AxL6ik zW^rIu%MuP{u?s6DBngQyEs~F&iazwN>qL>F~`D z_VBi>gQLa_`Jt@DCD)+Zszi(hqvY5Yr`7v)N`H?eV}647a5jX?G4_To5X>Y1Ug!+p zU3a`X7@4HOJ*7QP9!V&y8glW!^fqE}JQZSsQaM%IPABF2{{IoBvi;va8>id99ey$F z1oB4Uua5n-PWg4Us&?}afbHW4UXTwAfn`Eqg`T~==&-GA;$*Y^5T-v%;lyC@zyTar zC4k0CG%nA%fp23fDtQr8WL7}DY7y%pu9h~tNE^x2#oP48Ny>t3K<*+7D0@i^B#uhV z;)#2*rlykpVDa7F0m3O+$dK_gpXtYD2x;_mH5N79ye|?;won3CNqr`tTR|UKNq}*h z{mnbS%=-cY5Bv!nqZU%N+y%k94C3C0fjlVvx%;TrYqUN5w1g?Ro}T%W_{};e0m0$% zU3X18#%0b3pNqyP9SZUckW=@%t`YmYFpjF)M`atW2jq_x{m6HoSEJD7KReVhVq2g7 z02nj9K8?rcgnzfPWPkj$SP;SO*CCNFGL+LIA~u=bRAZ_xE&dQM&7i{|bnzyNp!CtZ zWz-craZf7!nD3joMk1p`oT>QHJ2!Iu1ieMn&~~LIht8qOAm?Ve2`mB!lH$Mpk4KNb zrLLYYe&xHWtLf&{hHRR zw?Sc9LRgSx)EE+`yT~{PE?yZ96|8*>Rn{J>__=Q#Zqf;&4Sia15aZfpt{Zs z+E22$f2u;KD~k41aMel)JE_m%DlWxQ$rCN9&LFtj_;|otYFQ|IQCe-Zc{w=)u5Vzp z#Y_DhZvT^wO>upm*m@;@DwN!SIF4(3>=EEHWwp8Vbf(#L5hpu?0qk3r$pw96t{|TZ z9eJPMe^$g15oZ+OOo%+$xy&wtCv4c)3%X2R>l_ifuKh*EA{DKPv8~A8yqx9syo7D~ zq0HwJ67T07J&ej=)Q|AS$x><9n@V`~{sCkyY?Lura*f4)Q6;raX~`xvAx?Eia;isi zL%+95HZYjo!)x`(L`}uEp7&FQqZD}0{s5v=DaMMWm;2|PiC2~y``_Pb%4k}$vHl`B zpH~QPz!UH=rpwo<$-}``uF*|L>um)&MbHSknC(X42S%Y$e^cj2h=}%#5nVUkkf>u$p32_6*~{e7kVM84@kI7^0{^N^e$YnDjbeXXw{a2*<(98E7q&F` z>yfk$FNv_^Mg*nWs3^#pg1&{DYaNIc+kRf&84%rQQ6?Sn-3 z?cJ=^`@R86Ssvwoa|W7R*U3rRE&2QuShg7hMUfnn)NBr1lT)2xsvchsmMViDS{$C}9TJ1()HVK&V=4yzrUW^*&) zn2AqSgadVmpW961j9h6}W8uE;MLHT(ON=x|8q=ryS)IrOWZx)xO!bou?NL`KPqmy_xh84Hh)u7XXXC}vav zR39MYMStPL&kyg zGX~-CjRAhYY3J)25{yr(rv;sY>Mz}MH5PB zwbNmb-gPFv?alP01W)LO$>YvrdR#LYVX2k@4s|-^979WjS9Z{{3fH(BUJ7Y?YsRm&*@uAhhMTQe83R}9ellXe^wGIPTSX~p%&+w!_G_2M zGA90aqF;#z`wr$yB|KN@Nga3_Cl}L+{e-Y7aWCLp@GOY6mp?sf+Wne-Hr;d4odE(* zUifj9mz^6A+p7ZD*yL0~gCdseTUc<O|s!1l6y8jr%{J%)EVdC$2T=-1B?Z`09dC|ChG zA|U6}lTx$9bCaI%yvcrgIwMbu1U{8+4L|u2Ds3D|mF0iDDbUZb_gE$v_Z|wzU&vW(RtU!|+@k*j=xZ1yym@lE)%h)#s5ye;TarfHr-*+~S0A{c6isR=8C3v+wYNuRKjck@;ev!a>WXhVQRW&Pf-M!-1} z+dYSoKtFJpJgxfl)h6(k`USj7z0}zSYRY6~@hh*aU(q%%-P}<=zC5gmX3=G1e0XUO?tS1pNmARbtyxUbuf%F=7*f z3oytlm2oh0|G{}EJ{cB$1#4s|U-86RG`i`U*RZk@hR2p#2!YTap04M9G&6z3TF8*^ z__TN2sklyAj3kw!hDBP#s&IxlI&}#NFAXc{`1{^}rxVpEjOkxL#aG|gED(aBYg}gS zQl5*>z9`L&S(`l$EqEIZGK0?uF*}RIrfz{D+5`X>j{P!fJQ&ZiljL$GYg^qD9=5my zv8mD!Qtr`HD3Eqz%Bum$>3uR4wu_26w^7?s;MXz;GRa5Y=~2IDspu^(j+Nng2%NtW zmOyOvNrhWLdZY$Yr_Xv;c{!0JbF9t!?p%CZx zWD&J4F*Fp9D`;0t!CoBRN)ygxHGH7{obVam}~}2;4ZeAzY| zP>@Qrdd^lAv&Ka)t96^<>L|5xI%>F;ak4{Mra;1|a2Ptv-2^rjkKxX4N9vJCZuybV zZ&eG^OSw7Qh|5Xz*9i^L41u5@DTfWQ$JgGt#@ve>e(dhK`c;F?7`t5GzKVUNkIiE7 z7510PZgCmsX_QPQhp9G#<(#Q(UJ3RTT3pU%8T6h5WM9Q|2L@>`xjp+(m}Zqeptr3g zLVI05UbDnkeSEQeVPJ!j3=Ih0rB=4Qww#fLx6y^opfMr{3^f~6E8u_>@0C4>sZL#d z9Gv-k&XS`u2hk=iU!>nNqI?-Ms5!-N_ohHvrOIzl&~fIAG8sID>Dw3Jbboe3FQdMV zDLraG5Hs?(AQ#k7?45+80Gmh6^A;;A`9%8m+XAk>+I@^sg}f26=qt!!BZ!)yqkg)h zp6oCJwIUk5=REftN3Lyx+s|`?hDI?5mLp&w%oRb+rO$@rN{OY~b$S=T{&$S$0ET3rPj4}=lK+w`WJ)kK=o6x z2m$FF`)@lUhI;;mQWYr`Hdo}ypF(NA`h%w{OV+Y=cO}K{YrWrJ=la67fNX67Uns8r zWi!oesvA@ul3ZJI@VYt1g0{`P{ou=E85_7_RskQj`m`J!7RJcnshs`AMH(`u73sN! zzf+Ow>LH-z?_{bKyA3Sg7TPRsWlX4^^F?koQMFA^e=T!@+Sf}6n9eqAw5p40pU*A- zsQxA^&3Rj(f}=Q>^GAUHbdkx8sz;x4p}ty2NADxxYg(o`Gpx5XQfEYrLY2i|lub${ zzZOjZ1>cC)nyb^62*i9X_*)B#=?&7HvG8Dmd-I6IaAx_AB-u%)?+DhmE_*y_E-vNx zYZ?w>Ho!R!gK4v>5=%mMtxYyRK-2g(QH07{oi<7$NF;Peo!JyIZd1j284%-MFC$LD z)`z%`jqkr%MY*tv$k9M}d655nd75_ayqeBYNy1d=!5=;RoFMINn_rKt^)Nx!s!oy1 zzSg}r$oKTP4t;pI_~~9SJ`M&5!l0=;HWLOr@u$e~17u5Y9uk=+G2HYNb^SU36bzE` zmijiXyatr4mV2Jm)#^7I`_J7oa%M`5snVUS}y!tA&yg{X!&kf-N3wC)aw@l6! zxOMw)!tUpKiIX=n{9h-XYjRsiEYOsk)Z;786sEn?(Cyrzyz=A`e%r zxa##d%0W&7<~T{8zj};Z-^~>bn!p-Ax$)6I{bhzk?J>5&Udm%yF}26iEEk&fIdgHD ztb2!yvFpERcJx^^@28gAN5ZHqcvE8BQ=}qQglXGnBR(-dn3pJxf2 z8M#rzUCzavF-@(XXmR63_M-#qTir^}H&kG^@@oCaz%IhC4^kqV7)yDXvR9(fi}za3 zkNHyqo?gkm>gUho{4}$UNuFT00DJJIX-JU5BYc?#a_I=UEdO_(P|zo(s~7DsV2ZAO zvDz{z^GjL7&-(W|4%!7Q{*p6mxN-6RMl7n#AG8RXUd{%wwXf5?Agyagi)oxRlpT4e z#NEj11K-JkfmCshpKH`7o_xgF`X=M8r_Y=XGT2?|`V;;Dey{0WIU3s2tGevkk{w%_ zQ|id)d!}d?R2y9|^@x27c8`Wut=|1PyJnsA^2yk~7;VkWZF(t>Jy^FEii z7Q`F}A6gmD0#W%#*BH^Yw$2|AolWQ{_vLrIZ>c#~-;l)bT`wRP4nSd+slf5L-SDSv z45|3SgGvR(r-&Ot{6Xg3TuCz#t)Q@Hxf9w|>W$@<+(+{-4liFfuiZD= zzMJw9-V=$u&#F{mS=C!bJeL{1R?~{;Mq}X1Y?SiY>9_g54@y4j2eLjzqSL8PtWtQV zk9|KS!{Sq+pDIIt3m7kq?ELj(Xg~Lg>_ljC(sSiyUY1Ti(%6&V{b@Gf1qxbB|D<|8 zIXN+Z9h=3u0W9CCjIX(IHkRg5?lMm~RwI?kMS_vC_V(H0(pIJeJkedZ0(s)A-Y)uR zci1RsQdo7SC5Po;iOVo1p2|l!FGn5mivZj+Je#$Tt_AJTq-){X0XE=gV*p0wxb#N#LlDxTRJv75{=%SZo`EEQ|4A#qVZv z6p0`$z;Y5&*~^`#OwfT9WaSD z(VWSi0!16l7Yi(z@=^dK-R0Gh^JFRMPVlDbLaf!*9-@+4yv|)449sfL-_I1Rsnn?7 zEzI8Dp*h>TzKGsZl(-IyJa>vLKbYXH)9VMpq@IgZc?q*Ky5N5`dYcy0ho@4FF+wYCo@q|YyEYw^|fv@f|I~Il9qsF5;8eNR0fZ0cii33aOf!Q6WWHQl%EpP@;SE+D-~B7~+Oy(pn30Rn^` ziqfTo-isH~qzfSdfzT5mLJ*M-qJVTk483=dsuZzb*K$Aiz5DEo-I;yGD1;V zmFI38k28L$6o#`0vc30``;crE^6HHeZonC4iA)69j=!p5ucPyY@Lkxr( zTY88vg0JeR0KN|9#l##O%JIHj%=@{4+GxBFL66C1ow8Z};*3e25_EBVqZH!sY?imm z$U$@Txa~ZsZ0~A7;-=I5iJH>KrSI{mh(}{L+1(3NJZ-(CBe=y%TtYdu#Wk3zaxnU6 zmpODmp{zmte+7qHFSi}iVy3{Ot(ybzoX+GyUhz@;|`aS-Kd`h6Zy>p#T=&pmkRG_rI zKdAz##4Nh^A&aV>6a#h+T3Vt*Rq~G2wIx0rzzIM9;81#P(+c>-1moUQy`|$EIG=K( zSs;&^ojP@B5Yg685BlYGyY(!?mbn7mtJF^A^{|f6;WR96HgzSJ;O1A~+^DJFe@}&Y z^Jcz4UQ2PLypk%4feGFx_4kdsF4)y!glQiEd@CeF%hR zt)ud2Z-Db)g0fb}9T24ox!=o#*WhGS1D@Xv5s(J;s2ItpJ-%?drGUdVVX(DYP12xFomaq zdIi6{Vzp3Eq{Rj0ac63S)dru5K6Ng81xG%He3Zslg=8{7&>N&ibFQjEP;L|dSrG`H-<}c&|=YB&u1N0H5Xd$g)U`2$&wC!b#|ZG zztK<>A<&%69!<1i2@kTNWvRN z77F+b63A2xghDQ0xf2h-w9MRIt5CJUB#o^5CKoCK-Zm=NGmc*Ld-$Xuo(QK+CFUc` z*5qW$MJr98y%oj(YOOWe7!?mJjI{`O0)Hz=+~;S#PEsAwiGcx_GiF|R?BqMD%q{tm zQ0c@YbJduY2L{G-du~Jbj7CQxAXGABd_{O6S>@UQlhJk2l%P?qvPK+uBCi38!g2zH zrbACJrtpIK!lZlO7T+!Td!a1)Tg-)S@p)4rPIc5+gPG0`CMywjd#hC&1k-DFGl$k6 zm82ESlA4f797In>;N!%t_$z@Jd5gB~(#cp-+aj`=aU&gUj0@W$%IA`L31HETy^$b| zK8^6;?rDdUSTeHQ(AiYI-8+y`3>UYMO(pgqgK(_=)F1xp)#>V9_v-E+fy_VBh5~71 zzp88ga4$}fBBj@y^bi){F8TsWbCh(%eZQDIj-0gJ zk4*wR&Zzl3!F*KmOi8M(aiCb_>z;Mnj@d+#Gz*KJ`P(@bDS_`9p~S=AD@BKXDvHl} z7N@&Ej~yzg5y|R3Iv8!U5d;Gt{oBmU`}L8oc`9}$R$#cb&VNPH|CLJT`B{4;GEU^a z7Hf6!bQhUMVf?f9jeqP>{OjrecJ6u9GX3Aub!@=V`Ta+M#pUV7lE-s-^ypAGZ^Z6h zHC|qEnqWsqNwx92{{Y^Gm;O=v-Tx41)Nxb4cSG*9*Y&<#@{)5kZUj{bf6P0qbsAjU z@&bZHHeqY1bEi1&t3B*FmI$snn))#ji7gS`;5qtsQ@nel%Jzn4fe}~)zLB4tXQ0xj z-DX(8&E?a)ycOngYkfedh^667;Uj3~D+%IitBqg)#6brB=6!)=gi48ta)+uOSl%#g z?(_+Ymhx&d0r$3Y6*I!n`ce{Fw~^r&W&zi!KV709z7@D=b*4nC16B8tI@|)bQ*{rr ziC(ndrMZDd=hF^i9k&pjA&+*>y_7L#$WcaVzK@wO3YLg^)g9YBtGAIQ(pG^;1;bH3 zO&!47RgH810NztQ@J6g;5AE3#lt=PE=&)Nh{d~Zj^SSJ7sMRPbH_U`7l~qi- zO>7KE+m-<&0OXTCiA0i@+F#XODka7B+u#$;ruZ}RCnmI?q%Tuv8L*a53ozy{XC0C6 z!FSnw&MySY1(}g0?O;PpG&Mu?!XrPY7iepZW&vxr7k8d;5d>LLSlm&@A@ZT-iU=nn zL{2cBGS`y+oHuMORWhV$-qqGr1By5XD7pG>D#Z@+hNq~a?jH%9R-Sw`#?4Z;@qV+x2}q5Zhg<(DTMYhSd44R)D4`x%iT~c#ockoZ-mjvVP?UA z11}3_L;&{Mxdi=bRtTe=YOIbQgI6q_g797!E6%oN{Bex%LXDra5hCo~gwexyj#X-B zljLQ-P8A-lGA^&ccmngMfl4e++9_(EArY*N(z*Cne|qkQ6S zXvW~{_Eq;0fMq>4s+^_M3Ba)gU<*C*W2WLHx^WStI5r6SCLpb2!R;>uh%*h9paF)S zl}(*k?(z6BCf6F*HP>q}6^zjs0plEIAT;7ahwOI>Ck8g8i>nsT-q)si+TSn^d_rUT zWEgD{pJ~JhMPhaU;yn=>Y3IzMM>l~oL_|dWJL@`3g{#Wj85R+V7{Z38>)lRVelbenSuZ}&Az&Djn zQc}~3HS1ARBbFGZpuZvlf?MdKm=?VHK}KjMBrDP~8~V*=1*O7&t$iwNKjxDfE45e4 z`ig7nXU$VNByxjiP0DA_CLzPuQsrV+%d@>Uxy?PjtgZVuG#u=^WQ*(_p~l<7M41z6 zA^!j(mG+P#>2%G|Saf4NfryZ%0cK<4W4GA4YaQwuj>#=k+1+qQqfs;yB_EE^cG42d zX4S$9(tP84S$;l)0^dZW4dCVud^ndWxxY!OoZt<1-~Y`0!d8tH1yho#6$8a z{>_Tm{XD-Q=9-H<%c%$gsJUzN(&pJxncF7d@03-=htjc}^oFVd2<&Xd9-P?~WdI4% zAc~bEwF@*a>-|!N`&SVM-jc`V?-QV6kRam{&BXpc03J;r?Ol#BkN4F_O9o$ib!Tk0 zjcLmrbG9x$Ie;r!C&-Y}Th1>`THa7Uc%;WAF1E`T>iil=W&)dO_{Xz;eRz8$bkFPM zi^*QY=+#}w4j%FDoqTB1oA6>#+&e}H0<0cCD_XAWmbLd*^~;TV_@j;b8;-=Hx+;DZ z4_ENa`PtRjbUQwAlG%8mQ@p)Ss+0~)m0o-V-{d`AuKo(YIY^|(kAxk&!vj0dFEGm| zwL$E~bYeshl_N5!{zUXUKk@Fjh_th?{$)pFB3+Uc{LDeAJCpNV ztH;FdPc-VOLi*u&k$(X3b@%=Om_Gdn@O{!gRDp7SfM)vmX&dQYnZkjn)U%KVkiq0T)ehX#4&@!hg*4T^EW6LD>E?V5`K&(#END#Wg>@8xs)}HsGn|*+{EYlZ+94*NxyoGe%%cst zlS0zX@z4@&xr7Y#D_E|}DH3weOBmh3{{RXbJC*)e?_D$vL@LiS{*||q2cK{>H=pYE zjG!hy0I(V7Iz5J8+)p`O<3ql-y zdM!@&ZOwuC{*ikw&Ut&jO^MQa3%q9AJ`B1w!Azh@OymP!PR#(HNieFEV>=gVI`|LZT7~At!Gq2Z zVfJ;4OYXy*mfunB?!Mbqi^pI&B1AVIze}$wy3x%l@>)8DukDSn{ZZpdC^!(Eui|C0 zH$6t7kJbRje*F|e`2Iv@unI=@`5pa2FLKFGsI%!kmloqUW&@YoOp&muJmDRQd+=~^ zz_0KN%Uqe(s+F)1hM=Ncu^{9IvWk%*7&5?B7ivmiHGCd?StF%pTPug9A5KFICELPp zemA^`-kEi{r;_4f}JDOZFB%;)31^1qv4%y);IqE zf~%I*XFcJ&8cr4`n*RXqwSN93bW5u#;LpNhfS+s2H$2My0+T%IWqN$omcQ8iWE`fH z5Th31{3~ca@hmo1+ahI~IGxyLQ*9Q)BB3e<(XE#+JV)8sp9tHByIt1W(x<2LK8Y_N z(_Oz5ier>HCkZW9WV!Mwvb(8}p(Nljfn$=p&A~}L_PYY%UEr|!av&UR1lGxJ+LMIt zY`N9|FHLw|3K>VMn_c>f+2=oO3xM~ZQ>GSaM zY+0;dU$rdOTkoRlW2Ql|sqHMA&xU5lP*$a;zFxo19E+tq7k}I-95Ma-htG$hy)4F2 z&{rEqX$$GwPVHgGx{!u7Br;R$w2P|7lUJg1_Db_f8}j=o(kSEZR=z+MRy{=cOzw<& zmb76BJBZhM_QHhd9b=eh0=p;jRQ$3?HXn4EJ~CQWX}g-sp+>09({W%v#d1G^ATQ1R z?2r?sBA%=1w><`VS|8{8-Nu^PL19vX`VWFNmo+^5NMqsWq_3=qf~=~l%d!^P`jp91 z2qZXxjB{A#_QIr@0nMU+AHI0B|J3o36L&XJdU$v^QenULW*QQg^#3VjhDC+D?N^Mv z=3v@kJ`;7M3HTC(5C{FZGRGNEJbqjH!%^7qD`1sC&UU(8XJb?H+#?P5?(x?V@L@BE z8DMKI_vnRbyRq`G=*9$x6e%>A0;$Dg?!j=R0`lX+qMvTgUD)*_VEkA&k1#Sw+tbQ%1XDx zjmD}iZu|P}W_tk>oXqW?k+;IX`qBqRo#Sf-qNP9n9ohU3V3G~*LL=!O=VVIxQ~d4M z^XAo5*_p@X^DJr-_Rzzj(Eq@v@b20ZK^&WHMVkYEI1m4<4Q099RVs zrU=Y9jxviZ`gn|3bZHT78zZ(K>|*<|Eh}{8Hv3k#|_??UGGEy=Wq-Wk$R$RkFl^rE8=&TT#M%iGTR|kPl`f z@;$?_S96u=LxUt77zXe!AstNY(v+8-&K~7!t$d)Uei3;O$ABAHpW z>X(|m_jDbLdH{p?-DvBUG5^lrC-oMu7TS_Vj=Wv2E#M(nC(obXmwc*S37w0(t?~ly zapLnxiXb1DvK1mJhA7{{5)B_P((^5$@9S^O)iB|UGIUuan6iaUWkhb&Z6u6LdWRXZ zEV&dpkWB8(t?XVzvVf;SAM1GX5DpAe@ErW^vNfTn%M=1#J>`kkK$i z+E$02z=g{=4lb^p6lqgjCM_n=aq{cJL+Mz7pa;x{6(LU}RiC#Ui?u8rE08~KwUBa< zm@}~l*e#m1@PUB9iHXQlQF6Gw|6RI|;Z66i=8DL6pkxl5a%(3fCo2IV7ygd@C!1kw z(H)hBx#YPZ0bPUwp^ZpOQl%J#i~DP)y}X)obSB4Hc74Iaf|FZFR&_&XSqy9rMg$o~ z|1Gs?qslfCCT-!WCYFx@l)rt;pVjycO%IEmNC( zxzZe-F7x%>hTX^c{Ds+I9qK3Ydhhx`Zx(tMArKq?W^Wa z@vpT46re&rk}Vn;yfZ&|cB(2i+?T`;Lj9zf6T5ktrUKZRPy=CmyH3gd3(MgAlBaj2 z$L^GPFGfnis-RC!v6DU zSTE0lNmt)Am}5l>HC|2sR|qpZ;*WH2(0a4pqu*N$laJF5Rb+qi?8jTeBa>(}c7;Cw zcwy+`;ANtG7|Ei(SSd?tPNI8y+YpsyGD0h{;9)s;sD9E14V@wy-F=HV7xv_2T5N9< zUpywSd|+4I^ygV-33K@&t^S&Yj=yCeHm-8z`Qp*H`jDh<5~<_LPFO>V=^sh3Q?{e@ zc8wz5pieYPi_XO37pgE-gT7rNbi3+gfP(`xKYs( z&`LRlbH=2-dJNgMNf&LMKm7gd%ppJ*xs=u7rkP&?Hh^Onnw5{|n8Ytt82|4*o!Ant zmLR*xru+iS9Ubda%uFt}Ml?x=&TE_%dZojC1&to`);X5v9IdqQ1D_|>xiKdce-l5c z@w|VOw}{sWX-7BT^r(khm)&_fszqN=wzfIgWp`M&OdcwbM?+(iD|yG2&Jl!%y*xx| z9Y;9A>LbXBTW8z3L#IQIlVChG%8}!TSyEZGF1ykUg4ya=+SJtEH#1C%syH^YcW=#C zR!4=>q3b%baRg=zYdG(!(n%4y+sL1sdg7=Tq&uQJZ00W%`rzo>M8Ltzt|Cu%$3Fk6 zJ>j*(l+i$MK3#8kFOu;syeX&EVdh(M-)Wnl+m9dcn8H$mD-S1=4(2EAqa`%`Vj>N;&=#%6CbY4a+71uS=w>oPshzTx2f?uGO@ z0D`Ej?E~!gCS=@a2^1V%gj-taGd^;*Ke`A}$lmlLUNy*hZw`VCDtL<3 z=&Rn*B$UKWk8b}^wkeQ%XrcdP#ll(IB5i`|m^NNB{KEmH-$~W!AgJ9q)_VSR$tHI) zWfakG>IohKqw=_rcUI`SzG_^8Kl<`@+OsEJj9Z1fl+>=@IEYpjgop>%B9Tmi8Lor9 z9bpk0BW>)&y9e+2jOl-PXRXVY9g!kTL)8||-)cenZ8uoOyx(q@HmOYCRTMq0jBMd=K|1~9BYdTU{BYkR)x^KJHX zNIKFEG9KB~SS^g~)4h8MeE48eTmSf7SS_Zq0!a4BdCvgR!PK?JHIx}34Gae9qw2o# z&K2kyIZ%)rmJMbj(?qa21ldrsA4;uI$5Nvdbd(?RyL5g{iCse}d85k6O|iLJ$Dkt1 zGoX&+rN&?V-VxDBawf~`(Dt{WyegBw_NFLlx+%V**;&W1tLFxTch4rJ(;w(Q(zV!X ztue9;;}EJAM5USGu-Vr-8tRU6GNOG{+D3ZcsZwyNB$A{>=IK0Yx?FH@Xyv$Zpo^21Dh}Ddo!7;4(90J-NYwP}(`xhC?gSNvemqDYP zg;)k#6q9MFAsEPk7s`^~w8x#86kIEOvZ&Oydy5I(EK7609QT;0-lbp=B(16m^KM62 zs$z_uve=Fq!EFfZC@ursgTnw5dPa#v)#T4S;zrO!iDWDF!l#QGG zt4HvLer;-8qd9J9tY(ozAVXVxd=uQd>H_H1o12jJWJS6o_g%}ge7(g|3}Hx0hn3$> z$MTK7lr29JF-MzKIbQy>KTqw|Bpu1!^tv@ARG}e$;|@v8&1*_AH)Gd#A_$`z71QeJ z(CwPbt|9-#HeKj~W{lJ_g}GownXAW9Od%z0CCH{+6oXmd=DeDL#~y;-C4rle~HrH3S2{MQE=A zJ^iq+zYxd5y^!nrwrNGVNX+}7A&Z1prz4nrDuc2Yw#=L86Gy_qvy86|Am4J%mF(Rsy(7<6P40(dU!zx8YOt0@BAhmqmcWbK?l2AgH+dtKy%o zi`Mg-(pL{*v3GjyGbSSY)hQqIhTkGXscNn@fX7W-e|b5x&w_(_62-O}2(nK&H>@vd zfo0X!Yv`80x%j;Vz*)g?jA8vF z^-%D#_{RTLd|8=#oD>RfPu2QTN43=uyauUS>qL*NoR814_!`JICNpDSEwE;n>0oC@ zphG7-~111Teq_0+QYipLe%Sz`~Sf%>? zW`#u}qNS;&p)z4*;EL9-?;%Q!hS%q>vl`dW5pF1C=W}jK>-5|&PvlAxa^j`G%Oxnk zw%F9^Fvearm@~iGJQ6!srYR62Qw~P+2gYe5e}6HMcJ^C``8ha`=J;dyRpdcCJ8eCp zH`OPumzQy}R^+t6-b!#!)@B^S(nfbsLy`TB$&*68yYk{v5N$+RnMw~g=vBH*eyYhp z!kxlRa=w5jktj!%iL%tD&B%xg(tN0-%$sR{i)E3p$PRq2w-@M01-v~Rs3kvX{j%Xy z$tYFEhW^-Q#j4;saM`&+Gkj_TkXFXUO4eh?*W3aRe^_?J^;i^T*!Vr=`ym>4O^mV- zxVge;emRoeTG+J5L_88Yj_nY9806M85*fs^-)q^3<5XlBP#y?|AU1oyNwA!XjBOw# zZgA#GpaAz}S_I*b)rJ|R_7Zjrf4tL_2z+!TXVMKeHkSg%O$AXbj}ujKURUY(lL^9K zdL|tq8^1*3ZiW%D*E0g6!55`pn)cq;s^rMD3Tofk;J%mP()>wy49Wp${ z>BadL5^`RCDLPyxBMFO3TZ&tQc?Cx9-d=t|=Xg=t_>h`)H5!T7gXq}S;pmjZ>pWs% zc@=H@BE1-{M6xJdc*+p1f9CJUb;X-LG%Sjnxq@&9NPx$k*E2l>%`93|p1%zNKW31Z z$S=;|?3LmtC=~l1i%fZA15>CB3z$~&LGIJH69H_HTLG7ZbkbGyuh1&NXV$v{)`S|h z^Yosdm3b>Gq}o}z>zz*a*;_^mXi2|oGC?$%e@$~~K4IV;2}vXnxHG>V%NOq3ZnVi% z1W8n4^E}%*^5)$ANN=%3y*;SJyIo(atw4R;P>_2?5V!Ch$=K<{S~nSYAi6uYL?g6p z)1vpxSYlfMJzLT~HUu|LDc|C1F@Mj%xGmf!nw!)8&iZR-==MDcM9*#K-#b+^w2$na z8<~cCOv`Hs$67*8BL`GNv=OrlZ1M@c`CivS8pxHJQI{N6K&Ttd7B_;iG;y8qaz8*@q z=F1T5awlHhdNSS5fBw7mdSC|mmZ3iiQEa;u5izZJf_KxbIg_0%AHMnkl#j_YGOE8q zc}diJAbETzXB%R8;q;|C=_8`&$FPmw2YWFi=EUSkb?TS+z17QewSDw*<^g$J;8Q4r zR}ID1DHz{@jWg`LQnT{CXYSfZPL}2$h#PBDDqqa#V;f#pO9`xHb^6BQ1Rp7dO0}o9 z6o4(RQ(cipKSY+=LB;Nt3&|w!62FcIjeJ%$#nR^lKkXFl3HqAgGqlr|$CqpVssF}NPR z1siihg{^Fl1(il#a1n{w`DTghQUHA10s^`!LA0=;b;|Kg9KF?}w^I=KO0C+-eE?g{ z)s?BCTJo)|jybDy=ET8AsMFj1HM($NIg)wM?Q}R6PMdl4s^kC_5O>KFs`Ss=7?Lkc z^)0<&KN5N6j`M315?Q@B)zv3`X36-Mz(XxiX-t6boFn~J8+*zTC-cDCj^#f4y@ zu56|rvsJJe1z)mPgMzKoqd*bU)S56!N4J) zOpFbmcUYe_)(U!LlSeD2qf}5E4<@{r&XDhr^7dg*Dy4 zohLVTZ`h~7G|E@P0E?8q$}dW%oBg?{M^ge#4t#;bI~pf~=*zS~UpgYmd%{2`oN19> zm6SgikihZ7>}IFzwkA$bu&HepjB=Q=Y$(P(eyKJ-#f=tJiG3Q_AQjxQ$@#u7XTo-t zyk^GE1>r>u^8reQ_WO5}CB_SaaonHQ2WRPKIQOiT3!GE_ z7RrJWNiRv-`IDQkX-a)f;5o40lEib67;%uYHB_&j=wkGcKP#IHswx^+heih8yDl}% zgLKgeGH!8gmY|0kB(<4$Te3a=txp#{NI%-vHkvWyOq8dqvY%oUoLSK&4Si+J5D_{M znU8K-?DhLbFQx(<&Dbb#h9fyA#Xg*{Gn&hZ007i4-f!?(C%(UQDQ^Z)i!&T$3ici( z5}^{-#i<5A0G?#u%FFv{{Ak27d|h$Gy4pgNnII7qgn{rbv76A}{!9zk)CHekc$SUe zQ=i|0#ef?XG1&`HomQxrVRcTw{mU=^RczSHVq>EmxJcJy?-HfKHekn@lvQ=uu%hSo zm6Z)x6xZCmuD`@H_E5!UqTu*`7Bw7W$;v=av@ITJs4xk;76=^16kJhfUrBtzg$4PD z!OZ|bu;^Ci_?3s!_f?%X1M_1JkNXe5LF-!2lOQJKW)T1bShTdaa^o%wF0vh7IC>BSMtc)RK${oh{cRH-$XOdwg#TO4h-3SddT9sD=}ayr?IEMG#O6&qXUO;wl1vUD8~ z4jw9({7S?LC7Xu(v(%~z$_B)ZWw)FozcwqJVJ^pV?UU=1RX(u~JBsSuyPTnE$U3iR z*wk$XFp`T<-l4(n7Kvn$KaY!?{a-2Fw75lWR(;jk zj}tbMYQA)A>NrjhFB$Hyb0Q45+3&nN3XFDeAA$oSUseOX%tbR{bDLz)NoEIEIp4*q z(Hqr@)l6}Bk{HDEFI^^qUr}b>-_sLz9Q@@>Q(W6p*(W)6N-<|J1g3)f+|7sAj!r^I zJ)>~;(U=oKLz!{Hi#~G}OLR``l6@)z@HMl-f=!&n3Qf!O$`mh$YW7L| zK%5<~gj3kk8h+O1-Rz#V-Xb?A^-frOiZcWxPNjW5lDsPr5jy508{_h+SW2rGSn*-J z9^!{Gi=(jCiP6UzzV)Pa%lxDvWuxS^=@YxM@y@z(7|j{~-f-z-`5&PG>a^r}aWg*Z z4%ELa-(Wb?rCZ{EU!)`PfATpH?4JJC_{+@_C-`rsPTl2Rze|ht|C>jA`hOgcssAAs zdeQ#}7~M2{i;i(H|I_|nrPB)*{@_hYylW4JCzVYj z61Cf@MjFnUr*I~fQvn{1@4Y?y&_c}Z*^km2Ea*@jDK1PsWT(KKzhuWhYJ?jomfm^o zBd|Gt=G^qBds3)x&hgooFc=i-)tdy8xTLKJy0Q65OML%n%P1odC#TjlE6j;Q2xJ`CM3qZ{369C#VHlXJ zkD}*VBHD3|J*U?)UhH&u0y42~;Iih#*8VH^nuVZ;Kpw{62Q59@a|Mp1F-usU^>P`p zhcMIQaM%J1PG@UFhlm4%@ zxIN_4#UR+)!j)!8j#7PHR73ay<>g;-i76Lzwe237Jho`Hv@CBU+t13ogiKq$gTsEL z|2E&Iu-74nNNk>6ETJDuEO+)xKF4vf^oVY`@ppZ`zO*?KG;{P^WqiQGSRoMx!qKx6 z_oXChA1HTaL@si#GgaHU<$DaXuE@ z()sP$nCaCn3!y#aVxDFE&umI>h_g|zdgfbz@au3zAq!0{*`TtKHpiuBzwHd5Ke@^U znp)0@;$@$6@fZ^y;+Lzpx`55{O(Sf>!IwLTPMMsX8Zk)`@mE-5e(xt-;%!-jDsO7F zmr!b+XaDlQTSf(+T1n(8+Xq3d83C@sp>H})#6QX?FJ?&6ee+|xJ?X32eYswzsxl!X z;s|p8LhJkZ6WQ?UGSbl40LEOX(Sc!{t2j=lb7YCxf71KMFE+mGHpghVeb8z)vFkP9 z%nr$!r11JzUuSkyLfgq$_~ptd1NXsvo>k#Zek8ALkR5Z4EI)-%%#RIh$;KbXNb?G! z)lZ+17s$S9AY-)~I!+j~#6)#eFYBdPgSk{HSey7NG^@&P z`UI?rx(xmcy`Ij+bN(LKjoFM2)1{PGh@xDHf(=PHkha^_*5{J$k!iKlXM3r9GqQE0 zKC1Q?O|4UGe_0Fo!&!;prVgy7;TB=tot&Vio)i&WP^hdSdOMGTFRR1hIRS9QTTcx$ zyHa%S-QhW$>P-k-XLSn%v*R7Nw>HS#(0c8St4+GG*cRnpJgD~GST0|OT|h@Sfld-S z4<3Bd{k;9%_3?TBndw3Wzbxg0anQV*f`AU@(!K`Ft+_-g%6EH9YWhhm?i%^AKIWM# z=w}KJs_Wp&Dxs@PRdYNvWC*e5?z;Mdg)H^g3b>5IcZTVVqJg4Qmgw!fc6w8t@m)|vFk0jZEDzQ!> zk!6O+?JP>w(LrTqxb{t~+Suq-Mv}c<-0p-Js$Dx##(PK@)2KqPH@)J{4d#s`vmB<7I(Zuq zP^9)}_L!4dIf0ELLbO%wuIgC5W>Ysmw%sm()X@CxD>INix4SZf`IofG<^jG)cJ`$b z-8Gj%Z@7^ASM`;oIzk4CMvC_ft>D+P5f%F77eSt#5s!St=IR=fj4kA3NUUcnx~`B* z15CIzBGBH}fp$rs`+0UIu$;3F!NjcvM>6^ zGX#npYhfw}a&10iyVVu*CVX{aCfGcb0V8el@w^bU4?pc7Wy#lfb>uT z2DdEM_8hbhbeQhTnn82;DLA^^k*}8t%Ni6zNJHSMIul47P0MYAuMKU1md{LHg+_5) z{qfv#X0yV{%q)H$YJG(%#cat_;4ywDq2l$t$qJWsQC`i5{@8Zr4t5^uoJp{j!OnAG zZr^^3E65b9DTmaLoA0lFoUNK0^S&fmP$u$=NA5Y z1XF=r?Bl^*?u!I{r_p;?Ee=tCGK5a?{&tx7vOj0J@Hj| zNwbS2mL4+ST9L(XNLE4A5n+t{ea>mif@wP+Cs)&prx z9g~N6>lN;C2hygBDAV(M+qO4zy}lub5wK?p*luW4U^%YKRasIt{vVD`LG zjKB%8%8>1g&oJS2gfGQauFh=A8*wQqsbalMW|simcoill!0x=mZzs_=h_;t*#zVeF zMyC^p{f1JkAWU2~)|(fo%DDPlg1eN}xa7ld^jQUu1Ad`OvsjdL)hxDG`$F(R^e6RN zM`Eo70>lY|+CQIab=Pz-U!-{fc}kTwb?dS3fpcDw!+_b+qxbcCIC1<8Y@#ca&-}NE zm&-}lLDG_bMqcE#ZN(y=!XWDr%W~0D&7kRouep}rADslhv^`>j7jP}QrRwSwn90!6 z3tp9?mpW%P&%&4KJ%MNs-sV^upvo%>p_N>iRq)g}`J}HiPsj1avEAvXw*XxI0 z@66}~l?e8CEv9OTW?&tST)$&7)wi z3AQBN!6x9hrxLP=Ox(Ge=I_$=M>zRe-)Gf~!0{P*#S`n+WZC@NL_kKI<)s|i$~rLS z`ozT>?n3$+mY@Dv_M1@}azq=Ld!cXB8qnM^ckU^kf5MH(<7|av=7RY#ch;BZBK%Q( z5e}boYr6(7Ti<7wzzERL$U|=(t7Ut)!x)Bf&01K{MrW6O=!_dI?^C8d*C<2cftp1} zc0#Rs@|_oq0FLF~G*$QMQ0Gm&VZK%^xUzO(coA}<8HcUOszjy=i)&bR>GoB8^-Z8^ zy=r2J9ewwNi<>C?JbB&8py{us>rXsMqQK9?U{;v=PJf3mY@5?e(MQC*SM8 z&5>Je+;oGqCc5)B#4y|yU22YrZVZ_f+AW%n2$@wI$XTm7$TB zRIDm#$Dp-FHTfhQ^`?}8pqsAR{8VOr?qTPpQ;r|Y& z9JPR658xdhmQR(_c?N7);;3W7P|rJKIJ{Ymb;mEG*aOBk*1vJG4ow&&)t8>T+!SQO zWmcMJ)5WpGr6fvyfraFKpCahWG=1PkQ>sq*MsMd7gqr332QaN?tU_(Ay+8j$5E;V2LrlCwdEU(_fe!80e&pX%h)7meGx62lsTAGBnx~;3N9c|>j z?Lcs;@gUf~dW7{jR`8dmkgwOoS#ADJ?Z|2)iiotiY!WR^DHX{+VmFEuxb_e+x7`~@ zRNUBrW(uk{+PmN4!enc5G8xc6NeT@q+dS5!VKu2Y4!fVd`T0~pZX~;viBFew3Bs=t z5b+DlwRu9f@II0uboi;}&&7a|FgW(qaq1v|CR$_4w*yS3uu*q(w3gxPI#P1_G5J!na0)BY!#1hP5=DQ3dsKvU-#c+ zng6vbm;L^WroYs&mL^|q7VZ_prJ?`5Ve-F&k%e{A+}2iUwa}4UgxxNyLh^M=@QTzJ zoCtiri#a-@Q3ml5nszb`I)?pTKE;N*x<|+dpjqS zKem0LInU>>t7QJeF?+lb;t5j)Nt&_-qtbgS$a&{TiC$#);>y>IYxB5_KhwiTxSNxa zuSeU;i$Vs_W6C4wIKY8V0QGTmM!3~Wkk$ljRZ*yaWUTK4u}bdtx^xpv8ZAd~_h*NR zkLl5rJ|JhPa>$-s;}i^gmWAK*YKqIjz!q0bBFRN5a%|&%D&vAX{GCLCDv(helD07t z`4~Jyog5W?$8upKx|YWXW82ZL?Cq+!v3&=`b{m_oW4(6l?T&(HVHg0O^j8ulH|Nng z#tQEkj-J7g;$GTrHYjEozP2AB7Esw7O z#%7bhwXqA=1HGyxn22OTj&>6~daa%%YmtS`efg6M;APT7K5{Oq_~BFv7q zEqn5T;NyhWr%&(mvn+Q$i3q%%*BRTwm@c1<12<9U7iq+qriGK^$=NnO%KiObW=1g; zy}8&=1B#m?U9Xb2VL1;Q77x2%Vm~lP^*4<8DS8Td-I*xuk=w7qs}%Y{au{ADJpY|h zepo=;l38-4ir^vVzD2(28&uO@jR{emTFuj4t)hd-(g%hiq=wL@JBcFl?Td?+i|cYC z-qJ5~Jd^XBCf}P%hF{+PrcG{ZvwR*Kb_(A&u9}!e`Wij5@EeRm@(^h0xZ){hYPR4- zsbQhu^~N`_&Kqa%{CkR|ty<qqTEw@aoY+0E5fhxfs#99u3m&+v+ct&8`>E^)rfpROa?M?gCZu(T zJxlXeWtG=rQyr}hhM9-7a4taiS>b`%bfPC*?O<=2gUuYY&Zh%bQ$M7&jxGaAU>Ey1 zo+$nLa?SHYEwN`|BokF$Zw+#){`99Fs`FZ4X&u)+4)gzwz4w4>vT4_agMbtP0YT|S zf)JWgrT3Nq0Ya0mQUe4C9R#FGkrE)GhH65QCP;50NEgu1q^Wf2RS>cK`QG>2d%t^s zXRm*+z4!Ug`PVsXJ!>*+J@-sz=9x9~Jab?7bxHP`Yv1Y=ue31*hYHFrTLXwK`$44M z70~>v-mV%^P1-s(+&Pxx8>k|t|Pfjm(^f(k=RG#w)Qlg{_S?p@?vMF@J}6G zhWUi`46F70+~stE^l44KzXauTI+R>n`cm1P+7#aQvp8K*<*iG)A54QV#m}}_Eg{{= zvdw2obyB2sV2tKZd?OdX`cCw;c8PQ-upI_!KHWZT)QpO&u9m^!z}{P9Z@3;zGUh9P zLf9_}junV3Q>Al+>RLJYvcitg6$a!CsSgIZ)T8kl*W0b8zca8&<)E z8zcT8BYx^`S!EqE?yipYpK=%a?Nyc>dh&dz2fW*E=3D-H{#HXkrk}jT{__AjvQksrAd~M7n*=~Y z$59_tR(u~1}}I5jyJ8^8|D`jqCHft zn_0cZe5{hn22CPg(uxx0HgQaGnDYK7*<0L z<~RQ>I*YZ1R_U^4PUJJ*9|*WPn!x>CU5Q3(B3B?vQTv z*~$0RlzcE^RBL4~3o-hlO6tNe_IkcXB(1SP%p%u%Ldc%JbYZIBRCa$s z?CGPIg8X`frjz~XBsV3YiM_BZ)5oFUlZMQV*lja$l_=0%ub?Y(0Fej}lC6fQ z@yrnEG~Tw14yJ5zI!(qlEz_x|2NJdCsQwJa`Tx^S4~t$RQH>&@=$>M)9_B3NcFQR* z*3$z+*o9$}B>-K3W4c={bH&NQn_uJ1Lr^BNqdZtoJn+(^{FMlB_reO7^ag6j5UP=+ z;^9B2+o6e!ITf%}^}taup+zwK3SJqz^HN;+>zZ=plRBc9J1^oG)1u}YqN5b)m{i#E zMVs=ijM6H7Bd0sscAe6gL)E9c7A}MWzVz;cTE;|_=!@B+{L*T>n9;Zm*5e9Mtn%u> zuJ~%B=!J11?-;D4owMov&<7$aG>XV)Ax73=T|7?Wvq!?`zSz z{YK7Jwkb8xFqm4<;s-8q{acqjN89X_GDmBGDgWmS<2>tZznG&*9G{PPmEVUn8{I}5 zt@_D@7GL(J$h%+cpZvfSPbrr~HOLfIYf(6Hq;v%reLZuKSrKc(HrS}CS=&z0*3}(z zF*7$U5*4dFnKaS$ACW};sB|zeqZODAKAp)0FU=l_X5Ga#`-F!+^5bPVx*jJNZC-K- zynixACGEN9?DNSxhc#X@Il>@uCwqsy(%Pvpc9Ybf_CbA-B-SWI`w7Z)9WC&t5)gJ? ztzcvMAcQP0T5>)>@@o8;>>N{7YZD`urYc{9%@@0C+9D&A;n~vUpzHi$r}0$qD7^?* z4?}5VJQ>ZZB0_0R;9^#oH&CH@kr(Z`a*(8M*qn|FTydJ9Hpxf?g1pgFWuWJ#6`P)t~r2h?o|;EiE5{elsMF zj^pIOrI%@6j-ZCXys@7Vw)vN-;f(^2JT<6ql+36jBgr7ClB7LcEiq4h7=pquVWYH> z_Nst%z|fZauAsP}nt4e~#zrEjK|~Nl#cQj^=`Lhso_|THfBq&}Oa_+*1P%ue_$ARR zHdR_9aSC32m}(9s9pSS1xajE0)qU36O}MKxdT$GDNeka%3R)!wW>lb9zn{Y zuC0VQQ}@m1lN}f015ocq;xI5a+d% znEveV?ncZ%2MGSBGyfgD+J8Dn|8wd8CN9+kz4w@c1h8~fbYOrDMq-)%QaZ%%o4H$4 zV`8PyH+S8OKfj@jH9F#`c+izKib9@q16ASIV9)!6ULhQ&RjA7TNXtcFm8a864hOjb zf23EKp8sr2z4zl*{vT=7zqT%_gVfI7`voq(r$oYF zQOfs@%0z-q(M745iWMVVX8eMDYpFs$0~j!b^4wt(-$6j);2{w@9!_rs8vmkU(Ija+>A8-ur2$; zq!j;uZ)*SFK_E_+|Jj4^t$b(z389$tH6i3Ny{k$-RhG`zO!-p-7S5pZZ&okA+rKu) zPo~Z-lw5ut7|vR(Sw7#a{P)jN|4RU`{|Y$luVw!cDE43IRyiI_yn>cY{WK9pp{ zWdq|E_Mef``1bs|z8c{~7z|&8Tjk(P4qN8_A?g1c@V@;w;KdC0k??Q80pZ5?@yGkp z6-i%OC0}*rYqcjlvuR1$aP*XFQ1PM?lV1r!gglvp23Ai6Rh`vl*$JGhN78L8HNJUp zRa3*~x)ey(m(!r?>eWis=kRruV(S z!`R3R9uS=ZP`y49kUcdWNnCN9dwaTYD8Oj_&79zAAuXG|1osksW<0dnyl8E{pjXZN z=DU!t(HYy1Pj621o;~K5**@vIm8Y;FfGR5)479$VuO;u>V$^^2)0%bV*S*7#mDT{i z_BS_ayM!M!i9C`kFBY&mV`Wvzf_(CoKJ9{kR9eQIf8PvSx&DoDY_!L$pZxXRl(%s+ z70sNk&p^VTI-?Bjh30OKhPkYP_UH{+>}Wv7WMy_Ht$q%#1%4=;J0L2R#`EQW16-O2 zuN3e0cj&mE%eA~Qc)tNGIsCvN-N(3s*aR-=gjZ}YW$e^s-`efA7sM)f>d+gu^|oJ1 zpw;(ljrE%>( zs`y=J@Mr9%gq%rD-Tfio+^?MpZ1*h3!Z`eX15U(k^P1x6X3bno9ZxR}xU8mNI~=%U z?eJp3_H6o&!D;7Lm)3esEyOHhUocmoS*ZwPP-t2i`!}rl-uV&2y~CEhwNYjTQNTu1 z{q45T3)AhPB_b;vn~IO>%OKE^Ox%_6~wl zt*G@WZgMtg?<{m`WR;DxjD>&y1S_+%IO-JdYdm^z-ynC>Eodl>Yek?@q@}K+S&^EO zl;w22ix>0Ug&)&Cbo;+T8wKmeBuVgZ{gU|95w++I!bt zW_U;bkv)HCvaR&z&GAo(hfvNINOW-Ht@Ds&ce7m|zd?gO^1<}_Dp%+?XaL}ZxypMh z^QF(kBFIj|b*1ZOLs^pN-O0LJ{Pk)cQuA?we&zh4&%89khCX>>q_{Cd?#`JPuW_LP9JAxt(?qH9}eDwOk0s9^DxYC*}6T5Gkc$D^(aLfnZIc#>Au|j z*#?p2$rI7Ikh?ShY&k@Nt^nf&pDUo*5q zKa3To5%G;E+x{D1)nN`CQxd|gtK71&6+6Ga2#+CfCVR!CVs9zGtj$&HF_JIH%UBKn zS;%;}Q^3)=$fH1uFV1t#p|wh}v%Kd;B%(wf98?4yZEX_!(cWf}VR){d6aGSlQBhN( z%!AQc@17;~1GtbEbubo`3LNI z`ve7PwPa5M*&pfHZtV`NQJ+>cBOPD%r7;fnaABK2f?)OenlgX`z}KTP|Fjvd49L-= z+7SjucFzeeYFM_xTfgzpqVj59H5^&;RMcGs(`If=0$}cfOwf2f?@Hsbry-~TWR<7~ zHe#8iRKQ;Kx7$zwZuf2Z)mRa=(T=NaE(ImT>$iMoL(H(O$Krq}=Gd}_0J*`V8aJ=u z!DR2Qrg+42pdkK3Du%nv&*vz5PmB(eGk`g;MyEpY!EeLmmccfVpZIn~UXgxASqEuSQ83 zvqrk6{VQ9jy=Lg@`V&v>DWajrCn4kI{FWkF;bX7j(;h(H4s-;hr4p9^zV+8H5CzCC=ytD7;wMIEp}q< zM!bXWGT)^UsxJWoFmB|`BnCt=82s&512$m1&L?eiHFA>BavROwVDZb~Lu)%_*PGaW zKZ!EaS+;mSzx^h63%_%nWtMRy_2=0KO4NNkyk{I?VA#8Wy;K$M>5P=wQ!$v5HfFs( z+>|Sh?ML%xnJnJ^)LYcj9D^DkCJJ4J04wuW+qJ_x+o9*i6V!9Gt)dACC0;OcgOZIf zIPeXs{Syi9%a>o7-n4U&T;n>w=|9`fS;BW%r0yIXpn(_2Z0Z^8-l{%5W2-6Y@rh+S5^K^nB)>AXX=fE~>bZzM1k?}w%)a(W;4b!& zwq%Mk)`69%rM_3IwE`7vx4m6uwe!N_I^kjzG{a?Nf(P+aQE>qy3&RwuvTBqVG2ND3 zMjyLIm*QU(H(2v@Z*os^JwAI|#0UV)Y z3$dN>{-|fFI96L`O6{tT=@Ov1lG@%-pCdxvfqCS>p7m2zsH97P{&k!cZ~;T>L*%w> z6m=oHYU+2B5>xbm&&7l;MtCAf3hEpReQaMLnd%}V`oiQ|br*2)lT20a@ zJ7;cmorzI*OhQKa(8NL}@t;Ja{$HUz|A^vA_zhT;`<44jXoEahJfCkTGi*8&^>fJN+UsbkS8_ZD`cg+`Buxry}`}} zv7^O^^1AF`FrselMYquR{!VI)%PsH(S6B~``uoBzl_6cJU%AdBQH4n(FGj6dGSN z(LGm=1{H8S&3a|-9NHwJ0OXU^FJ^(?IB0fl!-T%Bt@{m-x}M*DIE8#Ue7Cip0dDoy zoJ0K*3`5)B%^23TwRq4>+1!(2sBayURXiNj5kD5Q>7=Xdi%Wuq$+SB#U6H_Xr!DnGv&btE(!Y^BYJS{>K)KI$@fcGJPfBMY7xNT#U~h+?d9fU_9lWXvgWLV5!L zu{F-}T_opdCYk5kV=s^d<58%o`s<$YD&-vuIAlCH{iHvqfHi7>^4I9yw>!2NW1nXj zI8T)CMwdHU1t=41SuHd57KQ6ZHBYWzwx2A5nCUNW;5!SXKqjjBU-UZSjPzP{8#Bugbc;9 z)y))M`&;iYJp>V@E*;S3Ix()#IMlVuq`FC+4SzAb%rim*xt zvi?#eC$eSqk(Thiqct(Yl5lpL_oKiXil@Elc+sK>eST;I39vaO=eSRGgGAFug|Xhb zgZx|#n$P#;h4|v}#dZzerB<+0eAF&TUV0;j&wD#PACXDQBae=HHqtM%*(FrjLBjAM zRF7jc^vZGM05t97-q+Ay-?ulx1xA}GLMun^9<4SzzWM0~W)+z^f`EtW);ze|`>Yq+ zyS=O5bUUFf*0s%7tUSqYIT$zmfwGIdD%G`DxqZ&3yx*=~vm zcUVJ=i|C=ND`8tD;m~LGU0fle(>B2}=B<=S5&`V&7Uq&-Abao(9OA#W-YLE@uv$X( zIPI87OPWK|HG6DlGP3R>JC(F~`uNP2xiHRpsnKq&&$=Gl0=DUS-{W1PL{>Q6e1abr zKE?Ix% zPo?h-C}s0v5MlPsxNP0cOH%wrmoY2+zza2F>Ex_P(Nl%BqixO^rri(exN;ilbTHLf zMqyi9u6f(hbW^@~zxa_qZ3_2`IkJtBfZ!f?Po|`nqDEoxY2b6&R|0~OO3t+3*RD^u z-hvfL;Bf8&K=R0P;JJm@-#%I46C54T%guGJU2~uOXBlc4iNkJAqGl&!*ba!kcd$>P z;*dEpen{T`2syht@PL4pi8*15(g}@hGVnL8m`Ohwxa+rcdE?N7i_dxG7O-X1=lYW# zh@HE6Nk-aAhSl^hgQe!4(+m27b2p|#Ik8PPbWusQz-(v0WSO0gK9YNuVA%=|ApgF0 z`IC^LTR4+HKTj1Fdz&r&YCLo2vhbCe!K%AlyApHT!qZuNDA=p#4V;-uPnu23Y(I`= zf7ThY?eJc%PH5HBk2Sn;O`HT|6hz|)q~&=;?&5PUrN8Op`0~vS%BO{#G&ZejvYCwe z@+pf19h=}nM4(^gN2m3C@m~FNsYIYonq#}c%Z^ELa<|l2Un@?@!ox@IJGJTCQnQpc z&8ve5nNN8=c1Bj6H*1`qb#>(KfuP64gATb*vk&*ls!>4-6@Pww6(%msa5mtE}{F%3Gf$kWc@FbmT;+9sYoGJ@PK$}f5zSr z^UIY$^O?&wld(*d=xb@KrX)nLr+fGIy_F`!#D`an?l;ce<4)fH2KcM|B_GT#ZikxR zlZwLKN%rLU4jN?rq5G`P-dTZ>!vkN|^VDr{|NiISfKm5S0ke>e)9Q!60ixc&a#i-q z{*tfd+o=suo+&z#!&V0qS?wiLd%BcZzkG3m7U6I6WzUY|uxW*F*!+5*cLrXV*FDZ` zd2GOaX7Vptic2V>P5xBWGe^Y(0G4~ zy2ozQw~uD7Za(|9^_T3?Ej}fnqNSRVQ~gTbcOt?6Z@^$}l1_lhkkgaNmBcUTq>Pon z6|enEnZINY=S)gC&Ay9`hDL_R&D~e31}uU3sMU^cW<6cK!lZW7ca9NCkCMO_@(7PA zgY)mbGH@0AVv5jGb`*3tmM$F5dwTaP5zqnC|oNeIy(Ih{h_iO9+*Q^ zHkeD!_(A-J{PW?+7#>ah1`wZO<>02pW(W7Hw$L--nSZYrX@o+9&p&^T7pxH{++SLW zb6=Bxvr?g+m;Fw_zq&5+n_%vdw8R#x#;|&{CnNo{_nHo}KeTjAHal*NFPwk0_;Ska zWD_fgSA-2B54j)<$R9*vDfL91W*~`axWR(eH!TtfkarEQ{JQQp zV09)Fc_q;|LCno6G1bl6@q$UUws7`>OYYd|iN)^I+0i+lfu|gYhqaKu48F;~JXbsY z3HRVhDWVXX8);grWx$WJN>n(Tu>SSvHYzoN8Y+rk zYUOZc&e{FA3&Z^NR6CvFFrt2n$f&ByvS=CUftmlib)6PXPg4unwipc_epox^zirQ7 z32O<5Q71qg^Z7>Fa*qN&_6_t6%tTMjJ~9u@Ia%FooiI={-7mO&7TkGu(bvM1I?z zsh}9FVx&zgRt#u?CX(JT)yK%-uchEVdtBBA&xf?8ZK&ckZkjN_VwJbp^`7d%g=B}( z-V`0VDbhVsO?LjV7<|@s!a+v9E>O^60IBANVG4YIOTn;66oe#!UjaiR_!OdBlzU<8 zk&tS-(BLor#xvzoN3(Ws9=OUA^;r^Mrm5mBeEb5+#HrkS_lw;TvI;RPM6~=Kvjg8) zBqT-i$;18tjXnM*D>bX>XA$Vgbi+lJhn|2D$T*eK~nA+`b9>nnh$I3gwT%}LLMFSo?b`=a*a5mm>0nPpOb%7y0H1d zomC%R5FJ_PGY!=k$Cz-63|A{5#JIBkjEFHb8?^-ew14%=eZV z8hyTwT9;I2mslyU$a=?t&}2ZTp}fP;*9et^`CP*9t^9**%Jd8XRFg%R+gzjRwLMji z!S6u&sq!wNMj-u(n~@O5;0Y;e^Tvx+!7~b;f=B7>2s+u!Y^xr|MmSWL%+t3SB~VnI zqLWWCX9`C5tknqFs)aT1_chUNLJ|Ol4+xK`GymCZ^WW-}sR>LWItI|dRYP?axFWWYo{!I zBo?V|G%*YEKBh-T=tKzYRj=H2^+BYO3P;m@&aT0yCCLy*ihcv0%7dZahWSW&!?e z6STKx;IaIMR3V>%z~F@T$ERXz?k*Y?84Lp-eAHYqO&fmoo$UNP0MpCYx@4;D$E!O= zXxnefU7kBy_%0PacU6*AcDtqf%z_hl&IVW3&b4jN^bC-KCVgIYeqd8p574{qbAkt= zye|!pt6zp88!esJyspihpiqZS4Q*dgQ6=h_^y}8|o<&KBcg^p(kNf?-A@kdh-sQA> zOm{5O@sDGN_ayVGwqPG9FJUcgkE`ny%ZD|;wY?VwYhd4SNR>{L?BU4DeEb8F_KHwR8*=iEM1Pd`*E8^u6rq;y8_a<2c$KK~ z#4z$3K;ZtlS)pwD>JaGllL!uZ-lW1m&6;ML;h#>JMf9H=kS8%GML`vtn6rivDK=Rv zi+l~uRvI>C>X#vRz!ZzEwT2Idq3`e7DA>syEGiP(SpxIiZ(AB2i%&K!$0WEIo4QDs zHC5lkA%k$LX+==CM#QTORnF}z^5q-+qhh|hQKKi9$8pK2tl|1845);03)}>_&pT4 zi*++K8>bN=$MFXnr(u)p^4TvclV2Z6y*`p|pFM2*nS-77It#qH>mL4PpJ=M%<|^J} zghJz*I!`GOAygmsVK-OE48~g2)lwLn$)xoZ^cltA zG~&)Sagoloerntefq_;0y;7+LQnJT|^XF%N8K@i(XUxKFA|1}r$l0%(t-k?Vi^Nkb z_YdF12tV_lWTyh*VQwasI+cZ2dzsgMI635ayc!AaH+LBHhcfS@I-a`^;tfZVwuK&AC`Mo| z)tei4DW0UI$`^-)+&C&nN!@b4Es{ zMrL{nwN5WCsubAx#__M5j_DC0p|7dwul86AzZ1u9N_tHY;VHsP2}1_}Xfo`^yRQe! zq;TJ~y5c$L*FK^Iy8{?+_LwPLwgmUqjt1<=&W|*kL13>GFa8d>4gTH&TlEn84VWC? z$SWzNKQCWn3g`^(SF$^^Cv;vybGdC?UA)0NSu*|IlVdh9!&|IOztlXA6p?aji2Fza z5YSoS=;COpZTXsZE_vmJ8P`Kw?d)9{w&`e$<9&Q@1f_i3;^t)0+PB1>-Qk~JIb4!j z(>I6I9m{DNmZ;VWl~SOK!r3}BtS3s^@i3u zg@g&pr3lqY-s-z7Wo_bP6(=62Y09tC4(TsKl~6p(e`%H3@=%Y_ST39Y+6{knvkf&H zQ8{vvXa7sO5pttTxD!v2*ZpF#WYHrv&wWgOf`L8E3(eHP_yKYvA_4+(tjQV~pH0ul zi+brU3jlRr>bB{an!l%M_-?&37E27-EN5b*ro*kCA@_GG)ViB{j_;)lXeAG}v<7A_ zue!0)h>C3rJk~K*8z}fzt@Y~3ZI8K+;8;=NH68taiTQ`lS+KG@MN5+6J`)V)*49mfqXFqHHHs9{)S_JX2+xME5Q-NS{O6^4>J4o_%Rd#~g_xdl zr{1-?;vl?+; zznJv9_2G#PJ(pu8mcuHmylRiiyhtbC&%ALgGN`?Nt;8ocPfC6vCUf|bo@klS{>HkBRPwXV+W~CU@~eU^e=o!KuW@XL4-?YbN(&mu}{!!`u;c6rw`r9T&7w2 zB~fnOD_27DR5gP~(#tZ3;b<{bSHSOM}0hS1d{HH^;Cok z3Q4*Wxfy;E7<2V}@pnZhU(D6Bn>@ElkI=DkBlTjN(ye_In*+xt0*vfml}MQ^hg8jxinH4mT&B!LVF30q-}XJuP0F7mi&Oq>IF4AB5+|p zm9304&dXR-0w(HJ(O2IKyN48{3Rdejf5Es<5Tvy(FEjV{C3M2jT(B=hwlC4{s64zPhI4()f#F`DtPR*22P5W%7~G z4D8075+jN2Z>$A5Bw~uhr zZYEm2;&k#Kv9fcyR#w9!v5=v6NE})2$(B*@$O6j>2;GvooMn8SZAI|5-ymdMS|bb- zkyJS_Z}LIp?!68xr?<|k$lHU~^-)Ij7j6RTkVcFkz$9jq&F`1ePeIwI&9q%>>tE$X z$c`OZIGQtXAS$7edti2Yb8zSzkSd7H{0<2j z5+REN?{u3V0?8Z3lxI}Dpo1c3-1aM%NHoYUDK(z{ z&w200hw^Y08KFpk5fm`@FFX-ygG!X;%5X!}4-j5i>{glRY9SaM6Uh*`Kk#TSdhZ`ixik){%(oF}@@kNPX>Wk{8FJoc_FV*_Hs2%@#BNX{YY7UEpt20XA z1wWIl8#w*boiO}A{S6ylM?KN}0&KKJ-F>rOqq@zM9VrZwHP66uxIAu&K6~ec3#Nv1 zssF9}X{(?JMe;EGrR-7AKi5>n9^CBjv!H%bj<llSKuoBI4bx^g9QTYfl{zln| zMnAAZE=@x!uL0kn#hg)S_Yw0cCfc*4cT=&wMt|M!HIrCBK`9 zeUJY(zNyA9q}aa2x1xfV*e_2_`h{kM{Vyc)h8;zMU+&42V!^vsrDDY|UxKMdbUko*YkH0Q8|BgyPM?gqS$~4E!Zbr&PKwr3 z$?u@~jn`X7c5li$O-e-2H$9CJ)+JFmW}@t7sZIN4r3pt~Diwk$BW;KE#sKLSBk#}v zMG4;>sy@Hjz)79{$B;j36a?aR{;agr_AA3-At4H48vOs6!T0p_M?<K19`EW0$>l!+6C z^2$L>-U9`9LMyvyn>fVCfFcppb*-dDqo(mseS6d$?({QmYP=RD!6cu}KMs?D4=+xM zaz1B2)0td=qo%Va=`n!Dq}9!S5?1y{M?w~!$MiqqV&5I-U>BS}qf+r6=%oBcMm3>9 z*_u}52XEQyBW`qn8x=fTq@|(TTm$R{Sr-a6le8ea$nvW^@R!gBInCFr?G+Wgk^S@8 zMaNoHRC*w!u59;MFZI~tUW;5G(_h!J_-C+?)u!!gIDkpU$4EY;<%faChP7oriFab= z2%SrIrgy&TR|?NKg_V%>YlmwZh!4-H?mJwqdBRF5|X1&4?%VP5+l#oB=R!)_6s?n&x$I#w(}xWaKXDf74{vr z^xH->15%~>PcXpisKyvLh}CEUE4YC;x!7*lsq4jm)UfGMPduSXzf3Y-KvkQfk$CKe z`0%!x+PogaLvOZ`D(^9o*P@G&T>WXNi)_@jx|YSx3l_)*n9m1uK4)#dlH6r|aKp#a zwUdR_lb1vvKN`{oC@2Ro%1qh1-Hl}&K&(6q<*-IMpGB1>yDfTJonG+dE^;UAlM+Lk9`!dT@clX>nx zx{C290!5y@qaShAuoR?HB~cDKdR`^=VUioW(m=Rp;C)Iui|1FFkHCG4$w1UTF_OvC3IB=1gRh+j}?C{lWP1UC|)D6ukaU)dpGm z9cX_Q{}U9gryX_Z5wXuOJGsg-Vlt-iRtOHPrNz1+w(XWMmkib& z!4Rh=ffp%bXaV&|4Y1t265R(rmYP0;Vm-)Y42JJL&{Jv3-2LDIuM!?~Nu!vTx4vZg zhYTRyTmIX_JdTblqXex@au@(oD%-On+8;ql1R)xhRo)M4pXvg(jzoG>YZ4~Sv*|!I znIjQfN^882DrD!Wc)nKuaO_EcDgDIwEwHG~itsWzN)k`W8mZMOZIN0u`ZI8qEalgm5FM^PjFk%gpho5ywxeQ(OJhtwkqu1L ze89s20By=IP^i+^xl`GWqu&5$7pyM-D5<%Q!B*0vD>Me0m?8AJYk5N)mYPzCMVVEB z@veY_!RzNsl?@dZE+tC*1M@rOp*Kw58v)aP1F~L_IXI*XHMIZuc2^(|xlrd72G!#y z4KOzu`5|2x)i%xBp9FrWU~sMZeUZRX6^0XYEL}g>8o?i|D<7A3TslA{882qcSL~j< z4}VZ0PD75q|9-B+I?4DB3i0kv-l{1Klh>4EDk~XcL5MdE7e3&e- zbPBAPDq3EMD)6evG~_9#2K9py>Ek;_O1D)WH|0sKw}fnhF3MbTq`I2ftP|EUr-vhq zSiw-Hf|j1RPmQL_k)$?dIXj7{iRv7yA;!zp5Dm-CvX57ur0Fm~@dhM-_i#ODLz2lpAs- zlWjsxD>9I{ynfHSlnckQ&M0Y)Rcv%*Vwy#cc|)hP zqtIP9^lOA5=_Uz(S9ArzWLJo}GwZ=ak4D9l9IZx>uxa@Hwem8uAV-?W7d+-~1{}-4 zPM!Q#hd2jw-@@=vcuNZBMfINIz_S|Ht8etEdZr2Vn=mzFBc+veT{dKr`7l4>-m<4= z4j$3Y+drql-`E@zrLH>*H|k$q4ZqoDadW_bRdIz@bTZ@$j06@o(39|#laZNMM2gF( z2TRG8`e`~(YNPf>8IN3;I=(plEtvw7FkqYaby`7t%ygUWy1S<>m%%5!_uOz1bwVnh z8bU`mmjdRwzia#S-HI;E^hZEGObt*?qDeYaZQ(pYn_~#3!F#st--QvV)CkuWW#=6e zJ**MaAE`yFg$X4XxZG<_wbN;TI}Vwm`qJD?RWOiv zGGB#G4^v$6Fbb6PWY|4CKf3YcJl>thrK6Dy7%s%@z>_W^A)k13VMw+3>cJ$?ZD)c&G+)c8-5-4TNjFZRbb)h-*#U!jhIj zWu&U*ky3#75P?_V-nIX#ba7w zX+1MTS9@*Bg{c|%n#LVP)2LjHg?cheaF1iwQi63E3`0y)lr+-WxQupQK?uLQ7fgmDcV#c< za6A24?tIX==U^Zww8)F7(wpFHlxQ444oo)G3Y(LFK>NUSakZ^jIMk=;jzriLlO=M! z&)L)^edTJAXd`Y1mxj_=w2_eY@m?PD&79!PYOi-3S*v35k>b2UcH0La2!jL)xJ{MC z*67c9=sxT&mf+C5Q@XHPfm$||7Fl|r3rx0p2Uh0eW8xxWcmL^g$-HajQL~j@{M%Vw z_^caGL3Jx%lHmZM8>`6Z!SL!rKja>dd2DlLTY$GE$1p)>G#;D-(EGzRd3H>qGi| zre&&n{F`8tpR3zFN0`9$4o|;=LVufB&U46<0eE_g7*SrVVik}=-1+gGTJm)}V^a%+ zJgFsG;pXKiJTMskihbL}qTEj4JjfYK> z8&766h``5_L=$IX5cst&oaU3L`Qm2I{VLHncusSxLL>B+f%SP@JoTl%mR)hh^Z zh-r$6Arg&~7L^XL(prG;UWe_&8P-J>?hdXMkw?rDckN->vnkWw46mhc+Crri+%G#v z4aHrqP=cYCAK@5P`-R_u403&FD^wJ_1X_KrwL=sHUF_1QuO)ZVgjl`YJvF}`1noU9 z(Qt;@ggAT&<9C~Qwn;f0LW0UaJfCrbcuXWLpG%mCpS;MS^e=zyA$ldSqpDC#aBua# zWBJKJpNkMMj`ySE@hz&$ZfvgjsbtagX}_e;LHoA(#Fu`kqvf47=#DcqUVk7A=XYcS3>g;?7%<)uS0Ecc28vBt6rj3Bt_U@!am-?>Q{v?*BhOED6p;J6* zHH_bh7~_INAlSYjI3Q?C(?mH^C**+5I+X@1S z(`yx<%aYVEQ2xx(7hw+Ml=~FcM!IB`K0@%Ak!^DtF-oZFU^F4{sr61V(Th$-yvK#4!$5`RfspY^}H5|Tz2GW^LV z0LHF+yP8}rM54If51SD=QBjlGnh?rNXVwJ__lZseDqcWk2^_5c5Lh~_NR4wpyeG=I zKVU|KI`Qo+9Et8)N_lO;OAWkKHzNmW0u*e{y-4d1I5^23^-ah5=6OPLCkcxPeu(Y@ zqc$d(6c^!|LeG#n_j%E&mp?`)ZAilbi>}b*)}d5d^F+yCJZCxpG8trEc%hqlI=b#X zs0N!9#d1042Ms5XDl1zX**GMAW*IaYwwF?z^ry4KRv_Y}Nit$K`7Ot~xrHJNDU4 z>wohy48vG`zNkag;+HyZT#200s6HEHVyK+3fdCcK3x75r)dgYZ5!-b%WO6 zp`UYgnDVRC)3P@Bss&uzBU<56k;kATj=%)&E^DrY%ah9uEoho&-lXpP94%l@nQiOK z%BDP^oW=Sn@93LSl5!%-=&j(i<#am99ceEvlLLR9K*+KOQD(qfY{uR1hG?K5s8z;- z_S}H1c!vf>sq%AoU1;EXfq(=7(X5;4uD~#PlC#&8Wme_Vj<+UBJ~k=Yx7g`4u}*2j zjQlA0B&MkK8dYPVO~?^rrUgS$%j)r0NPA_gZx8ESv#GN1W+IA zTBQDB!IK^vDSF1!qd#-S%G=2NT9ctMw(vfFWh8`H&31*&iQVmJh4|&!l7{0N6%xtw zq5c?|S{-66v{!%Y-rfAZrWN1Ty1+QshX04Q_l#<4-P(q!BB3{>7a>A|G^K+`Q6K>V z1f+waAiacMmENR=gx)0-sZv5mIs#IpL+HIokt(+RX77ETbIyLw9`F0T-}gOZtREQ} zYtH+==ek$2)|}V8E~Teng(BqMW>dn$?N7^=F`7cnrl{$qaOg(i7ppRtff%0*55@El zdQLsI;Ex6boKLM{CQP*l?}6&gbJFRzIiDq#8k|)}#ClEMLsjwW5|94!8@JRe-I=VU z)*h^=6dxel!o5yu9QWtF6qlqBaF;$E;9Qb+0x1+RJZ34 z&lY8s;^^1*pNj9N_sMQpo#9bS*-LmY9+h{ePF~ZWy3?)B3p=aaWnzYDSZakQFcEkH z6~@7D6&_bWQ_um6t~W4)pQD>^^m8{&j7ncjv=5mFuri#;%*k`|=8V9xy6M;;Nzni%E!%)DDCnS8wKX(mb=#^x>S< z@YdxZX)x&}^yN0x^7Z2pd!Bxclco4EI5Pm2 z$Min+iO`QYNI&`qhwdW0Q4PO`QMe@P3D@-7jtcX*Vn2UskIAJ;luXXF5D#SGOmV)8qDSHCIq%rbd)54x~fk=;!!I>!WHx zw%w%sy|!yI_)KcgpQ%>5pMv5Qf-KOGAnDnyc6T~7mEB;V&^P}bvA_5<#@HDF!2p7l zm94k9O5MstlT;>OyPiE*Mg09Y-58Rqzj!>7Xk)#Kn%K^M3vxFKrJB<&zn19)V|P|3 z=I8VWkpG^gkNSoBa{%4QBs>%j3sH%pfT;zuFab$^&-4Csc3?aU%0~=u# z)o2eO1VX&1#~WSYY);xH+%l|(L6uim&$$voiM|x;5FF$ZE7krbGH}BVC4!La3b#Tj z@p<{RKWh+CztFHve>~VOVshrnS<^?fOBou2QYS7}LSBR65@g?QGvbUJ3n+HehRP6H z`Oe**R3(K>?01SG%n+GTB_-@%hA`R3L+q+(Kxwc2)7YpB<-6vm=cFlMc@q5df(}ZY zzbDAK#?$|d8lEfXulok{KX-!Qo<{l+klUZ>H-aDKyZ`^c2k76Ob9*Q?XMHZZA6F{i z%S}JWYfa#VtMGl3Mci}w8eP6zG?y~m4z*%=_Xaii3i1IUO<>c{b!zbj+PIB4)`+c= zOg(XNO*>*zG4B$sU%ojH_YlmQSXF{tFn-1>E!E%sO1>`tkNsX@2Ud;#tH zTV78lj+20hsr|DGm|6Nxg2-wP^%~2lE2isQ0n{*m3xhCnLh~Fz6%U)TYqBGj%%v)d zxsHqJzGyZ&DQ3E8m1aqQhM0A5xiakTvK3M~CAH&QgXD(Vsx+sw>ZAjn;v@^@z#qq~ zPv>#5gI$b$1W?_a$f_UyZ>w03+m*1LSj~WJv;e#HoIFueZXcH|Otx-Jgj7}U9nm4V7+4Yox9sQt=2@I)%e9IAO@zF;V*TK6+o5ccbfS)?~GQ(UOzJ-rIrM$-J;w=F{H!{a4?r3@~yF@ljii zZz7i8o0ZeEAyD7%~XHtpHc9k{CY#tQ`q<`H%veqqbZ)9|*1r85(!nE?uFx;xVv zm@PPE2Y0i+osU3orY0m;@*#avn3}hpooD<4AUeJjTNq!GV&12BWsfGh>f|30dDASq zByp=Zi3;nO+HHMu6e)mr`?*d89b_fCUAyadV6hIJ+^p>trrUu1$X+_k;(s1noHobeoF0o2-|6R0-JBdeJ~%Jv?^!qkkslnT(bmTNjffznVF#mFT&pfUh1jh& z*B1d(>M0ZRPY__I1KGZ8bz-<)a`oZv2Z_BOlfJnfGb0YZBUj&VhoV+q%i}cMP5g)~ z`$3L(4N^kia?@4>yuldZ03G}R@#v9X9~KQAyaWwA`chsyrk!BO@HyQLb|Y4p(!c7$PWVoMr? zJRGPuKT&#(&;Z$0W(m2365ap%taYqMW)@>-vgAL;ro@m!c@YNgS7csD`7$Q!sqL+0sFs9 zDR+(jZGrbHZC>B;mh0znwR-f4qd`6XyS0*YsVuxaoT>xd=QS`IRGIL{h=1594fWTV z^L4H6J9T1vY~y%#W0VL55!EtI>wKU6d(H;QvehK1=Dis^l1}}HuOnk#Z$a@QY^y3f ztsAn+@3MK>4%IAb|IHm-6Qr$eui`C3Srcm?8z!l*6&)l- z88{_n=|$<@XN0ztDo87<)n)AZ{%aqxKcRPByl`4r;CVp4V)bZKavwU`?bL`aBQqkQ z2gJ{D6Rrq)aBC&^z@4@0f}&#Ggmz3K7%>C}t9^)MjKWjCtLgoJo6?ZcQ?vJW8)h4w zNp!`}P8J`Qf_zRTHm*hSVX6UGoD3VKq48e=i1~jP_y1e7Co0jp9sCOGO8BNffY6^x z1>oD?$_}_jFiihXSp>@;8ykQtcm@8Hd9Hf`8TBcX0Hfccd#0teOQWT1wPdqV;qr-U ztv-)m-p%=08zu~27s%g`2rKb~@bUA`-+Pid0LBya${`(Q=34G-rV3g(zkGQ(zZMb<>HAf^bBY!F@I!}1&R^TsMs@Eh4N`l65g zUaHVY(PRw`d{g_UjotU>-LFQuUl~hW)fC!AJ^@pSHvm*&VadVU+KJsCuRgZszWI&7 z(Z}U#gJ%DBE>>RZ#|hba@{>%EcJb=A_V3QL|JE7m+e=Q5-^~mEWsVhf)^T>a`Sjy6 zC}F1_jP&Vu#FLc$(kuB!_0YaV`oRwm!%xg%UU2mk2ZI`1`49qn z7{Qkc_}7e{`N7BD5sZ?&Ss9-KFvBnTsd%skI(!Oj#+;x|>E8%~E$+hxX89#Ke9bxD z)Gys>w({RT(2BfjeXtkva&q=nX7{g>s_XW5BF79Ss2fq|a9VXHCcpO7{=G`B2f4}1 z59}Qu46pu1ps#mP)cs?L>->=q$BPtmJt#t`9Gi{GOAbB~|7OVbHWz>L(yPBY8FW_p z;ITq}F6wW_CB`VA`}c|`@0}zB{4A~hjX)~$r>^#VCe5kOt0|@xkK*yhpZeb-Ug{p@ z)=P42;W;GUg1+ln{&J!DR?te_jsk%oAZ`I`zWDaNK*5A5?Gl@f%lH2c-0B@H|%~=3BYY^>e*Fma7LU%FVb#pfck$ALBVyBcs})q2TFoj{Ed} ztFi7he2raOWzxnqFwAhr{_1CK&5w3HL$|i<%sTJ!Lmx(rVBZ-EBf$8V!&lQE-J2OW z-p40z(ee>lqHTqou-vBqO4hBcTjFmZaNh*Ib+H6aB8#N$+N?>Zy61@J1B-LeD0RGZ z)ZAS4%BBX7xL(kjzxQJQy6oA2W}7o2kJ3sq5(+?P1$pox{kEM-?$c*GpjU=AT1rxS zc6oO1U@#>>s$JI3MM0-WU`S`5Yo6>m(?{GE=JZ=yMA1T9aQ}Pe z*@A4}Kd6&AmfeS4mNyLbE`6bAZoD^#I{>?>I1ElnRh_0YsEvh?D>)T!n!@Hz9i2k@ifcI3-}XP z+VX9_hJ-s@)?@|at%EmNmS$Xpu0Nyn&OQ4s2%2JIl z0;50S5%tzJ8(W!&YA$JgW+qBUwj;{0I1Q;uPw1dh3sDgyVzax0lvUC z85y=Pbkb!mfEtS)IX=S$tvFa=R9|}3vedpYfj1ED6zD6Ch{CiUH!mN$7UDtH@Xrmb zfXC_TVDHi+cU@E-mjsoZC)=1Os`5!pN^07>difjN16g5O%BewwPSygtWX!@OG`tgi zMJv5~wI4K`K_8rk0~=q1r&5&h7p#Y>)BllF>p$4C)P{MWcdJIuzdeYvY;#?~W!dfs zdTQB2)$|I(pZa@MjWC_R=f#0mJKYd5Pd-7s}7MylP115Qhg;b7Bc2(ys9a27XSM)|OWfs1 zw}R&|MQpI+<2E39d@=Fs@gT+;S!;837HQ7;GB{#$!n)XOp+;8YnQ^jj+d!kDlZIX7 z#`U2=cqCB-Ug3gBz1IbYo#Pv(ti-WI;LOPM3meyGGp zG;#Qz;^^0rJTZ&FYimE7&Sgi19@z?*nB$+D`M%OBaT2}DR(RBBvN2$!7ejb|GAszs z;C`)xfS~u;7aNy7XSe74A!H2sQ*XF;by*-E6!w;m)qY9Tz1m|i0qp+L&VPR|u3`bj zbj@t55m5st)BBBp_^7h=y|dhVeuW1!oS7%Zc;x)rtG&oyy@tt#RX>V)z0{~A*VVxq z^z;p4D_L~8JuxSM_f+qXUnOHlugr6)PT$)QzPR7H#*ci+-(*EaeukBM$z(aidy`_^ zTtxsG>gEGQv?1xj5~-7Y{{qXb}AN~~2ae%qY88_%z@+CvtHQWm1{M->Q#56({RQW=4dsB=f6+o=X zkB9CPDW39kKspBYAHTgcHuH4Z{$9HTN!jo)Q|JMzY(XL>!<%HH*3&R}JX(cOC)

lE;aew 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 KEKOVe|0V!Fe!M~e literal 0 HcmV?d00001 diff --git a/frontend/src/api/gatewayClient.ts b/frontend/src/api/gatewayClient.ts index 24e159d..51d2a74 100644 --- a/frontend/src/api/gatewayClient.ts +++ b/frontend/src/api/gatewayClient.ts @@ -349,3 +349,38 @@ export interface DeliveryView { export const deliveryApi = { view: () => request("/api/patterns/delivery"), }; + +// --- Demo 14: compensation under timeouts and duplicate events ----------------------------------- + +export interface HoldRow { + reservation_id: string; + order_id: number; + status: "RESERVED" | "SOLD" | "RELEASED" | string; + items: { product_id: number; quantity: number }[]; + releases_received: number; +} + +export interface HandledEvent { + event_id: string; + type: string; + reservation_id: string | null; + outcome: string; +} + +export const compensationApi = { + inventoryMode: () => request<{ mode: string; enabled: boolean }>("/api/shop/inventory/chaos"), + setInventoryMode: (mode: string) => + getAny<{ mode?: string; message?: string }>("/api/shop/inventory/chaos", { + method: "POST", + headers: { "Content-Type": "application/json" }, + body: JSON.stringify({ mode }), + }), + holds: () => request<{ results: HoldRow[] }>("/api/shop/inventory/reservations"), + handled: () => + request<{ results: HandledEvent[]; duplicates_skipped: number; not_handled: number }>("/api/shop/inventory/events"), + replay: (token: string, sagaId: string) => + getAny<{ replayed?: number; message?: string }>(`/api/shop/order/sagas/${sagaId}/replay`, { + method: "POST", + headers: authHeaders(token), + }), +}; diff --git a/frontend/src/pages/Home.tsx b/frontend/src/pages/Home.tsx index 96c0256..96032c0 100644 --- a/frontend/src/pages/Home.tsx +++ b/frontend/src/pages/Home.tsx @@ -18,7 +18,7 @@ export default function Home() {

Patterns

-

The 12 patterns. All 12 are live, each with a working demo, plus demo 13: a slow payment in the middle of checkout.

+

The 12 patterns. All 12 are live, each with a working demo, plus demo 13 (a slow payment in the middle of checkout) and demo 14 (the saga's undo under timeouts and duplicate events).

diff --git a/frontend/src/pages/PatternPage.tsx b/frontend/src/pages/PatternPage.tsx index 8a951be..a30abee 100644 --- a/frontend/src/pages/PatternPage.tsx +++ b/frontend/src/pages/PatternPage.tsx @@ -12,6 +12,7 @@ import ObservabilityDemo from "../patterns/demos/ObservabilityDemo"; import SagaDemo from "../patterns/demos/SagaDemo"; import ServiceDiscoveryDemo from "../patterns/demos/ServiceDiscoveryDemo"; import SlowPaymentDemo from "../patterns/demos/SlowPaymentDemo"; +import CompensationDemo from "../patterns/demos/CompensationDemo"; import StatelessDemo from "../patterns/demos/StatelessDemo"; import { PATTERNS } from "../patterns/content"; @@ -29,6 +30,7 @@ const DEMOS: Record ReactNode> = { containerization: () => , "ci-cd-pipeline": () => , "slow-payment": () => , + compensation: () => , }; export default function PatternPage() { diff --git a/frontend/src/pages/Patterns.tsx b/frontend/src/pages/Patterns.tsx index fb59885..0764e8a 100644 --- a/frontend/src/pages/Patterns.tsx +++ b/frontend/src/pages/Patterns.tsx @@ -2,15 +2,15 @@ import { Link } from "react-router-dom"; import { PATTERNS } from "../patterns/content"; export default function Patterns() { - const patterns = PATTERNS.filter((p) => p.n <= 12); // demo 13 is a bonus, not a 13th pattern + const patterns = PATTERNS.filter((p) => p.n <= 12); // demos 13 and 14 are bonuses, not patterns const liveCount = patterns.filter((p) => p.live).length; return (
-

The 12 patterns, plus demo 13

+

The 12 patterns, plus demos 13 and 14

Each pattern has a page that explains it, says when not to use it, and runs a live demo against the real - services. {liveCount} of {patterns.length} are live. Demo 13 puts patterns 4 and 8 under a slow payment. + services. {liveCount} of {patterns.length} are live. Demo 13 puts patterns 4 and 8 under a slow payment; demo 14 puts the saga's undo under timeouts and duplicate events.

diff --git a/frontend/src/patterns/content.ts b/frontend/src/patterns/content.ts index 9b31e12..ffce541 100644 --- a/frontend/src/patterns/content.ts +++ b/frontend/src/patterns/content.ts @@ -303,6 +303,29 @@ export const PATTERNS: PatternInfo[] = [ ], source: { label: "Stripe — Idempotent requests", url: "https://docs.stripe.com/api/idempotent_requests" }, }, + { + n: 14, + slug: "compensation", + name: "Compensation under fire", + what: "Times out and duplicates the saga's undo, then checks the stock ends where it began.", + milestone: "M3", + live: true, + problem: + "An undo is a new action, not a rewind, and it travels over the same unreliable network. A release can time out yet go through, so it is sent twice. A release can overtake the slow hold it undoes, so the hold lands afterwards with nothing left to cancel it. And at-least-once delivery sends any event twice.", + inThisProject: [ + "Inventory has a demo switch: hold slowly (6 s, past the saga's 3 s wait) or release slowly.", + "When the hold times out, the saga sends its release as an event; it reaches inventory in about 4 s, before the 6 s hold. Inventory records a release for a hold it never saw as RELEASED (and logs it). When the late hold arrives, it finds that record and holds nothing.", + "A release that times out is also sent as an event. The event copy lands first, the slow direct call second. Release only acts on a hold that is still RESERVED, so the second copy changes nothing; the page counts both copies.", + "Inventory acts on 2 event types, OrderConfirmed and StockReleaseRequested. It remembers every id it acted on and skips one it has seen; other types are not its business and it ignores them. The replay button sends a checkout's events again with the same ids, and the page counts what was skipped and what was ignored.", + "Raised by a reader of the project's LinkedIn post, after demo 13.", + ], + whenNotToUse: [ + "Recording releases for unknown holds keeps rows that never held anything. At scale they need a retention window, longer than any request can be late.", + "An undo that touches the outside world (an email sent, money refunded) cannot be made invisible: the customer sees both actions. Here the undo only moves stock inside one service.", + "Event-id dedupe needs the ids kept as long as a duplicate can arrive. A bus with a short redelivery window can keep fewer.", + ], + source: { label: "Microsoft — Compensating Transaction pattern", url: "https://learn.microsoft.com/azure/architecture/patterns/compensating-transaction" }, + }, ]; export const SERVICE_NAMES = ["gateway", "user", "catalog", "order", "payment", "inventory"] as const; diff --git a/frontend/src/patterns/demos/CompensationDemo.tsx b/frontend/src/patterns/demos/CompensationDemo.tsx new file mode 100644 index 0000000..da0ba16 --- /dev/null +++ b/frontend/src/patterns/demos/CompensationDemo.tsx @@ -0,0 +1,213 @@ +import { useEffect, useState } from "react"; +import { Link } from "react-router-dom"; +import { + HandledEvent, + HoldRow, + SagaRun, + StockRow, + asyncApi, + compensationApi, + savedToken, +} from "../../api/gatewayClient"; +import { PILL, STEP_LABEL } from "./SagaDemo"; + +const DEMO_PRODUCT = 1; +const POLL_MS = 2000; + +const MODES: { mode: string; label: string; what: string }[] = [ + { mode: "slow_reserve", label: "Hold arrives late", what: "Inventory takes the hold 6 s late. The saga waits 3 s, gives up, and sends a release, which arrives first." }, + { mode: "slow_release", label: "Release times out", what: "Inventory releases 6 s late. The saga's direct release times out after 3 s, so it also sends the release as an event. The event copy lands first (about 4 s), the direct call second (6 s): 2 copies, 1 release." }, + { mode: "healthy", label: "Healthy", what: "Inventory answers at once." }, +]; + +/** Demo 14: compensation under timeouts and duplicate events. Does the stock end where it began? */ +export default function CompensationDemo() { + const token = savedToken(); + const [mode, setMode] = useState("unknown"); + const [error, setError] = useState(null); + const [busy, setBusy] = useState(false); + const [answer, setAnswer] = useState(null); + const [before, setBefore] = useState(null); + const [stock, setStock] = useState(null); + const [saga, setSaga] = useState(null); + const [hold, setHold] = useState(null); + const [handled, setHandled] = useState([]); + const [counts, setCounts] = useState<{ skipped: number; notHandled: number } | null>(null); + const [replayed, setReplayed] = useState<{ count: number; skippedAt: number; notHandledAt: number } | null>(null); + + async function refresh(): Promise { + if (!token) return null; + const [history, view, holds, events, chaos] = await Promise.all([ + asyncApi.sagas(token).catch(() => null), + asyncApi.events().catch(() => null), + compensationApi.holds().catch(() => null), + compensationApi.handled().catch(() => null), + compensationApi.inventoryMode().catch(() => null), + ]); + const latest = history?.results[0] ?? null; + const row = view?.stock?.find((s) => s.product_id === DEMO_PRODUCT) ?? null; + setSaga(latest); + setStock(row); + setHold(latest ? holds?.results.find((h) => h.reservation_id === latest.saga_id) ?? null : null); + setHandled(latest && events ? events.results.filter((e) => e.reservation_id === latest.saga_id) : []); + if (events) setCounts({ skipped: events.duplicates_skipped, notHandled: events.not_handled }); + if (chaos) setMode(chaos.mode); + return row; + } + + useEffect(() => { + refresh(); + const timer = setInterval(refresh, POLL_MS); + return () => clearInterval(timer); + // eslint-disable-next-line react-hooks/exhaustive-deps + }, []); + + if (!token) { + return ( +

+ This demo checks out a real cart, so it needs a signed-in user. Register or log in on the Shop + page, then come back. +

+ ); + } + + async function switchInventory(next: string) { + setError(null); + const { status, body } = await compensationApi.setInventoryMode(next); + if (status === 200 && body.mode) setMode(body.mode); + else setError(body.message ?? `HTTP ${status}`); + } + + async function buy(decline: boolean) { + if (!token) return; + setBusy(true); + setAnswer(null); + setReplayed(null); + try { + setBefore(await refresh()); + await asyncApi.addToCart(token, DEMO_PRODUCT, 2); + const { status, body } = await asyncApi.checkout(token, decline); + setAnswer(`HTTP ${status}: ${body.message ?? (status === 200 ? "Order placed." : "")}`); + } catch (err) { + setAnswer(String(err)); + } finally { + await refresh(); + setBusy(false); + } + } + + async function replay() { + if (!token || !saga) return; + setError(null); + const { status, body } = await compensationApi.replay(token, saga.saga_id); + if (status === 200) + setReplayed({ count: body.replayed ?? 0, skippedAt: counts?.skipped ?? 0, notHandledAt: counts?.notHandled ?? 0 }); + else setError(body.message ?? `HTTP ${status}`); + } + + const restored = before && stock && stock.on_hand === before.on_hand && stock.reserved === before.reserved; + const sold = before && stock && stock.on_hand === before.on_hand - 2 && stock.reserved === before.reserved; + const verdict = !before || !stock + ? null + : restored + ? "Back where it began: same mugs on hand, nothing held." + : sold + ? "Sold once: 2 mugs fewer on hand, nothing held." + : `Not settled yet: on hand ${before.on_hand} -> ${stock.on_hand}, held ${before.reserved} -> ${stock.reserved}.`; + + return ( +
+
+
+

Step 1. Pick what goes wrong in inventory

+
+ {MODES.map((m) => ( + + ))} +
+

{MODES.find((m) => m.mode === mode)?.what ?? "Inventory mode unknown."}

+ {error &&

{error}

} + +

Step 2. Buy 2 Contoso Mugs

+
+ + +
+

+ "Hold arrives late" goes with Buy. "Release times out" goes with card declined, so the saga has to undo. +

+ {busy &&

Checking out…

} + {answer &&

{answer}

} + +

Step 3. Send this checkout's events again

+ + {replayed && counts && ( +

+ Sent {replayed.count} event(s) again with the same ids. Since then, inventory skipped{" "} + {counts.skipped - replayed.skippedAt} it had already acted on, and ignored{" "} + {counts.notHandled - replayed.notHandledAt} that are not its business (counts include any other checkout + running now). +

+ )} +
+ +
+

Where the stock is

+ + + + + + + + + + + + + + + + + + + + + + + + + + + +
Hold for this checkout{hold ? `${hold.status}${hold.items.length === 0 ? " (release came first, nothing held)" : ""}` : "none yet"}
Release requests received{hold ? hold.releases_received : "–"}
Mugs on hand{before && stock ? `${before.on_hand} -> ${stock.on_hand}` : stock?.on_hand ?? "?"}
Mugs held for checkouts{before && stock ? `${before.reserved} -> ${stock.reserved}` : stock?.reserved ?? "?"}
Events inventory acted on{handled.length === 0 ? "none" : handled.map((e) => `${e.type}: ${e.outcome}`).join("; ")}
Duplicate events skipped (all checkouts){counts?.skipped ?? "?"}
+ {verdict &&

{verdict}

} +

Refreshes every 2 s. A slow step lands about 6 s after the click.

+
+
+ + {saga && ( +
+

What the saga did

+
    + {saga.steps.map((s, i) => ( +
  1. + {s.status} + {STEP_LABEL[s.step] ?? s.step} + {s.detail && · {s.detail}} +
  2. + ))} +
+
+ )} +
+ ); +} diff --git a/services/inventory/application/__init__.py b/services/inventory/application/__init__.py index c200054..5ad15e5 100644 --- a/services/inventory/application/__init__.py +++ b/services/inventory/application/__init__.py @@ -34,6 +34,9 @@ def create_app(config_name: str | None = None) -> Flask: app.register_blueprint(inventory_api) db.create_all() + from shop_common.db_setup import add_missing_columns + + add_missing_columns(db) # demo 14: reservation.releases_received from .seed import seed_missing_stock seed_missing_stock() diff --git a/services/inventory/application/consumer.py b/services/inventory/application/consumer.py index 9102b84..503a29b 100644 --- a/services/inventory/application/consumer.py +++ b/services/inventory/application/consumer.py @@ -8,13 +8,18 @@ from .models import ConsumedEvent HANDLERS = {"OrderConfirmed": stock.commit, "StockReleaseRequested": stock.release} +# Demo 14: what this process did with events it did not act on. In memory: demo counters, not data. +# duplicates_skipped: an event id it already acted on. not_handled: a type that is not inventory's. +counts = {"duplicates_skipped": 0, "not_handled": 0} def handle(event: dict) -> None: action = HANDLERS.get(event.get("type")) if action is None: + counts["not_handled"] += 1 return if db.session.get(ConsumedEvent, event["event_id"]) is not None: + counts["duplicates_skipped"] += 1 return # seen before: at-least-once delivery sent it twice reservation_id = event["payload"].get("reservation_id") # action() commits on its own. If we crash before the ConsumedEvent row below, the event is diff --git a/services/inventory/application/models.py b/services/inventory/application/models.py index e77bf13..0d6f984 100644 --- a/services/inventory/application/models.py +++ b/services/inventory/application/models.py @@ -29,6 +29,10 @@ def _utcnow(): return datetime.now(timezone.utc) +# Demo 14: the order id of a hold recorded only by its release (the hold itself never arrived). +NEVER_HELD = 0 + + class Reservation(db.Model): """Stock held for one checkout attempt (pattern 8). Keyed by the order service's saga id, so a retried request or a redelivered event finds the same row instead of holding stock twice.""" @@ -39,6 +43,8 @@ class Reservation(db.Model): order_id = db.Column(db.Integer, nullable=False, index=True) items = db.Column(db.JSON, nullable=False) # [{"product_id": 1, "quantity": 2}] status = db.Column(db.String(10), nullable=False) # RESERVED -> SOLD | RELEASED + # Demo 14: how many release requests arrived (a direct call and its event copy can both come). + releases_received = db.Column(db.Integer, nullable=True, default=0) created_at = db.Column(db.DateTime, default=_utcnow) updated_at = db.Column(db.DateTime, default=_utcnow, onupdate=_utcnow) @@ -48,6 +54,7 @@ def to_json(self): "order_id": self.order_id, "items": self.items, "status": self.status, + "releases_received": self.releases_received or 0, "updated_at": self.updated_at.isoformat() if self.updated_at else None, } diff --git a/services/inventory/application/routes.py b/services/inventory/application/routes.py index 6587d5b..6f4b049 100644 --- a/services/inventory/application/routes.py +++ b/services/inventory/application/routes.py @@ -1,12 +1,32 @@ +import time + from flask import Blueprint, jsonify, make_response, request from pydantic import BaseModel, Field, ValidationError -from shop_common.flask_support import chaos_enabled +from shop_common.flask_support import DemoSwitch, chaos_enabled, switches_off -from . import db, stock +from . import consumer, db, stock from .models import ConsumedEvent, Reservation, StockItem inventory_api = Blueprint("inventory_api", __name__) +# Demo 14 switch: "slow_reserve" makes a hold land after the saga gave up on it (its timeout is +# 3 s), so the saga's release arrives first. "slow_release" makes the saga's direct release time +# out although it goes through, so the event copy arrives too. In memory: a lab switch, not data. +SWITCH = DemoSwitch("healthy", "slow_reserve", "slow_release") +SLOW_SECONDS = 6 +_SLOWED = {"slow_reserve": "inventory_api.reserve", "slow_release": "inventory_api.release"} + + +@inventory_api.before_request +def _apply_chaos(): + if _SLOWED.get(SWITCH.value) == request.endpoint: + time.sleep(SLOW_SECONDS) + + +@inventory_api.route("/api/inventory/chaos", methods=["GET", "POST"]) +def chaos(): + return SWITCH.respond() + class Line(BaseModel): product_id: int = Field(gt=0) @@ -47,10 +67,9 @@ def reserve(): @inventory_api.post("/api/inventory/reservations//release") def release(reservation_id: str): - reservation = stock.release(reservation_id) - if reservation is None: - return make_response(jsonify({"message": "No such reservation"}), 404) - return jsonify({"result": reservation.to_json()}) + if not 8 <= len(reservation_id) <= 36: # the same rule as a hold's id + return make_response(jsonify({"message": "A hold id is 8 to 36 characters"}), 400) + return jsonify({"result": stock.release(reservation_id).to_json()}) @inventory_api.get("/api/inventory/reservations") @@ -62,7 +81,7 @@ def list_reservations(): @inventory_api.get("/api/inventory/events") def consumed_events(): rows = ConsumedEvent.query.order_by(ConsumedEvent.handled_at.desc()).limit(20) - return jsonify({"results": [e.to_json() for e in rows]}) + return jsonify({"results": [e.to_json() for e in rows], **consumer.counts}) class RestockRequest(BaseModel): @@ -73,7 +92,7 @@ class RestockRequest(BaseModel): def restock(product_id: int): """Demo and smoke-test helper: adds units on hand. Only with CHAOS_ENABLED=1 (make run).""" if not chaos_enabled(): - return make_response(jsonify({"message": "Demo switches are off (CHAOS_ENABLED is not 1)"}), 403) + return switches_off() try: data = RestockRequest.model_validate(request.get_json(silent=True) or {}) except ValidationError as exc: diff --git a/services/inventory/application/stock.py b/services/inventory/application/stock.py index 7bc538a..f383f74 100644 --- a/services/inventory/application/stock.py +++ b/services/inventory/application/stock.py @@ -1,15 +1,20 @@ """Stock rules for the checkout saga (pattern 8) and the event consumer (pattern 7). reserve: available -> reserved (saga step 1; all lines or none) -release: reserved -> available (saga compensation) +release: reserved -> available (saga compensation; an unknown hold is recorded as RELEASED, + so a hold that arrives late is refused: demo 14) commit: reserved -> sold (on OrderConfirmed: on hand goes down) Each is idempotent: calling it again for the same reservation changes nothing. """ +import logging + from sqlalchemy.exc import IntegrityError from . import db -from .models import Reservation, StockItem +from .models import NEVER_HELD, Reservation, StockItem + +log = logging.getLogger(__name__) class OutOfStock(Exception): @@ -29,7 +34,7 @@ def _in_lock_order(items: list[dict]) -> list[dict]: def reserve(reservation_id: str, order_id: int, items: list[dict]) -> Reservation: existing = db.session.get(Reservation, reservation_id) - if existing is not None: + if existing is not None: # a retry, or a hold its release beat here: either way, hold nothing new return existing items = _in_lock_order(items) short = [] @@ -53,9 +58,24 @@ def reserve(reservation_id: str, order_id: int, items: list[dict]) -> Reservatio return reservation -def release(reservation_id: str) -> Reservation | None: +def release(reservation_id: str) -> Reservation: reservation = db.session.get(Reservation, reservation_id) - if reservation is None or reservation.status != "RESERVED": + if reservation is None: + # Demo 14: the release beat its hold here (the hold request was slow and the saga gave + # up). Record the release, so the late hold finds it and holds nothing. + log.warning("release for hold %s, which never arrived: recorded so a late hold is refused", reservation_id) + reservation = Reservation(id=reservation_id, order_id=NEVER_HELD, items=[], status="RELEASED", + releases_received=1) + db.session.add(reservation) + try: + db.session.commit() + except IntegrityError: # the hold or another release landed at the same moment + db.session.rollback() + return release(reservation_id) + return reservation + reservation.releases_received = (reservation.releases_received or 0) + 1 + if reservation.status != "RESERVED": + db.session.commit() return reservation for line in _in_lock_order(reservation.items): _lock(line["product_id"]).reserved -= line["quantity"] diff --git a/services/inventory/tests/test_compensation.py b/services/inventory/tests/test_compensation.py new file mode 100644 index 0000000..78ffa36 --- /dev/null +++ b/services/inventory/tests/test_compensation.py @@ -0,0 +1,135 @@ +"""Demo 14: compensation under timeouts and duplicate events. + +A saga's release can arrive before its hold (the hold request was slow, the saga gave up and sent +a release), and the same release can arrive twice (the direct call timed out but went through, +and the event copy follows). Either way the stock must end up exactly as before the checkout. +""" +import pytest + +from application import consumer, db, routes +from application.models import StockItem +from application.seed import seed_missing_stock + +RID = "saga-0014-aaaa" + + +@pytest.fixture +def seeded(app): + seed_missing_stock() + return app + + +def _stock(product_id=1): + return db.session.get(StockItem, product_id).to_json() + + +def _reserve(client, rid=RID, qty=2): + return client.post("/api/inventory/reservations", + json={"reservation_id": rid, "order_id": 7, "items": [{"product_id": 1, "quantity": qty}]}) + + +def _release(client, rid=RID): + return client.post(f"/api/inventory/reservations/{rid}/release") + + +def _mode(client, monkeypatch, mode): + monkeypatch.setenv("CHAOS_ENABLED", "1") + return client.post("/api/inventory/chaos", json={"mode": mode}) + + +@pytest.fixture(autouse=True) +def _fresh(): + """The switch and the counters live in memory for the whole test run: reset them per test.""" + consumer.counts.update(duplicates_skipped=0, not_handled=0) + yield + routes.SWITCH.value = "healthy" + + +def _counts(client): + body = client.get("/api/inventory/events").get_json() + return body["duplicates_skipped"], body["not_handled"] + + +def test_a_release_that_arrives_before_its_hold_refuses_the_late_hold(seeded, client): + before = _stock() + assert _release(client).get_json()["result"]["status"] == "RELEASED" # nothing held yet + late = _reserve(client) + assert late.status_code == 200 + assert late.get_json()["result"]["status"] == "RELEASED" # the late hold holds nothing + assert _stock() == before + + +def test_a_release_sent_twice_returns_the_stock_once_and_counts_both_copies(seeded, client): + before = _stock() + _reserve(client) + consumer.handle({"event_id": "evt-r1", "type": "StockReleaseRequested", "payload": {"reservation_id": RID}}) + late = _release(client) # the direct call that timed out, landing after the event copy + assert _stock() == before + assert late.get_json()["result"]["releases_received"] == 2 # the page shows both copies arrived + + +def test_a_release_for_a_hold_never_seen_is_logged(seeded, client, caplog): + with caplog.at_level("WARNING"): + _release(client) + assert RID in caplog.text + + +def test_a_release_id_must_look_like_a_hold_id(seeded, client): + assert _release(client, "x").status_code == 400 + assert _release(client, "y" * 37).status_code == 400 + + +def test_a_replayed_checkout_is_skipped_or_ignored_event_by_event(seeded, client): + _reserve(client, qty=3) + checkout = [{"event_id": f"evt-{t}", "type": t, "payload": {"reservation_id": RID}} + for t in ("StockReserved", "PaymentCharged", "OrderConfirmed")] + for event in checkout: + consumer.handle(event) + sold = _stock() + for event in checkout: # redelivered + consumer.handle(event) + assert _stock() == sold + assert _counts(client) == (1, 4) # OrderConfirmed skipped once; the other 2 are not inventory's, twice + + +def test_a_database_from_before_demo_14_gains_the_release_count(app): + from sqlalchemy import inspect, text + + from application import create_app + + db.drop_all() + db.session.execute(text("CREATE TABLE reservation (id VARCHAR(36) PRIMARY KEY, order_id INTEGER NOT NULL, " + "items JSON NOT NULL, status VARCHAR(10) NOT NULL, created_at DATETIME, updated_at DATETIME)")) + db.session.commit() + create_app("development") + assert "releases_received" in {c["name"] for c in inspect(db.engine).get_columns("reservation")} + + +def test_slow_reserve_delays_only_the_hold(seeded, client, monkeypatch): + slept = [] + monkeypatch.setattr(routes.time, "sleep", slept.append) + assert _mode(client, monkeypatch, "slow_reserve").status_code == 200 + _release(client, "saga-other-1") + assert slept == [] + _reserve(client) + assert slept == [routes.SLOW_SECONDS] + + +def test_slow_release_delays_only_the_release(seeded, client, monkeypatch): + slept = [] + monkeypatch.setattr(routes.time, "sleep", slept.append) + _mode(client, monkeypatch, "slow_release") + _reserve(client) + assert slept == [] + _release(client) + assert slept == [routes.SLOW_SECONDS] + + +def test_the_inventory_switch_is_off_unless_chaos_is_enabled(seeded, client, monkeypatch): + monkeypatch.delenv("CHAOS_ENABLED", raising=False) + assert client.post("/api/inventory/chaos", json={"mode": "slow_reserve"}).status_code == 403 + assert client.get("/api/inventory/chaos").get_json()["mode"] == "healthy" + + +def test_the_inventory_switch_rejects_an_unknown_mode(seeded, client, monkeypatch): + assert _mode(client, monkeypatch, "broken").status_code == 400 diff --git a/services/order/application/order_api/routes.py b/services/order/application/order_api/routes.py index 0cf12ad..87844ab 100644 --- a/services/order/application/order_api/routes.py +++ b/services/order/application/order_api/routes.py @@ -3,10 +3,10 @@ from flask import jsonify, make_response, request from . import order_api_blueprint -from shop_common.flask_support import chaos_enabled +from shop_common.flask_support import chaos_enabled, switches_off from .. import db, outbox, saga -from ..models import Order, OrderItem, OutboxEvent +from ..models import Order, OrderItem, OutboxEvent, SagaStep from ..schemas import OrderAddItemRequest from ..validation import validate_form from .api import clients @@ -80,7 +80,7 @@ def checkout(): options = request.get_json(silent=True) or request.form simulate = "decline" if str(options.get("simulate_decline", "")).lower() in ("1", "true", "yes") else "approve" if simulate == "decline" and not chaos_enabled(): - return make_response(jsonify({"message": "Demo switches are off (CHAOS_ENABLED is not 1)"}), 403) + return switches_off() status, body = saga.run_checkout(order_model, u_id, simulate) return make_response(jsonify(body), status) @@ -93,6 +93,27 @@ def sagas(): return jsonify({"results": saga.recent_sagas(u_id)}) +# Demo 14: send a checkout's events to the bus again, with the same ids, as at-least-once delivery +# can. Inventory should skip every one. Only your own checkout, only with the demo switches on. +@order_api_blueprint.route("/api/order/sagas//replay", methods=["POST"]) +def replay_saga_events(saga_id: str): + if not chaos_enabled(): + return switches_off() + u_id = _user_id() + if u_id is None: + return _not_logged_in() + first = SagaStep.query.filter_by(saga_id=saga_id, user_id=u_id).order_by(SagaStep.id).first() + if first is None: + return make_response(jsonify({"message": "No such checkout"}), 404) + # Its events are all written after its first step: scan from there, not the whole outbox. + since = OutboxEvent.query.filter(OutboxEvent.created_at >= first.at).all() + events = [e for e in since if e.payload.get("saga_id") == saga_id] + for event in events: + event.published_at = None # the relay sends it again within 1 s + db.session.commit() + return jsonify({"replayed": len(events), "event_ids": [e.id for e in events]}) + + # Pattern 7 demo: what is waiting in the outbox and what has been published. No personal data: # events carry ids, quantities and amounts only. @order_api_blueprint.route("/api/order/outbox", methods=["GET"]) @@ -106,7 +127,7 @@ def outbox_events(): @order_api_blueprint.route("/debug/bus", methods=["POST"]) def bus_switch(): if not chaos_enabled(): - return make_response(jsonify({"message": "Demo switches are off (CHAOS_ENABLED is not 1)"}), 403) + return switches_off() connected = bool((request.get_json(silent=True) or {}).get("connected", True)) outbox.set_connected(connected) return jsonify({"bus_connected": connected}) diff --git a/services/order/tests/test_saga_and_outbox.py b/services/order/tests/test_saga_and_outbox.py index 8e5b740..0880291 100644 --- a/services/order/tests/test_saga_and_outbox.py +++ b/services/order/tests/test_saga_and_outbox.py @@ -161,3 +161,27 @@ def timeout(rid, oid, items): assert r.status_code == 503 assert _events() == ["StockReleaseRequested", "CheckoutFailed"] assert OutboxEvent.query.filter_by(type="StockReleaseRequested").one().payload["reservation_id"] == r.get_json()["saga_id"] + + +# --- Demo 14: replay a checkout's events, to show inventory skips duplicates --------------------- + +def test_replay_sends_a_checkouts_events_again_with_the_same_ids(client, calls): + saga_id = _checkout(client).get_json()["saga_id"] + OutboxEvent.query.update({"published_at": outbox.datetime.now(outbox.timezone.utc)}) + ids = sorted(e.id for e in OutboxEvent.query) + r = client.post(f"/api/order/sagas/{saga_id}/replay", headers=AUTH) + assert r.status_code == 200 + assert r.get_json()["replayed"] == 3 + assert sorted(e.id for e in OutboxEvent.query.filter(OutboxEvent.published_at.is_(None))) == ids + + +def test_replay_is_only_for_your_own_checkout(client, calls, monkeypatch): + saga_id = _checkout(client).get_json()["saga_id"] + monkeypatch.setattr(clients, "current_user_id", lambda header: 2) + assert client.post(f"/api/order/sagas/{saga_id}/replay", headers=AUTH).status_code == 404 + + +def test_replay_is_off_unless_chaos_is_enabled(client, calls, monkeypatch): + saga_id = _checkout(client).get_json()["saga_id"] + monkeypatch.delenv("CHAOS_ENABLED") + assert client.post(f"/api/order/sagas/{saga_id}/replay", headers=AUTH).status_code == 403 diff --git a/services/payment/application/routes.py b/services/payment/application/routes.py index abfd895..0cfb396 100644 --- a/services/payment/application/routes.py +++ b/services/payment/application/routes.py @@ -4,7 +4,7 @@ from flask import Blueprint, jsonify, make_response, request from pydantic import BaseModel, Field, ValidationError -from shop_common.flask_support import chaos_enabled +from shop_common.flask_support import DemoSwitch from sqlalchemy.exc import IntegrityError from . import db @@ -16,9 +16,8 @@ # SLOW_SECONDS, longer than the order service waits). Held in memory: it is a lab switch, not data. # The switch makes charging sick, not settling: void and the list always answer, so the demo 13 # page can show where the money is while payment is slow. -MODES = ("healthy", "failing", "slow") +SWITCH = DemoSwitch("healthy", "failing", "slow") SLOW_SECONDS = 3 -_mode = {"value": "healthy"} _ALWAYS_ANSWERS = {"payment_api.chaos", "payment_api.void", "payment_api.list_payments"} # Demo 13: a charge still PROCESSING after this long lost its process (a crash or restart), so a # void may cancel it. Far longer than any charge takes, slow mode included. @@ -42,9 +41,9 @@ class ChargeRequest(VoidRequest): def _apply_chaos(): if request.endpoint in _ALWAYS_ANSWERS: return None - if _mode["value"] == "failing": + if SWITCH.value == "failing": return make_response(jsonify({"message": "Payment is failing (demo switch)"}), 500) - if _mode["value"] == "slow" and request.endpoint != "payment_api.charge": # charge() is slow itself + if SWITCH.value == "slow" and request.endpoint != "payment_api.charge": # charge() is slow itself time.sleep(SLOW_SECONDS) return None @@ -99,7 +98,7 @@ def charge(): if (payment.order_id, payment.amount_cents) != (data.order_id, data.amount_cents): return make_response(jsonify({"message": "This key was already used for a different charge"}), 409) return jsonify({"result": payment.to_json()}) - if _mode["value"] == "slow": + if SWITCH.value == "slow": time.sleep(SLOW_SECONDS) return jsonify({"result": _finish(payment, "DECLINED" if data.simulate == "decline" else "APPROVED").to_json()}) @@ -122,11 +121,4 @@ def void(key: str): @payment_api.route("/api/payment/chaos", methods=["GET", "POST"]) def chaos(): - if request.method == "POST": - if not chaos_enabled(): - return make_response(jsonify({"message": "Chaos switches are off (CHAOS_ENABLED is not 1)"}), 403) - mode = (request.get_json(silent=True) or request.form.to_dict()).get("mode") - if mode not in MODES: - return make_response(jsonify({"message": f"mode must be one of {list(MODES)}"}), 400) - _mode["value"] = mode - return jsonify({"mode": _mode["value"], "modes": list(MODES), "enabled": chaos_enabled()}) + return SWITCH.respond() diff --git a/services/payment/tests/test_contract_provider.py b/services/payment/tests/test_contract_provider.py index 7a95fd4..3e8a692 100644 --- a/services/payment/tests/test_contract_provider.py +++ b/services/payment/tests/test_contract_provider.py @@ -19,7 +19,7 @@ def test_payment_honours_the_order_services_contract(app): db.session.remove() def healthy() -> None: - routes._mode["value"] = "healthy" + routes.SWITCH.value = "healthy" def charge_exists() -> None: healthy() diff --git a/services/payment/tests/test_payment.py b/services/payment/tests/test_payment.py index 9ae2cf7..757f7d1 100644 --- a/services/payment/tests/test_payment.py +++ b/services/payment/tests/test_payment.py @@ -115,7 +115,7 @@ def test_a_charge_voided_while_it_ran_does_not_approve_when_it_finishes(client, try: assert _charge(client, "saga-1").get_json()["result"]["status"] == "VOIDED" finally: - routes._mode["value"] = "healthy" + routes.SWITCH.value = "healthy" def _force_void(key): @@ -135,7 +135,7 @@ def test_a_slow_retry_does_not_wait_again(client, monkeypatch): _charge(client, "saga-1") _charge(client, "saga-1") finally: - routes._mode["value"] = "healthy" + routes.SWITCH.value = "healthy" assert len(sleeps) == 1 @@ -150,7 +150,7 @@ def test_a_slow_charge_is_recorded_as_processing_before_the_slow_part(client, mo try: assert _charge(client, "saga-1").get_json()["result"]["status"] == "APPROVED" finally: - routes._mode["value"] = "healthy" + routes.SWITCH.value = "healthy" assert seen_while_slow == ["PROCESSING"] # a void during the slow part sees it in flight diff --git a/shared/shop_common/flask_support.py b/shared/shop_common/flask_support.py index d37c33e..230c4aa 100644 --- a/shared/shop_common/flask_support.py +++ b/shared/shop_common/flask_support.py @@ -46,6 +46,34 @@ def chaos_enabled() -> bool: return os.environ.get("CHAOS_ENABLED") == "1" +def switches_off() -> Response: + """The one answer every demo switch gives when CHAOS_ENABLED is not 1.""" + response = jsonify({"message": "Demo switches are off (CHAOS_ENABLED is not 1)"}) + response.status_code = 403 + return response + + +class DemoSwitch: + """A lab switch held in memory, one value per process: a demo setting, not data. + GET reads it; POST {"mode": ...} sets it, only when CHAOS_ENABLED=1.""" + + def __init__(self, *modes: str): + self.modes = modes + self.value = modes[0] + + def respond(self) -> Response: + if request.method == "POST": + if not chaos_enabled(): + return switches_off() + mode = (request.get_json(silent=True) or request.form.to_dict()).get("mode") + if mode not in self.modes: + response = jsonify({"message": f"mode must be one of {list(self.modes)}"}) + response.status_code = 400 + return response + self.value = mode + return jsonify({"mode": self.value, "modes": list(self.modes), "enabled": chaos_enabled()}) + + def install(app: Flask, service_name: str, db) -> None: init_tracing(service_name) this_instance = instance_id(service_name) diff --git a/tests/smoke/test_post_run.py b/tests/smoke/test_post_run.py index 2ea3fb1..97997e7 100644 --- a/tests/smoke/test_post_run.py +++ b/tests/smoke/test_post_run.py @@ -254,6 +254,68 @@ def test_demo_13_a_charge_payment_never_took_is_voided_and_the_stock_goes_back() assert _wait_for(lambda: {httpx.get(f"{api}/call").json()["outcome"] for _ in range(2)} == {"ok"}, seconds=20) +def _inventory_mode(mode: str) -> None: + assert httpx.post(f"{GATEWAY_URL}/api/shop/inventory/chaos", json={"mode": mode}).status_code == 200 + + +def _hold(saga_id: str) -> dict | None: + holds = httpx.get(f"{GATEWAY_URL}/api/shop/inventory/reservations").json()["results"] + return next((h for h in holds if h["reservation_id"] == saga_id), None) + + +def test_demo_14_a_release_that_beats_its_slow_hold_leaves_the_stock_untouched(): + _require_stack() + import time + + headers = _login_with_cart() + before = _stock(1) + _inventory_mode("slow_reserve") + try: + sent = time.monotonic() + r = httpx.post(f"{GATEWAY_URL}/api/shop/order/checkout", headers=headers, timeout=15) + assert r.status_code == 503, r.text # the saga gave up on the hold after 3 s + time.sleep(max(0.0, sent + 8 - time.monotonic())) # past the late hold, which lands at about 6 s + finally: + _inventory_mode("healthy") + hold = _hold(r.json()["saga_id"]) + assert hold is not None and hold["status"] == "RELEASED" and hold["items"] == [], hold + assert _stock(1) == before + + +def test_demo_14_a_release_that_times_out_and_arrives_twice_counts_once(): + _require_stack() + headers = _login_with_cart() + before = _stock(1) + _inventory_mode("slow_release") + try: + r = httpx.post(f"{GATEWAY_URL}/api/shop/order/checkout", json={"simulate_decline": True}, headers=headers, timeout=15) + assert r.status_code == 402, r.text + saga_id = r.json()["saga_id"] + assert _wait_for(lambda: (_hold(saga_id) or {}).get("status") == "RELEASED") # the event copy + finally: + _inventory_mode("healthy") + assert _wait_for(lambda: _hold(saga_id)["releases_received"] == 2), _hold(saga_id) # the direct call, at 6 s + assert _stock(1) == before + + +def test_demo_14_replayed_events_are_skipped_and_the_sale_counts_once(): + _require_stack() + headers = _login_with_cart() + before = _stock(1) + r = httpx.post(f"{GATEWAY_URL}/api/shop/order/checkout", headers=headers, timeout=15) + assert r.status_code == 200, r.text + assert _wait_for(lambda: _stock(1)["on_hand"] == before["on_hand"] - 3) + sold = _stock(1) + counts = lambda: httpx.get(f"{GATEWAY_URL}/api/shop/inventory/events").json() # noqa: E731 + start = counts() + replay = httpx.post(f"{GATEWAY_URL}/api/shop/order/sagas/{r.json()['saga_id']}/replay", headers=headers) + assert replay.json()["replayed"] == 3, replay.text + # OrderConfirmed again: skipped, not sold twice. StockReserved and PaymentCharged: ignored. + assert _wait_for(lambda: counts()["duplicates_skipped"] >= start["duplicates_skipped"] + 1) + assert _wait_for(lambda: counts()["not_handled"] >= start["not_handled"] + 2) + assert _stock(1) == sold + + def test_events_wait_in_the_outbox_while_the_bus_is_down_then_drain(): _require_stack() api = f"{GATEWAY_URL}/api/patterns/events"