1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
508
509
510
511
512
513
514
515
516
517
518
519
520
521
522
523
524
525
526
527
528
529
530
531
532
533
534
535
536
537
538
539
540
541
542
543
544
545
546
547
548
549
550
551
552
553
554
555
556
557
558
559
560
561
562
563
564
565
566
567
568
569
570
571
572
573
574
575
576
577
578
579
580
581
582
583
584
585
586
587
588
589
590
591
592
593
594
595
596
597
598
599
600
601
602
603
604
605
606
607
608
609
610
611
612
613
614
615
616
617
618
619
620
621
622
623
624
625
626
627
628
629
630
631
632
633
634
635
636
637
638
639
640
641
642
643
644
645
646
647
648
649
650
651
652
653
654
655
656
657
658
659
660
661
662
663
664
665
666
667
668
669
670
671
672
673
674
675
676
677
678
679
680
681
682
683
684
685
686
687
688
689
690
691
692
693
694
695
696
697
698
699
700
701
702
703
704
705
706
707
708
709
710
711
712
713
714
715
716
717
718
719
720
721
722
723
724
725
726
727
728
729
730
731
732
733
734
735
736
737
738
739
740
741
742
743
744
745
746
747
748
749
750
751
752
753
754
755
756
757
758
759
760
761
762
763
764
765
766
767
768
769
770
771
772
773
774
775
776
777
778
779
780
781
782
783
784
785
786
787
788
789
790
791
792
793
794
795
796
797
798
799
800
801
802
803
804
805
806
807
808
809
810
811
812
813
814
815
816
817
818
819
820
821
822
823
824
825
826
827
828
829
830
831
832
833
834
835
836
837
838
839
840
841
842
843
844
845
846
847
848
849
850
851
852
853
854
855
856
857
858
859
860
861
862
863
864
865
866
867
868
869
870
871
872
873
874
875
876
877
878
879
880
881
882
883
884
885
886
887
888
889
890
891
892
893
894
895
896
897
898
899
900
901
902
903
904
905
906
907
908
909
910
911
912
913
914
915
916
917
918
919
920
921
922
923
924
925
926
927
928
929
930
931
932
933
934
935
936
937
938
939
940
941
942
943
944
945
946
947
948
949
950
951
952
953
954
955
956
957
958
959
960
961
962
963
964
965
966
967
968
969
970
971
972
973
974
975
976
977
978
979
980
981
982
983
984
985
986
987
988
989
990
991
992
993
994
995
996
997
998
999
1000
1001
1002
1003
1004
1005
1006
1007
1008
1009
1010
1011
1012
1013
1014
1015
1016
1017
1018
1019
1020
1021
1022
1023
1024
1025
1026
1027
1028
1029
1030
1031
1032
1033
1034
1035
1036
1037
1038
1039
1040
1041
1042
1043
1044
1045
1046
1047
1048
1049
1050
1051
1052
1053
1054
1055
1056
1057
1058
1059
1060
1061
1062
1063
1064
1065
1066
1067
1068
1069
1070
1071
1072
1073
1074
1075
1076
1077
1078
|
<html><head><meta charset="utf-8" /><link href="https://maxcdn.bootstrapcdn.com/bootstrap/3.3.6/css/bootstrap.min.css" rel="stylesheet" type="text/css" /><link href="https://maxcdn.bootstrapcdn.com/font-awesome/4.5.0/css/font-awesome.min.css" rel="stylesheet" type="text/css" /><link href="https://cdnjs.cloudflare.com/ajax/libs/highlight.js/9.1.0/styles/github-gist.min.css" rel="stylesheet" type="text/css" /><title>Cask: a Scala HTTP micro-framework</title><style>@media (min-width: 60em) {.WideStyles-header{
bottom: 0px;
display: flex;
flex-direction: column;
justify-content: center;
position: fixed;
top: 0px;
width: 25%;
}
.WideStyles-tableOfContentsItem{
display: inline-block;
overflow: hidden;
text-overflow: ellipsis;
vertical-align: middle;
width: 100%;
}
.WideStyles-tableOfContents{
display: flex;
flex-direction: column;
flex-grow: 1;
flex-shrink: 1;
min-height: 0px;
width: 100%;
}
.WideStyles-content{
box-sizing: border-box;
margin-left: 25%;
padding: 48px;
}
.WideStyles-footer{
bottom: 0px;
height: 50px;
position: fixed;
width: 25%;
}
.WideStyles-marginLeftZero{
margin-left: 0px;
}
}</style><style>@media (max-width: 60em) {.NarrowStyles-header{
margin-bottom: 10px;
}
.NarrowStyles-content{
padding: 16px;
}
.NarrowStyles-headerContent{
align-items: center;
display: flex;
flex-direction: row;
width: 100%;
}
.NarrowStyles-flexFont{
font-size: 4vw;
}
.NarrowStyles-disappear{
display: none;
}
.NarrowStyles-floatLeft{
float: left;
margin-left: 30px;
}
}</style><style>.Styles-hoverBox{
align-items: center;
display: flex;
flex-direction: row;
justify-content: space-between;
}
.Styles-hoverBox:hover .Styles-hoverLink{
opacity: 0.5;
}
.Styles-hoverLink{
opacity: 0.1;
}
.Styles-hoverLink:hover{
opacity: 1.0;
}
.Styles-headerStyle{
background-color: rgb(61, 79, 93);
box-sizing: border-box;
display: flex;
}
.Styles-headerLinkBox{
display: flex;
flex: 1;
flex-direction: column;
}
.Styles-headerLink{
align-items: center;
display: flex;
flex: 1;
justify-content: center;
padding: 10px 10px;
}
.Styles-footerStyle{
color: rgb(158, 167, 174);
display: flex;
justify-content: center;
}
.Styles-subtleLink{
text-decoration: none;
}
</style><script src="https://cdnjs.cloudflare.com/ajax/libs/highlight.js/9.1.0/highlight.min.js"></script><script src="https://cdnjs.cloudflare.com/ajax/libs/highlight.js/9.1.0/languages/scala.min.js"></script><script>hljs.initHighlightingOnLoad();</script><meta name="viewport" content="initial-scale = 1.0,maximum-scale = 1.0" /></head><body style="margin: 0px;background-color: #f8f8f8;"><div class=" WideStyles-header NarrowStyles-header Styles-headerStyle"><div class=" NarrowStyles-headerContent"><h1 style="text-align: center;padding: 30px 30px;margin: 0px;"><a style="color: #f8f8f8;font-weight: bold;" href="" class=" Styles-subtleLink NarrowStyles-flexFont"> Cask</a></h1><div class=" Styles-headerLinkBox"><div class=" WideStyles-tableOfContents" style="color: #f8f8f8;"><div style="padding-left: 40px;" class=" NarrowStyles-disappear"><b>Pages</b></div><div style="overflow-y: auto;flex-shrink: 1;min-height: 0px;"><ul style="overflow: hidden;text-align: start;margin-top: 10px;white-space: nowrap;text-overflow: ellipsis;margin-right: 10px;"><li class=" WideStyles-marginLeftZero NarrowStyles-floatLeft"><a style="color: #f8f8f8;" class=" WideStyles-tableOfContentsItem" href="index.html">Cask: a Scala HTTP micro-framework</a></li><li class=" WideStyles-marginLeftZero NarrowStyles-floatLeft"><a style="color: #f8f8f8;" class=" WideStyles-tableOfContentsItem" href="page/main-customization.html">Main Customization</a></li><li class=" WideStyles-marginLeftZero NarrowStyles-floatLeft"><a style="color: #f8f8f8;" class=" WideStyles-tableOfContentsItem" href="page/about-cask.html">About Cask</a></li></ul></div></div></div></div><hr class=" NarrowStyles-disappear" style="background-color: #f8f8f8;width: 80%;" /><div class=" WideStyles-tableOfContents NarrowStyles-disappear" style="color: #f8f8f8;"><div style="padding-left: 40px;" class=" NarrowStyles-disappear"><b>Table of Contents</b></div><div style="overflow-y: auto;flex-shrink: 1;min-height: 0px;"><ul style="overflow: hidden;text-align: start;margin-top: 10px;white-space: nowrap;text-overflow: ellipsis;margin-right: 10px;"><li style="margin-left: 0px;"><a style="color: #f8f8f8;" class=" WideStyles-tableOfContentsItem" href="#getting-started">Getting Started</a></li><li style="margin-left: 0px;"><a style="color: #f8f8f8;" class=" WideStyles-tableOfContentsItem" href="#minimal-example">Minimal Example</a></li><li style="margin-left: 0px;"><a style="color: #f8f8f8;" class=" WideStyles-tableOfContentsItem" href="#variable-routes">Variable Routes</a></li><li style="margin-left: 0px;"><a style="color: #f8f8f8;" class=" WideStyles-tableOfContentsItem" href="#multi-method-routes">Multi-method Routes</a></li><li style="margin-left: 0px;"><a style="color: #f8f8f8;" class=" WideStyles-tableOfContentsItem" href="#receiving-form-encoded-or-json-data">Receiving Form-encoded or JSON data</a></li><li style="margin-left: 0px;"><a style="color: #f8f8f8;" class=" WideStyles-tableOfContentsItem" href="#processing-cookies">Processing Cookies</a></li><li style="margin-left: 0px;"><a style="color: #f8f8f8;" class=" WideStyles-tableOfContentsItem" href="#serving-static-files">Serving Static Files</a></li><li style="margin-left: 0px;"><a style="color: #f8f8f8;" class=" WideStyles-tableOfContentsItem" href="#redirects-or-aborts">Redirects or Aborts</a></li><li style="margin-left: 0px;"><a style="color: #f8f8f8;" class=" WideStyles-tableOfContentsItem" href="#html-rendering">HTML Rendering</a></li><li style="margin-left: 0px;"><a style="color: #f8f8f8;" class=" WideStyles-tableOfContentsItem" href="#extending-endpoints-with-decorators">Extending Endpoints with Decorators</a></li><li style="margin-left: 0px;"><a style="color: #f8f8f8;" class=" WideStyles-tableOfContentsItem" href="#custom-endpoints">Custom Endpoints</a></li><li style="margin-left: 0px;"><a style="color: #f8f8f8;" class=" WideStyles-tableOfContentsItem" href="#gzip--deflated-responses">Gzip & Deflated Responses</a></li><li style="margin-left: 0px;"><a style="color: #f8f8f8;" class=" WideStyles-tableOfContentsItem" href="#websockets">Websockets</a></li><li style="margin-left: 0px;"><a style="color: #f8f8f8;" class=" WideStyles-tableOfContentsItem" href="#todomvc-api-server">TodoMVC Api Server</a></li><li style="margin-left: 0px;"><a style="color: #f8f8f8;" class=" WideStyles-tableOfContentsItem" href="#todomvc-database-integration">TodoMVC Database Integration</a></li><li style="margin-left: 0px;"><a style="color: #f8f8f8;" class=" WideStyles-tableOfContentsItem" href="#todomvc-full-stack-web">TodoMVC Full Stack Web</a></li></ul></div></div></div><div class=" WideStyles-content NarrowStyles-content" style="max-width: 900px;"><h1>Cask: a Scala HTTP micro-framework</h1><div style="margin-bottom: 10px;"><div style="display: flex;flex-direction: row;justify-content: space-between;"><div></div><a href="page/main-customization.html">Main Customization <i class="fa fa-arrow-right" aria-hidden="true"></i></a></div></div><p><a href="https://travis-ci.org/lihaoyi/cask"><div style="text-align: center"><img src="https://travis-ci.org/lihaoyi/cask.svg" alt="Build Status" style="max-width: 100%; max-height: 500px" /></div></a> <a href="https://gitter.im/lihaoyi/cask?utm_source=badge&utm_medium=badge&utm_campaign=pr-badge&utm_content=badge"><div style="text-align: center"><img src="https://badges.gitter.im/Join%20Chat.svg" alt="Gitter Chat" style="max-width: 100%; max-height: 500px" /></div></a> <a href="https://www.patreon.com/lihaoyi"><div style="text-align: center"><img src="https://img.shields.io/badge/patreon-sponsor-ff69b4.svg" alt="Patreon" style="max-width: 100%; max-height: 500px" /></div></a></p>
<pre style="background-color: #f8f8f8"><code style="white-space:pre; background-color: #f8f8f8" class="scala">package app
object MinimalApplication extends cask.MainRoutes{
@cask.get("/")
def hello() = {
"Hello World!"
}
@cask.post("/do-thing")
def doThing(request: cask.Request) = {
new String(request.readAllBytes()).reverse
}
initialize()
}
</code></pre>
<ul>
<li><a href="https://github.com/lihaoyi/cask/releases/download/0.3.6/minimalApplication-0.3.6.zip">example project</a></li>
</ul>
<p><a href="https://github.com/lihaoyi/cask">Cask</a> is a simple Scala web framework inspired by Python's <a href="http://flask.pocoo.org/docs/1.0/">Flask</a> project. It aims to bring simplicity, flexibility and ease-of-use to Scala webservers, avoiding cryptic DSLs or complicated asynchrony.</p><h2 id="getting-started" class="Styles-hoverBox">Getting Started<a href="#getting-started" class=" Styles-hoverLink"><i class="fa fa-link" aria-hidden="true"></i></a></h2>
<p>The easiest way to begin using Cask is by downloading the example project above.</p>
<p>Unzip one of the example projects available on this page (e.g. above) into a folder. This should give you the following files:</p>
<pre style="background-color: #f8f8f8"><code style="white-space:pre; background-color: #f8f8f8" class="text">build.sc
app/src/MinimalExample.scala
app/test/src/ExampleTests.scala
</code></pre>
<ul>
<li><code>cd</code> into the folder, and run</li>
</ul>
<pre style="background-color: #f8f8f8"><code style="white-space:pre; background-color: #f8f8f8" class="bash">./mill -w app.runBackground
</code></pre>
<p>This will server up the Cask application on <code>http://localhost:8080</code>. You can immediately start interacting with it either via the browser, or programmatically via <code>curl</code> or a HTTP client like <a href="https://github.com/lihaoyi/requests-scala">Requests-Scala</a>:</p>
<pre style="background-color: #f8f8f8"><code style="white-space:pre; background-color: #f8f8f8" class="scala">val host = "http://localhost:8080"
val success = requests.get(host)
success.text() ==> "Hello World!"
success.statusCode ==> 200
requests.get(host + "/doesnt-exist").statusCode ==> 404
requests.post(host + "/do-thing", data = "hello").text() ==> "olleh"
requests.get(host + "/do-thing").statusCode ==> 404
</code></pre>
<p>These HTTP calls are part of the test suite for the example project, which you can run using:</p>
<pre style="background-color: #f8f8f8"><code style="white-space:pre; background-color: #f8f8f8" class="bash">./mill -w app.test
</code></pre>
<p>To configure your Cask application to work with IntelliJ, you can use:</p>
<pre style="background-color: #f8f8f8"><code style="white-space:pre; background-color: #f8f8f8" class="bash">./mill mill.scalalib.GenIdea/idea
</code></pre>
<p>This will need to be re-run when you re-configure your <code>build.sc</code> file, e.g. when adding additional modules or third-party dependencies.</p>
<p>Cask is just a Scala library, and you can use Cask in any existing Scala project via the following coordinates:</p>
<pre style="background-color: #f8f8f8"><code style="white-space:pre; background-color: #f8f8f8" class="scala">// Mill
ivy"com.lihaoyi::cask:0.3.6"
// SBT
"com.lihaoyi" %% "cask" % "0.3.6"
</code></pre>
<p>The <code>./mill</code> command is just a wrapper around the <a href="http://www.lihaoyi.com/mill/">Mill build tool</a>; the <code>build.sc</code> files you see in all examples are Mill build files, and you can use your own installation of Mill instead of <code>./mill</code> if you wish. All normal Mill commands and functionality works for <code>./mill</code>.</p>
<p>The following examples will walk you through how to use Cask to accomplish tasks common to anyone writing a web application. Each example comes with a downloadable example project with code and unit tests, which you can use via the same <code>./mill -w app.runBackground</code> or <code>./mill -w app.test</code> workflows we saw above.</p><h2 id="minimal-example" class="Styles-hoverBox">Minimal Example<a href="#minimal-example" class=" Styles-hoverLink"><i class="fa fa-link" aria-hidden="true"></i></a></h2>
<pre style="background-color: #f8f8f8"><code style="white-space:pre; background-color: #f8f8f8" class="scala">package app
object MinimalApplication extends cask.MainRoutes{
@cask.get("/")
def hello() = {
"Hello World!"
}
@cask.post("/do-thing")
def doThing(request: cask.Request) = {
new String(request.readAllBytes()).reverse
}
initialize()
}
</code></pre>
<ul>
<li><a href="https://github.com/lihaoyi/cask/releases/download/0.3.6/minimalApplication-0.3.6.zip">example project</a></li>
</ul>
<p>The rough outline of how the minimal example works should be easy to understand:</p>
<ul>
<li>
<p>You define an object that inherits from <code>cask.MainRoutes</code></p></li>
<li>
<p>Define endpoints using annotated functions, using <code>@cask.get</code> or <code>@cask.post</code> with the route they should match</p></li>
<li>
<p>Each function can return the data you want in the response, or a <code>cask.Response</code> if you want further customization: response code, headers, etc.</p></li>
<li>
<p>Your function can tale an optional <code>cask.Request</code>, which exposes the entire incoming HTTP request if necessary. In the above example, we use it to read the request body into a string and return it reversed.</p></li>
</ul>
<p>In most cases, Cask provides convenient helpers to extract exactly the data from the incoming HTTP request that you need, while also de-serializing it into the data type you need and returning meaningful errors if they are missing. Thus, although you can always get all the data necessary through <code>cask.Request</code>, it is often more convenient to use another way, which will go into below.</p>
<p>As your application grows, you will likely want to split up the routes into separate files, themselves separate from any configuration of the Main entrypoint (e.g. overriding the port, host, default error handlers, etc.). You can do this by splitting it up into <code>cask.Routes</code> and <code>cask.Main</code> objects:</p>
<pre style="background-color: #f8f8f8"><code style="white-space:pre; background-color: #f8f8f8" class="scala">package app
case class MinimalRoutes()(implicit val log: cask.Logger) extends cask.Routes{
@cask.get("/")
def hello() = {
"Hello World!"
}
@cask.post("/do-thing")
def doThing(request: cask.Request) = {
new String(request.readAllBytes()).reverse
}
initialize()
}
object MinimalRoutesMain extends cask.Main{
val allRoutes = Seq(MinimalRoutes())
}
</code></pre>
<ul>
<li><a href="https://github.com/lihaoyi/cask/releases/download/0.3.6/minimalApplication2-0.3.6.zip">example project</a></li>
</ul>
<p>You can split up your routes into separate <code>cask.Routes</code> objects as makes sense and pass them all into <code>cask.Main</code>.</p><h2 id="variable-routes" class="Styles-hoverBox">Variable Routes<a href="#variable-routes" class=" Styles-hoverLink"><i class="fa fa-link" aria-hidden="true"></i></a></h2>
<pre style="background-color: #f8f8f8"><code style="white-space:pre; background-color: #f8f8f8" class="scala">package app
object VariableRoutes extends cask.MainRoutes{
@cask.get("/user/:userName")
def showUserProfile(userName: String) = {
s"User $userName"
}
@cask.get("/post/:postId")
def showPost(postId: Int, param: Seq[String]) = {
s"Post $postId $param"
}
@cask.get("/path", subpath = true)
def showSubpath(request: cask.Request) = {
s"Subpath ${request.remainingPathSegments}"
}
initialize()
}
</code></pre>
<ul>
<li><a href="https://github.com/lihaoyi/cask/releases/download/0.3.6/variableRoutes-0.3.6.zip">example project</a></li>
</ul>
<p>You can bind variables to endpoints by declaring them as parameters: these are either taken from a path-segment matcher of the same name (e.g. <code>postId</code> above), or from query-parameters of the same name (e.g. <code>param</code> above). You can make <code>param</code> take a <code>: String</code> to match <code>?param=hello</code>, an <code>: Int</code> for <code>?param=123</code> a <code>Seq[T]</code> (as above) for repeated params such as <code>?param=hello&param=world</code>, or <code>: Option[T]</code> for cases where the <code>?param=hello</code> is optional.</p>
<p>If you need to capture the entire sub-path of the request, you can set the flag <code>subpath=true</code> and ask for a <code>: cask.Subpath</code> (the name of the param doesn't matter). This will make the route match any sub-path of the prefix given to the <code>@cask</code> decorator, and give you the remainder to use in your endpoint logic.</p><h2 id="multi-method-routes" class="Styles-hoverBox">Multi-method Routes<a href="#multi-method-routes" class=" Styles-hoverLink"><i class="fa fa-link" aria-hidden="true"></i></a></h2>
<pre style="background-color: #f8f8f8"><code style="white-space:pre; background-color: #f8f8f8" class="scala">package app
object HttpMethods extends cask.MainRoutes{
@cask.route("/login", methods = Seq("get", "post"))
def login(request: cask.Request) = {
if (request.exchange.getRequestMethod.equalToString("post")) "do_the_login"
else "show_the_login_form"
}
initialize()
}
</code></pre>
<ul>
<li><a href="https://github.com/lihaoyi/cask/releases/download/0.3.6/httpMethods-0.3.6.zip">example project</a></li>
</ul>
<p>Sometimes, you may want to handle multiple kinds of HTTP requests in the same endpoint function, e.g. with code that can accept both GETs and POSTs and decide what to do in each case. You can use the <code>@cask.route</code> annotation to do so</p><h2 id="receiving-form-encoded-or-json-data" class="Styles-hoverBox">Receiving Form-encoded or JSON data<a href="#receiving-form-encoded-or-json-data" class=" Styles-hoverLink"><i class="fa fa-link" aria-hidden="true"></i></a></h2>
<pre style="background-color: #f8f8f8"><code style="white-space:pre; background-color: #f8f8f8" class="scala">package app
object FormJsonPost extends cask.MainRoutes{
@cask.postJson("/json")
def jsonEndpoint(value1: ujson.Value, value2: Seq[Int]) = {
"OK " + value1 + " " + value2
}
@cask.postForm("/form")
def formEndpoint(value1: cask.FormValue, value2: Seq[Int]) = {
"OK " + value1 + " " + value2
}
@cask.postForm("/upload")
def uploadFile(image: cask.FormFile) = {
image.fileName
}
initialize()
}
</code></pre>
<ul>
<li><a href="https://github.com/lihaoyi/cask/releases/download/0.3.6/formJsonPost-0.3.6.zip">example project</a></li>
</ul>
<p>If you need to handle a JSON-encoded POST request, you can use the <code>@cask.postJson</code> decorator. This assumes the posted request body is a JSON dict, and uses its keys to populate the endpoint's parameters, either as raw <code>ujson.Value</code>s or deserialized into <code>Seq[Int]</code>s or other things. Deserialization is handled using the <a href="https://github.com/lihaoyi/upickle">uPickle</a> JSON library, though you could write your own version of <code>postJson</code> to work with any other JSON library of your choice.</p>
<p>Similarly, you can mark endpoints as <code>@cask.postForm</code>, in which case the endpoints params will be taken from the form-encoded POST body either raw (as <code>cask.FormValue</code>s) or deserialized into simple data structures. Use <code>cask.FormFile</code> if you want the given form value to be a file upload.</p>
<p>Both normal forms and multipart forms are handled the same way.</p>
<p>If the necessary keys are not present in the JSON/form-encoded POST body, or the deserialization into Scala data-types fails, a 400 response is returned automatically with a helpful error message.</p><h2 id="processing-cookies" class="Styles-hoverBox">Processing Cookies<a href="#processing-cookies" class=" Styles-hoverLink"><i class="fa fa-link" aria-hidden="true"></i></a></h2>
<pre style="background-color: #f8f8f8"><code style="white-space:pre; background-color: #f8f8f8" class="scala">package app
object Cookies extends cask.MainRoutes{
@cask.get("/read-cookie")
def readCookies(username: cask.Cookie) = {
username.value
}
@cask.get("/store-cookie")
def storeCookies() = {
cask.Response(
"Cookies Set!",
cookies = Seq(cask.Cookie("username", "the username"))
)
}
@cask.get("/delete-cookie")
def deleteCookie() = {
cask.Response(
"Cookies Deleted!",
cookies = Seq(cask.Cookie("username", "", expires = java.time.Instant.EPOCH))
)
}
initialize()
}
</code></pre>
<ul>
<li><a href="https://github.com/lihaoyi/cask/releases/download/0.3.6/cookies-0.3.6.zip">example project</a></li>
</ul>
<p>Cookies are most easily read by declaring a <code>: cask.Cookie</code> parameter; the parameter name is used to fetch the cookie you are interested in. Cookies can be stored by setting the <code>cookie</code> attribute in the response, and deleted simply by setting <code>expires = java.time.Instant.EPOCH</code> (i.e. to have expired a long time ago)</p><h2 id="serving-static-files" class="Styles-hoverBox">Serving Static Files<a href="#serving-static-files" class=" Styles-hoverLink"><i class="fa fa-link" aria-hidden="true"></i></a></h2>
<pre style="background-color: #f8f8f8"><code style="white-space:pre; background-color: #f8f8f8" class="scala">package app
object StaticFiles extends cask.MainRoutes{
@cask.get("/")
def index() = {
"Hello!"
}
@cask.staticFiles("/static/file")
def staticFileRoutes() = "app/resources/cask"
@cask.staticResources("/static/resource")
def staticResourceRoutes() = "cask"
@cask.staticResources("/static/resource2")
def staticResourceRoutes2() = "."
initialize()
}
</code></pre>
<ul>
<li><a href="https://github.com/lihaoyi/cask/releases/download/0.3.6/staticFiles-0.3.6.zip">example project</a></li>
</ul>
<p>You can ask Cask to serve static files by defining a <code>@cask.staticFiles</code> endpoint. This will match any subpath of the value returned by the endpoint (e.g. above <code>/static/file.txt</code>, <code>/static/folder/file.txt</code>, etc.) and return the file contents from the corresponding file on disk (and 404 otherwise).</p>
<p>Similarly, <code>@cask.staticResources</code> attempts to serve a request based on the JVM resource path, returning the data if a resource is present and a 404 otherwise.</p>
<p>You can also configure the <code>headers</code> you wish to return to static file requests, or use <code>@cask.decorators.compress</code> to compress the responses:</p>
<pre style="background-color: #f8f8f8"><code style="white-space:pre; background-color: #f8f8f8" class="scala">package app
object StaticFiles2 extends cask.MainRoutes{
@cask.get("/")
def index() = {
"Hello!"
}
@cask.staticFiles("/static/file", headers = Seq("Cache-Control" -> "max-age=31536000"))
def staticFileRoutes() = "app/resources/cask"
@cask.decorators.compress
@cask.staticResources("/static/resource")
def staticResourceRoutes() = "cask"
@cask.staticResources("/static/resource2")
def staticResourceRoutes2() = "."
initialize()
}
</code></pre>
<ul>
<li><a href="https://github.com/lihaoyi/cask/releases/download/0.3.6/staticFiles2-0.3.6.zip">example project</a></li>
</ul><h2 id="redirects-or-aborts" class="Styles-hoverBox">Redirects or Aborts<a href="#redirects-or-aborts" class=" Styles-hoverLink"><i class="fa fa-link" aria-hidden="true"></i></a></h2>
<pre style="background-color: #f8f8f8"><code style="white-space:pre; background-color: #f8f8f8" class="scala">package app
object RedirectAbort extends cask.MainRoutes{
@cask.get("/")
def index() = {
cask.Redirect("/login")
}
@cask.get("/login")
def login() = {
cask.Abort(401)
}
initialize()
}
</code></pre>
<ul>
<li><a href="https://github.com/lihaoyi/cask/releases/download/0.3.6/redirectAbort-0.3.6.zip">example project</a></li>
</ul>
<p>Cask provides some convenient helpers <code>cask.Redirect</code> and <code>cask.Abort</code> which you can return; these are simple wrappers around <code>cask.Request</code>, and simply set up the relevant headers or status code for you.</p><h2 id="html-rendering" class="Styles-hoverBox">HTML Rendering<a href="#html-rendering" class=" Styles-hoverLink"><i class="fa fa-link" aria-hidden="true"></i></a></h2>
<p>Cask doesn't come bundled with HTML templating functionality, but it makes it really easy to use community-standard libraries like <a href="https://github.com/lihaoyi/scalatags">Scalatags</a> to render your HTML. Simply adding the relevant <code>ivy"com.lihaoyi::scalatags:0.7.0"</code> dependency to your <code>build.sc</code> file is enough to render Scalatags templates:</p>
<pre style="background-color: #f8f8f8"><code style="white-space:pre; background-color: #f8f8f8" class="scala">package app
import scalatags.Text.all._
object Scalatags extends cask.MainRoutes{
@cask.get("/")
def hello() = {
"<!doctype html>" + html(
body(
h1("Hello World"),
p("I am cow")
)
)
}
initialize()
}
</code></pre>
<ul>
<li><a href="https://github.com/lihaoyi/cask/releases/download/0.3.6/scalatags-0.3.6.zip">example project</a></li>
</ul>
<p>If you prefer to use the <a href="https://www.playframework.com/documentation/2.6.x/ScalaTemplates">Twirl</a> templating engine, you can use that too:</p>
<pre style="background-color: #f8f8f8"><code style="white-space:pre; background-color: #f8f8f8" class="scala">package app
object Twirl extends cask.MainRoutes{
@cask.get("/")
def hello() = {
"<!doctype html>" + html.hello("Hello World")
}
initialize()
}
</code></pre>
<ul>
<li><a href="https://github.com/lihaoyi/cask/releases/download/0.3.6/twirl-0.3.6.zip">example project</a></li>
</ul>
<p>With the following <code>app/views/hello.scala.html</code>:</p>
<pre style="background-color: #f8f8f8"><code style="white-space:pre; background-color: #f8f8f8" class="html">@(titleTxt: String)
<html>
<body>
<h1>@titleTxt</h1>
<p>I am cow</p>
</body>
</html>
</code></pre><h2 id="extending-endpoints-with-decorators" class="Styles-hoverBox">Extending Endpoints with Decorators<a href="#extending-endpoints-with-decorators" class=" Styles-hoverLink"><i class="fa fa-link" aria-hidden="true"></i></a></h2>
<pre style="background-color: #f8f8f8"><code style="white-space:pre; background-color: #f8f8f8" class="scala">package app
object Decorated extends cask.MainRoutes{
class User{
override def toString = "[haoyi]"
}
class loggedIn extends cask.RawDecorator {
def wrapFunction(ctx: cask.Request, delegate: Delegate) = {
delegate(Map("user" -> new User()))
}
}
class withExtra extends cask.RawDecorator {
def wrapFunction(ctx: cask.Request, delegate: Delegate) = {
delegate(Map("extra" -> 31337))
}
}
@withExtra()
@cask.get("/hello/:world")
def hello(world: String)(extra: Int) = {
world + extra
}
@loggedIn()
@cask.get("/internal/:world")
def internal(world: String)(user: User) = {
world + user
}
@withExtra()
@loggedIn()
@cask.get("/internal-extra/:world")
def internalExtra(world: String)(user: User)(extra: Int) = {
world + user + extra
}
@withExtra()
@loggedIn()
@cask.get("/ignore-extra/:world")
def ignoreExtra(world: String)(user: User) = {
world + user
}
initialize()
}
</code></pre>
<ul>
<li><a href="https://github.com/lihaoyi/cask/releases/download/0.3.6/decorated-0.3.6.zip">example project</a></li>
</ul>
<p>You can write extra decorator annotations that stack on top of the existing <code>@cask.get</code>/<code>@cask.post</code> to provide additional arguments or validation. This is done by implementing the <code>cask.Decorator</code> interface and it's <code>getRawParams</code> function. <code>getRawParams</code>:</p>
<ul>
<li>
<p>Receives a <code>Request</code>, which basically gives you full access to the underlying undertow HTTP connection so you can pick out whatever data you would like</p></li>
<li>
<p>Returns an <code>Either[Response, cask.Decor[Any]]</code>. Returning a <code>Left</code> lets you bail out early with a fixed <code>cask.Response</code>, avoiding further processing. Returning a <code>Right</code> provides a map of parameter names and values that will then get passed to the endpoint function in consecutive parameter lists (shown above), as well as an optional cleanup function that is run after the endpoint terminates.</p></li>
</ul>
<p>Each additional decorator is responsible for one additional parameter list to the right of the existing parameter lists, each of which can contain any number of parameters.</p>
<p>Decorators are useful for things like:</p>
<ul>
<li>
<p>Making an endpoint return a HTTP 403 if the user isn't logged in, but if they are logged in providing the <code>: User</code> object to the body of the endpoint function</p></li>
<li>
<p>Rate-limiting users by returning early with a HTTP 429 if a user tries to access an endpoint too many times too quickly</p></li>
<li>
<p>Providing request-scoped values to the endpoint function: perhaps a database transaction that commits when the function succeeds (and rolls-back if it fails), or access to some system resource that needs to be released.</p></li>
</ul>
<p>For decorators that you wish to apply to multiple routes at once, you can define them by overriding the <code>cask.Routes#decorators</code> field (to apply to every endpoint in that routes object) or <code>cask.Main#mainDecorators</code> (to apply to every endpoint, period):</p>
<pre style="background-color: #f8f8f8"><code style="white-space:pre; background-color: #f8f8f8" class="scala">package app
object Decorated2 extends cask.MainRoutes{
class User{
override def toString = "[haoyi]"
}
class loggedIn extends cask.RawDecorator {
def wrapFunction(ctx: cask.Request, delegate: Delegate) = {
delegate(Map("user" -> new User()))
}
}
class withExtra extends cask.RawDecorator {
def wrapFunction(ctx: cask.Request, delegate: Delegate) = {
delegate(Map("extra" -> 31337))
}
}
override def decorators = Seq(new withExtra())
@cask.get("/hello/:world")
def hello(world: String)(extra: Int) = {
world + extra
}
@loggedIn()
@cask.get("/internal-extra/:world")
def internalExtra(world: String)(user: User)(extra: Int) = {
world + user + extra
}
@loggedIn()
@cask.get("/ignore-extra/:world")
def ignoreExtra(world: String)(user: User)(extra: Int) = {
world + user
}
initialize()
}
</code></pre>
<ul>
<li><a href="https://github.com/lihaoyi/cask/releases/download/0.3.6/decorated2-0.3.6.zip">example project</a></li>
</ul>
<p>This is convenient for cases where you want a set of decorators to apply broadly across your web application, and do not want to repeat them over and over at every single endpoint.</p><h2 id="custom-endpoints" class="Styles-hoverBox">Custom Endpoints<a href="#custom-endpoints" class=" Styles-hoverLink"><i class="fa fa-link" aria-hidden="true"></i></a></h2>
<pre style="background-color: #f8f8f8"><code style="white-space:pre; background-color: #f8f8f8" class="scala">package app
class custom(val path: String, val methods: Seq[String])
extends cask.HttpEndpoint[Int, Seq[String]]{
def wrapFunction(ctx: cask.Request, delegate: Delegate) = {
delegate(Map()).map{num =>
cask.Response("Echo " + num, statusCode = num)
}
}
def wrapPathSegment(s: String) = Seq(s)
type InputParser[T] = cask.endpoints.QueryParamReader[T]
}
object Endpoints extends cask.MainRoutes{
@custom("/echo/:status", methods = Seq("get"))
def echoStatus(status: String) = {
status.toInt
}
initialize()
}
</code></pre>
<ul>
<li><a href="https://github.com/lihaoyi/cask/releases/download/0.3.6/endpoints-0.3.6.zip">example project</a></li>
</ul>
<p>When you need more flexibility than decorators allow, you can define your own custom <code>cask.Endpoint</code>s to replace the default set that Cask provides. This allows you to</p>
<ul>
<li>
<p>Change the expected return type of the annotated function, and how allows you to that type gets processed: the above example trivially expects an allows you to <code>Int</code> which becomes the status code, but you could make it e.g. automatically serialize returned objects to JSON responses via your favorite library, or serialize them to bytes via protobufs</p></li>
<li>
<p>Change where the first parameter list's params are taken from: <code>@cask.get</code> takes them from query params, <code>@cask.postForm</code> takes them from the form-encoded POST body, and you can write your own endpoint to take the params from where-ever you like: perhaps from the request headers, or a protobuf- encoded request body</p></li>
<li>
<p>Change how parameters are deserialized: e.g. <code>@cask.postJson</code> de-serializes parameters using the <a href="https://github.com/lihaoyi/upickle">uPickle</a> JSON library, and your own custom endpoint could change that to use another library like <a href="https://github.com/circe/circe">Circe</a> or <a href="https://github.com/FasterXML/jackson-module-scala">Jackson</a></p></li>
<li>
<p>DRY up common sets of decorators: if all your endpoint functions use the same decorators, you can extract that functionality into a single <code>cask.Endpoint</code> to do the job.</p></li>
</ul>
<p>Generally you should not be writing custom <code>cask.Endpoint</code>s every day, but if you find yourself trying to standardize on a way of doing things across your web application, it might make sense to write a custom endpoint decorator: to DRY things up , separate business logic (inside the annotated function) from plumbing (in the endpoint function and decorators), and enforcing a standard of how endpoint functions are written.</p><h2 id="gzip--deflated-responses" class="Styles-hoverBox">Gzip & Deflated Responses<a href="#gzip--deflated-responses" class=" Styles-hoverLink"><i class="fa fa-link" aria-hidden="true"></i></a></h2>
<pre style="background-color: #f8f8f8"><code style="white-space:pre; background-color: #f8f8f8" class="scala">package app
object Compress extends cask.MainRoutes{
@cask.decorators.compress
@cask.get("/")
def hello() = {
"Hello World! Hello World! Hello World!"
}
initialize()
}
</code></pre>
<ul>
<li><a href="https://github.com/lihaoyi/cask/releases/download/0.3.6/compress-0.3.6.zip">example project</a></li>
</ul>
<p>Cask provides a useful <code>@cask.decorators.compress</code> decorator that gzips or deflates a response body if possible. This is useful if you don't have a proxy like Nginx or similar in front of your server to perform the compression for you.</p>
<p>Like all decorators, <code>@cask.decorators.compress</code> can be defined on a level of a set of <code>cask.Routes</code>:</p>
<pre style="background-color: #f8f8f8"><code style="white-space:pre; background-color: #f8f8f8" class="scala">package app
case class Compress2()(implicit val log: cask.Logger) extends cask.Routes{
override def decorators = Seq(new cask.decorators.compress())
@cask.get("/")
def hello() = {
"Hello World! Hello World! Hello World!"
}
initialize()
}
object Compress2Main extends cask.Main{
val allRoutes = Seq(Compress2())
}
</code></pre>
<ul>
<li><a href="https://github.com/lihaoyi/cask/releases/download/0.3.6/compress2-0.3.6.zip">example project</a></li>
</ul>
<p>Or globally, in your <code>cask.Main</code>:</p>
<pre style="background-color: #f8f8f8"><code style="white-space:pre; background-color: #f8f8f8" class="scala">package app
case class Compress3()(implicit val log: cask.Logger) extends cask.Routes{
@cask.get("/")
def hello() = {
"Hello World! Hello World! Hello World!"
}
initialize()
}
object Compress3Main extends cask.Main{
override def mainDecorators = Seq(new cask.decorators.compress())
val allRoutes = Seq(Compress3())
}
</code></pre>
<ul>
<li><a href="https://github.com/lihaoyi/cask/releases/download/0.3.6/compress3-0.3.6.zip">example project</a></li>
</ul><h2 id="websockets" class="Styles-hoverBox">Websockets<a href="#websockets" class=" Styles-hoverLink"><i class="fa fa-link" aria-hidden="true"></i></a></h2>
<pre style="background-color: #f8f8f8"><code style="white-space:pre; background-color: #f8f8f8" class="scala">package app
object Websockets extends cask.MainRoutes{
@cask.websocket("/connect/:userName")
def showUserProfile(userName: String): cask.WebsocketResult = {
if (userName != "haoyi") cask.Response("", statusCode = 403)
else cask.WsHandler { channel =>
cask.WsActor {
case cask.Ws.Text("") => channel.send(cask.Ws.Close())
case cask.Ws.Text(data) =>
channel.send(cask.Ws.Text(userName + " " + data))
}
}
}
initialize()
}
</code></pre>
<ul>
<li><a href="https://github.com/lihaoyi/cask/releases/download/0.3.6/websockets-0.3.6.zip">example project</a></li>
</ul>
<p>Cask's Websocket endpoints are very similar to Cask's HTTP endpoints. Annotated with <code>@cask.websocket</code> instead of <code>@cask.get</code> or <code>@cask.post</code>, the primary difference is that instead of only returning a <code>cask.Response</code>, you now have an option of returning a <code>cask.WsHandler</code>.</p>
<p>The <code>cask.WsHandler</code> allows you to pro-actively start sending websocket messages once a connection has been made, via the <code>channel: WsChannelActor</code> it exposes, and lets you react to messages via the <code>cask.WsActor</code> you create. You can use these two APIs to perform full bi-directional, asynchronous communications, as websockets are intended to be used for. Note that all messages received on a each individual Websocket connection by your <code>cask.WsActor</code> are handled in a single-threaded fashion by default: this means you can work with local mutable state in your <code>@cask.websocket</code> endpoint without worrying about race conditions or multithreading. If you want further parallelism, you can explicitly spin off <code>scala.concurrent.Future</code>s or other <code>cask.BatchActor</code>s to perform that parallel processing.</p>
<p>Returning a <code>cask.Response</code> immediately closes the websocket connection, and is useful if you want to e.g. return a 404 or 403 due to the initial request being invalid.</p>
<p>Cask also provides a lower-lever websocket interface, which allows you directly work with the underlying <code>io.undertow.websockets.WebSocketConnectionCallback</code>:</p>
<pre style="background-color: #f8f8f8"><code style="white-space:pre; background-color: #f8f8f8" class="scala">package app
import io.undertow.websockets.WebSocketConnectionCallback
import io.undertow.websockets.core.{AbstractReceiveListener, BufferedTextMessage, WebSocketChannel, WebSockets}
import io.undertow.websockets.spi.WebSocketHttpExchange
object Websockets2 extends cask.MainRoutes{
@cask.websocket("/connect/:userName")
def showUserProfile(userName: String): cask.WebsocketResult = {
if (userName != "haoyi") cask.Response("", statusCode = 403)
else new WebSocketConnectionCallback() {
override def onConnect(exchange: WebSocketHttpExchange, channel: WebSocketChannel): Unit = {
channel.getReceiveSetter.set(
new AbstractReceiveListener() {
override def onFullTextMessage(channel: WebSocketChannel, message: BufferedTextMessage) = {
message.getData match{
case "" => channel.close()
case data => WebSockets.sendTextBlocking(userName + " " + data, channel)
}
}
}
)
channel.resumeReceives()
}
}
}
initialize()
}
</code></pre>
<ul>
<li><a href="https://github.com/lihaoyi/cask/releases/download/0.3.6/websockets2-0.3.6.zip">example project</a></li>
</ul>
<p>It leaves it up to you to manage open channels, react to incoming messages, or pro-actively send them out, mostly using the underlying Undertow webserver interface. While Cask does not model streams, backpressure, iteratees, or provide any higher level API, it should not be difficult to take the Cask API and build whatever higher-level abstractions you prefer to use.</p>
<p>If you are separating your <code>cask.Routes</code> from your <code>cask.Main</code>, you need to inject in a <code>cask.Logger</code> to handle errors reported when handling websocket requests:</p>
<pre style="background-color: #f8f8f8"><code style="white-space:pre; background-color: #f8f8f8" class="scala">package app
case class Websockets3()(implicit val log: cask.Logger) extends cask.Routes{
@cask.websocket("/connect/:userName")
def showUserProfile(userName: String): cask.WebsocketResult = {
if (userName != "haoyi") cask.Response("", statusCode = 403)
else cask.WsHandler { channel =>
cask.WsActor {
case cask.Ws.Text("") => channel.send(cask.Ws.Close())
case cask.Ws.Text(data) =>
channel.send(cask.Ws.Text(userName + " " + data))
}
}
}
initialize()
}
object Websockets3Main extends cask.Main{
val allRoutes = Seq(Websockets3())
}
</code></pre>
<ul>
<li><a href="https://github.com/lihaoyi/cask/releases/download/0.3.6/websockets3-0.3.6.zip">example project</a></li>
</ul><h2 id="todomvc-api-server" class="Styles-hoverBox">TodoMVC Api Server<a href="#todomvc-api-server" class=" Styles-hoverLink"><i class="fa fa-link" aria-hidden="true"></i></a></h2>
<pre style="background-color: #f8f8f8"><code style="white-space:pre; background-color: #f8f8f8" class="scala">package app
object TodoMvcApi extends cask.MainRoutes{
case class Todo(checked: Boolean, text: String)
object Todo{
implicit def todoRW = upickle.default.macroRW[Todo]
}
var todos = Seq(
Todo(true, "Get started with Cask"),
Todo(false, "Profit!")
)
@cask.get("/list/:state")
def list(state: String) = {
val filteredTodos = state match{
case "all" => todos
case "active" => todos.filter(!_.checked)
case "completed" => todos.filter(_.checked)
}
upickle.default.write(filteredTodos)
}
@cask.post("/add")
def add(request: cask.Request) = {
todos = Seq(Todo(false, new String(request.readAllBytes()))) ++ todos
}
@cask.post("/toggle/:index")
def toggle(index: Int) = {
todos = todos.updated(index, todos(index).copy(checked = !todos(index).checked))
}
@cask.post("/delete/:index")
def delete(index: Int) = {
todos = todos.patch(index, Nil, 1)
}
initialize()
}
</code></pre>
<ul>
<li><a href="https://github.com/lihaoyi/cask/releases/download/0.3.6/todoApi-0.3.6.zip">example project</a></li>
</ul>
<p>This is a simple self-contained example of using Cask to write an in-memory API server for the common <a href="http://todomvc.com/">TodoMVC example app</a>.</p>
<p>This minimal example intentionally does not contain javascript, HTML, styles, etc.. Those can be managed via the normal mechanism for <a href="#serving-static-files">Serving Static Files</a>.</p><h2 id="todomvc-database-integration" class="Styles-hoverBox">TodoMVC Database Integration<a href="#todomvc-database-integration" class=" Styles-hoverLink"><i class="fa fa-link" aria-hidden="true"></i></a></h2>
<pre style="background-color: #f8f8f8"><code style="white-space:pre; background-color: #f8f8f8" class="scala">package app
import com.typesafe.config.ConfigFactory
import io.getquill.{SqliteJdbcContext, SnakeCase}
object TodoMvcDb extends cask.MainRoutes{
val tmpDb = java.nio.file.Files.createTempDirectory("todo-cask-sqlite")
object ctx extends SqliteJdbcContext(
SnakeCase,
ConfigFactory.parseString(
s"""{"driverClassName":"org.sqlite.JDBC","jdbcUrl":"jdbc:sqlite:$tmpDb/file.db"}"""
)
)
class transactional extends cask.RawDecorator{
class TransactionFailed(val value: cask.router.Result.Error) extends Exception
def wrapFunction(pctx: cask.Request, delegate: Delegate) = {
try ctx.transaction(
delegate(Map()) match{
case cask.router.Result.Success(t) => cask.router.Result.Success(t)
case e: cask.router.Result.Error => throw new TransactionFailed(e)
}
)
catch{case e: TransactionFailed => e.value}
}
}
case class Todo(id: Int, checked: Boolean, text: String)
object Todo{
implicit def todoRW = upickle.default.macroRW[Todo]
}
ctx.executeAction(
"""CREATE TABLE todo (
id INTEGER PRIMARY KEY AUTOINCREMENT,
checked BOOLEAN,
text TEXT
);
""".stripMargin
)
ctx.executeAction(
"""INSERT INTO todo (checked, text) VALUES
(1, 'Get started with Cask'),
(0, 'Profit!');
""".stripMargin
)
import ctx._
@transactional
@cask.get("/list/:state")
def list(state: String) = {
val filteredTodos = state match{
case "all" => run(query[Todo])
case "active" => run(query[Todo].filter(!_.checked))
case "completed" => run(query[Todo].filter(_.checked))
}
upickle.default.write(filteredTodos)
}
@transactional
@cask.post("/add")
def add(request: cask.Request) = {
val body = new String(request.readAllBytes())
run(
query[Todo]
.insert(_.checked -> lift(false), _.text -> lift(body))
.returningGenerated(_.id)
)
}
@transactional
@cask.post("/toggle/:index")
def toggle(index: Int) = {
run(query[Todo].filter(_.id == lift(index)).update(p => p.checked -> !p.checked))
}
@transactional
@cask.post("/delete/:index")
def delete(index: Int) = {
run(query[Todo].filter(_.id == lift(index)).delete)
}
initialize()
}
</code></pre>
<ul>
<li><a href="https://github.com/lihaoyi/cask/releases/download/0.3.6/todoDb-0.3.6.zip">example project</a></li>
</ul>
<p>This example demonstrates how to use Cask to write a TodoMVC API server that persists it's state in a database rather than in memory. We use the <a href="http://getquill.io/">Quill</a> database access library to write a <code>@transactional</code> decorator that automatically opens one transaction per call to an endpoint, ensuring that database queries are properly committed on success or rolled-back on error. Note that because the default database connector propagates its transaction context in a thread-local, <code>@transactional</code> does not need to pass the <code>ctx</code> object into each endpoint as an additional parameter list, and so we simply leave it out.</p>
<p>While this example is specific to Quill, you can easily modify the <code>@transactional</code> decorator to make it work with whatever database access library you happen to be using. For libraries which need an implicit transaction, it can be passed into each endpoint function as an additional parameter list as described in <a href="#extending-endpoints-with-decorators">Extending Endpoints with Decorators</a>. work with whatever database access library you happen to be using. For libraries which need an implicit transaction, it can be passed into each endpoint function as an additional parameter list as described in <a href="#extending-endpoints-with-decorators">Extending Endpoints with Decorators</a>.</p><h2 id="todomvc-full-stack-web" class="Styles-hoverBox">TodoMVC Full Stack Web<a href="#todomvc-full-stack-web" class=" Styles-hoverLink"><i class="fa fa-link" aria-hidden="true"></i></a></h2>
<p>The following code snippet is the complete code for a full-stack TodoMVC implementation: including HTML generation for the web UI via <a href="https://github.com/lihaoyi/scalatags">Scalatags</a>, Javascript for the interactivity, static file serving, and database integration via <a href="https://github.com/getquill/quill">Quill</a>. While slightly long, this example should give you a tour of all the things you need to know to use Cask.</p>
<p>Note that this is a "boring" server-side-rendered webapp with Ajax interactions, without any complex front-end frameworks or libraries: it's purpose is to demonstrate a simple working web application of using Cask end-to-end, which you can build upon to create your own Cask web application architected however you would like.</p>
<pre style="background-color: #f8f8f8"><code style="white-space:pre; background-color: #f8f8f8" class="scala">package app
import com.typesafe.config.ConfigFactory
import io.getquill.{SnakeCase, SqliteJdbcContext}
import scalatags.Text.all._
import scalatags.Text.tags2
object TodoServer extends cask.MainRoutes{
val tmpDb = java.nio.file.Files.createTempDirectory("todo-cask-sqlite")
object ctx extends SqliteJdbcContext(
SnakeCase,
ConfigFactory.parseString(
s"""{"driverClassName":"org.sqlite.JDBC","jdbcUrl":"jdbc:sqlite:$tmpDb/file.db"}"""
)
)
class transactional extends cask.RawDecorator{
class TransactionFailed(val value: cask.router.Result.Error) extends Exception
def wrapFunction(pctx: cask.Request, delegate: Delegate) = {
try ctx.transaction(
delegate(Map()) match{
case cask.router.Result.Success(t) => cask.router.Result.Success(t)
case e: cask.router.Result.Error => throw new TransactionFailed(e)
}
)
catch{case e: TransactionFailed => e.value}
}
}
case class Todo(id: Int, checked: Boolean, text: String)
ctx.executeAction(
"""CREATE TABLE todo (
id INTEGER PRIMARY KEY AUTOINCREMENT,
checked BOOLEAN,
text TEXT
);
""".stripMargin
)
ctx.executeAction(
"""INSERT INTO todo (checked, text) VALUES
(1, 'Get started with Cask'),
(0, 'Profit!');
""".stripMargin
)
import ctx._
@transactional
@cask.post("/list/:state")
def list(state: String) = renderBody(state).render
@transactional
@cask.post("/add/:state")
def add(state: String, request: cask.Request) = {
val body = new String(request.readAllBytes())
run(
query[Todo]
.insert(_.checked -> lift(false), _.text -> lift(body))
.returningGenerated(_.id)
)
renderBody(state).render
}
@transactional
@cask.post("/delete/:state/:index")
def delete(state: String, index: Int) = {
run(query[Todo].filter(_.id == lift(index)).delete)
renderBody(state).render
}
@transactional
@cask.post("/toggle/:state/:index")
def toggle(state: String, index: Int) = {
run(query[Todo].filter(_.id == lift(index)).update(p => p.checked -> !p.checked))
renderBody(state).render
}
@transactional
@cask.post("/clear-completed/:state")
def clearCompleted(state: String) = {
run(query[Todo].filter(_.checked).delete)
renderBody(state).render
}
@transactional
@cask.post("/toggle-all/:state")
def toggleAll(state: String) = {
val next = run(query[Todo].filter(_.checked).size) != 0
run(query[Todo].update(_.checked -> !lift(next)))
renderBody(state).render
}
def renderBody(state: String) = {
val filteredTodos = state match{
case "all" => run(query[Todo]).sortBy(-_.id)
case "active" => run(query[Todo].filter(!_.checked)).sortBy(-_.id)
case "completed" => run(query[Todo].filter(_.checked)).sortBy(-_.id)
}
frag(
header(cls := "header",
h1("todos"),
input(cls := "new-todo", placeholder := "What needs to be done?", autofocus := "")
),
tags2.section(cls := "main",
input(
id := "toggle-all",
cls := "toggle-all",
`type` := "checkbox",
if (run(query[Todo].filter(_.checked).size != 0)) checked else ()
),
label(`for` := "toggle-all","Mark all as complete"),
ul(cls := "todo-list",
for(todo <- filteredTodos) yield li(
if (todo.checked) cls := "completed" else (),
div(cls := "view",
input(
cls := "toggle",
`type` := "checkbox",
if (todo.checked) checked else (),
data("todo-index") := todo.id
),
label(todo.text),
button(cls := "destroy", data("todo-index") := todo.id)
),
input(cls := "edit", value := todo.text)
)
)
),
footer(cls := "footer",
span(cls := "todo-count",
strong(run(query[Todo].filter(!_.checked).size).toInt),
" items left"
),
ul(cls := "filters",
li(cls := "todo-all",
a(if (state == "all") cls := "selected" else (), "All")
),
li(cls := "todo-active",
a(if (state == "active") cls := "selected" else (), "Active")
),
li(cls := "todo-completed",
a(if (state == "completed") cls := "selected" else (), "Completed")
)
),
button(cls := "clear-completed","Clear completed")
)
)
}
@transactional
@cask.get("/")
def index() = {
cask.Response(
"<!doctype html>" + html(lang := "en",
head(
meta(charset := "utf-8"),
meta(name := "viewport", content := "width=device-width, initial-scale=1"),
tags2.title("Template • TodoMVC"),
link(rel := "stylesheet", href := "/static/index.css")
),
body(
tags2.section(cls := "todoapp", renderBody("all")),
footer(cls := "info",
p("Double-click to edit a todo"),
p("Created by ",
a(href := "http://todomvc.com","Li Haoyi")
),
p("Part of ",
a(href := "http://todomvc.com","TodoMVC")
)
),
script(src := "/static/app.js")
)
)
)
}
@cask.staticResources("/static")
def static() = "todo"
initialize()
}
</code></pre>
<ul>
<li><a href="https://github.com/lihaoyi/cask/releases/download/0.3.6/todo-0.3.6.zip">example project</a></li>
</ul><hr /><p><b>About the Author:</b><i> Haoyi is a software engineer, an early contributor to <a href="http://www.scala-js.org/">Scala.js</a>, and the author of many open-source Scala tools such as Cask, the <a href="lihaoyi.com/Ammonite">Ammonite REPL</a> and <a href="https://github.com/lihaoyi/fastparse">FastParse</a>. </i></p><p><i>If you've enjoy using Cask, or enjoyed using Haoyi's other open source libraries, please chip in (or get your Company to chip in!) via <a href="https://www.patreon.com/lihaoyi">Patreon</a> so he can continue his open-source work</i></p><hr /><div style="display: flex;flex-direction: row;justify-content: space-between;"><div></div><a href="page/main-customization.html">Main Customization <i class="fa fa-arrow-right" aria-hidden="true"></i></a></div></div></body></html>
|
