3 Launching Servers

This module provides functions for launching dispatching servers.

(serve
		#:dispatch dispatch
	[	#:tcp@ tcp@
		#:port port
		#:listen-ip listen-ip
		#:max-waiting max-waiting
		#:initial-connection-timeout initial-connection-timeout])

→ (-> void)

dispatch : dispatcher/c

tcp@ : (unit/c (import) (export tcp^)) = raw:tcp@

port : integer? = 80

listen-ip : (or/c string? false/c) = #f

max-waiting : integer? = 40

initial-connection-timeout : integer? = 60

Constructs an appropriate dispatch-server-config^, invokes the dispatch-server@, and calls its serve function.

The #:tcp@ keyword is provided for building an SSL server. See How do I set up the server to use HTTPS?.

Here’s an example of a simple web server that serves files from a given path:

(define (start-file-server base)

(serve

#:dispatch

(files:make

#:url->path (make-url->path base)

#:path->mime-type

(lambda (path)

#"application/octet-stream"))

#:port 8080))

(serve/ports
		#:dispatch dispatch
	[	#:tcp@ tcp@
		#:ports ports
		#:listen-ip listen-ip
		#:max-waiting max-waiting
		#:initial-connection-timeout initial-connection-timeout])

→ (-> void)

dispatch : dispatcher/c

tcp@ : (unit/c (import) (export tcp^)) = raw:tcp@

ports : (listof integer?) = (list 80)

listen-ip : (or/c string? false/c) = #f

max-waiting : integer? = 40

initial-connection-timeout : integer? = 60

Calls serve multiple times, once for each port, and returns a function that shuts down all of the server instances.

(serve/ips+ports
		#:dispatch dispatch
	[	#:tcp@ tcp@
		#:ips+ports ips+ports
		#:max-waiting max-waiting
		#:initial-connection-timeout initial-connection-timeout])

→ (-> void)

dispatch : dispatcher/c

tcp@ : (unit/c (import) (export tcp^)) = raw:tcp@

	ips+ports		:		(listof (cons/c (or/c string? false/c) (listof integer?)))
			=		(list (cons #f (list 80)))

max-waiting : integer? = 40

initial-connection-timeout : integer? = 60

Calls serve/ports multiple times, once for each ip, and returns a function that shuts down all of the server instances.

(serve/web-config@ config@ [#:tcp@ tcp@]) → (-> void)

config@ : (unit/c (import) (export web-config^))

tcp@ : (unit/c (import) (export tcp^)) = raw:tcp@

Starts the Web Server with the settings defined by the given web-config^ unit.

It is very useful to combine this with configuration-table->web-config@ and configuration-table-sexpr->web-config@:

(serve/web-config@

(configuration-table->web-config@

default-configuration-table-path))

(do-not-return) → void

This function does not return. If you are writing a script to load the Web Server you are likely to want to call this functions at the end of your script.

(require web-server/servlet-dispatch)

These functions optimize the construction of dispatchers and launching of servers for single servlets and interactive development.

(dispatch/servlet
		start
	[	#:regexp regexp
		#:stateless? stateless?
		#:stuffer stuffer
		#:manager manager
		#:namespace namespace
		#:current-directory servlet-current-directory])

→ dispatcher/c

start : (request? . -> . response/c)

regexp : regexp? = #rx""

stateless? : boolean? = #f

stuffer : (stuffer/c serializable? bytes?) = default-stuffer

	manager		:		manager?
			=		(make-threshold-LRU-manager #f (* 1024 1024 64))

namespace : (listof module-path?) = empty

servlet-current-directory : path-string? = (current-directory)

serve/servlet starts a server and uses a particular dispatching sequence. For some applications, this nails down too much, but users are conflicted, because the interface is so convenient. For those users, dispatch/servlet does the hardest part of serve/servlet and constructs a dispatcher just for the start servlet.

The dispatcher responds to requests that match regexp. The current directory of servlet execution is servlet-current-directory.

If stateless? is true, then the servlet is run as a stateless

#lang web-server

module and stuffer is used as the stuffer.

The servlet is loaded with manager as its continuation manager. (The default manager limits the amount of memory to 64 MB and deals with memory pressure as discussed in the make-threshold-LRU-manager documentation.)

The modules specified by servlet-namespace are shared with other servlets.

(serve/launch/wait		make-dispatcher
	[	#:launch-path launch-path
		#:banner? banner?
		#:listen-ip listen-ip
		#:port port
		#:ssl-cert ssl-cert
		#:ssl-key ssl-key])	→	void

make-dispatcher : (semaphore? . -> . dispatcher/c)

launch-path : (or/c false/c string?) = #f

banner? : boolean? = #f

listen-ip : (or/c false/c string?) = "127.0.0.1"

port : number? = 8000

ssl-cert : (or/c false/c path-string?) = #f

ssl-key : (or/c false/c path-string?) = #f

The other interesting part of serve/servlet is its ability to start up a server and immediately launch a browser at it. This is provided by serve/launch/wait.

It starts a server using the result of make-dispatcher as the dispatcher. make-dispatcher is supplied a semaphore that if posted, will cause the server to quit.

If launch-path is not false, then a browser is launched with that path appended to the URL to the server itself.

If banner? is true, then a banner is printed informing the user of the server’s URL.

The server listens on listen-ip and port port. If listen-ip is #f, then the server accepts connections to all of the listening machine’s addresses. Otherwise, the server accepts connections only at the interface(s) associated with the given string. For example, providing "127.0.0.1" (the default) as listen-ip creates a server that accepts only connections to "127.0.0.1" (the loopback interface) from the local machine.

If ssl-key and ssl-cert are not false, then the server runs in HTTPS mode with ssl-cert and ssl-key as paths to the certificate and private key.

1	Dispatching Server
2	Dispatchers
3	Launching Servers
4	Web Servers
5	Internal APIs
6	Troubleshooting and Tips
	Index

3 Launching Servers

3.1 Simple Single Servlet Servers