1#lang scribble/doc
2@(require "web-server.rkt")
3
4@title[]{Simple Single Servlet Servers}
5@(require (for-label web-server/servlet-env
6                     web-server/servlet-dispatch
7                     web-server/http
8                     web-server/managers/manager
9                     web-server/managers/lru
10                     web-server/private/util
11                     web-server/dispatchers/dispatch
12                     web-server/configuration/configuration-table
13                     web-server/configuration/responders
14                     web-server/dispatchers/dispatch-log
15                     web-server/web-server
16                     web-server/safety-limits
17                     net/url
18                     racket/serialize
19                     web-server/stuffers
20                     racket/list))
21
22@defmodule[web-server/servlet-dispatch]{
23
24These functions optimize the construction of dispatchers and launching of servers for single servlets and interactive development.
25
26@defproc[(dispatch/servlet
27          [start (request? . -> . response?)]
28          [#:regexp regexp regexp? #rx""]
29          [#:stateless? stateless? boolean? #f]
30          [#:stuffer stuffer (stuffer/c serializable? bytes?) default-stuffer]
31          [#:manager manager manager? (make-threshold-LRU-manager #f (* 1024 1024 64))]
32          [#:current-directory servlet-current-directory path-string? (current-directory)]
33          [#:responders-servlet-loading
34           responders-servlet-loading
35           (url? any/c . -> . can-be-response?)
36           servlet-loading-responder]
37          [#:responders-servlet
38           responders-servlet
39           (url? any/c . -> . can-be-response?)
40           servlet-error-responder])
41         dispatcher/c]{
42 @racket[serve/servlet] starts a server and uses a particular dispatching sequence. For some applications, this
43 nails down too much, but users are conflicted, because the interface is so convenient. For those users, @racket[dispatch/servlet]
44 does the hardest part of @racket[serve/servlet] and constructs a dispatcher just for the @racket[start] servlet.
45
46 The dispatcher responds to requests that match @racket[regexp]. The current directory
47 of servlet execution is @racket[servlet-current-directory].
48
49 If @racket[stateless?] is true, then the servlet is run as a stateless @racketmod[web-server] module and @racket[stuffer] is used
50 as the @tech[#:doc '(lib "web-server/scribblings/web-server.scrbl")]{stuffer}.
51
52 The servlet is loaded with @racket[manager] as its continuation manager. (The default manager limits the amount of memory to 64 MB and
53 deals with memory pressure as discussed in the @racket[make-threshold-LRU-manager] documentation.)
54
55 The servlet is run in the @racket[(current-namespace)].
56
57 If a servlet fails to load, @racket[responders-servlet-loading] is used. If a servlet errors during its operation, @racket[responders-servlet] is used.
58}
59
60@defproc[(serve/launch/wait
61          [make-dispatcher (semaphore? . -> . dispatcher/c)]
62          [#:connection-close? connection-close? boolean? #f]
63          [#:launch-path launch-path (or/c #f string?) #f]
64          [#:banner? banner? boolean? #f]
65          [#:listen-ip listen-ip (or/c #f string?) "127.0.0.1"]
66          [#:port port number? 8000]
67          [#:ssl-cert ssl-cert (or/c #f path-string?) #f]
68          [#:ssl-key ssl-key (or/c #f path-string?) #f]
69          [#:max-waiting max-waiting exact-nonnegative-integer? 511]
70          [#:safety-limits safety-limits safety-limits?
71           (make-safety-limits #:max-waiting max-waiting)])
72         any]{
73 The other interesting part of @racket[serve/servlet] is its ability to start up a server and immediately
74 launch a browser at it. This is provided by @racket[serve/launch/wait].
75
76 It starts a server using the result of @racket[make-dispatcher] as the dispatcher.
77 The @racket[make-dispatcher] argument is called with
78 a semaphore that, if posted, will cause the server to quit.
79
80 If @racket[launch-path] is not false, then a browser is launched with that path appended to the URL to the server itself.
81
82 If @racket[banner?] is true, then a banner is printed informing the user of the server's URL.
83
84 The server listens on @racket[listen-ip] and port @racket[port]. If @racket[listen-ip] is @racket[#f], then the server accepts
85 connections to all of the listening machine's addresses. Otherwise, the server accepts connections only at the interface(s) associated with the given string.
86 For example, providing @racket["127.0.0.1"] (the default) as @racket[listen-ip] creates a server that accepts only connections to @racket["127.0.0.1"] (the loopback interface) from the local machine.
87
88 If @racket[ssl-key] and @racket[ssl-cert] are not false, then the server runs in HTTPS mode with @racket[ssl-cert]
89 and @racket[ssl-key] as paths to the certificate and private key.
90
91 If @racket[connection-close?] is @racket[#t], then every connection is closed after one
92 request. Otherwise, the client decides based on what HTTP version it uses.
93
94  The @racket[safety-limits] argument supplies a @tech{safety limits}
95  value specifying the policies to be used while reading and handling requests.
96
97  The @racket[max-waiting] argument is supported for backwards compatability.
98  If a @racket[safety-limits] argument is given, the @racket[max-waiting]
99  argument is ignored; otherwise, it is passed to @racket[make-safety-limits]
100  to construct the @tech{safety limits} value.
101  If neither @racket[max-waiting] nor @racket[safety-limits] are given,
102  the default @tech{safety limits} value is equivalent to @racket[(make-safety-limits)].
103
104  @history[#:changed "1.6"
105           @elem{Added the @racket[safety-limits] argument:
106              see @elemref["safety-limits-porting"]{compatability note}.}]
107}
108
109}
110