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