1% Generated by roxygen2: do not edit by hand
2% Please edit documentation in R/httpuv.R
3\name{startServer}
4\alias{startServer}
5\alias{startPipeServer}
6\title{Create an HTTP/WebSocket server}
7\usage{
8startServer(host, port, app, quiet = FALSE)
9
10startPipeServer(name, mask, app, quiet = FALSE)
11}
12\arguments{
13\item{host}{A string that is a valid IPv4 address that is owned by this
14server, or \code{"0.0.0.0"} to listen on all IP addresses.}
15
16\item{port}{A number or integer that indicates the server port that should be
17listened on. Note that on most Unix-like systems including Linux and Mac OS
18X, port numbers smaller than 1025 require root privileges.}
19
20\item{app}{A collection of functions that define your application. See
21Details.}
22
23\item{quiet}{If \code{TRUE}, suppress error messages from starting app.}
24
25\item{name}{A string that indicates the path for the domain socket (on
26Unix-like systems) or the name of the named pipe (on Windows).}
27
28\item{mask}{If non-\code{NULL} and non-negative, this numeric value is used
29to temporarily modify the process's umask while the domain socket is being
30created. To ensure that only root can access the domain socket, use
31\code{strtoi("777", 8)}; or to allow owner and group read/write access, use
32\code{strtoi("117", 8)}. If the value is \code{NULL} then the process's
33umask is left unchanged. (This parameter has no effect on Windows.)}
34}
35\value{
36A handle for this server that can be passed to
37\code{\link{stopServer}} to shut the server down.
38
39A \code{\link{WebServer}} or \code{\link{PipeServer}} object.
40}
41\description{
42Creates an HTTP/WebSocket server on the specified host and port.
43}
44\details{
45\code{startServer} binds the specified port and listens for
46connections on an thread running in the background. This background thread
47handles the I/O, and when it receives a HTTP request, it will schedule a
48call to the user-defined R functions in \code{app} to handle the request.
49This scheduling is done with \code{\link[later]{later}()}. When the R call
50stack is empty -- in other words, when an interactive R session is sitting
51idle at the command prompt -- R will automatically run the scheduled calls.
52However, if the call stack is not empty -- if R is evaluating other R code
53-- then the callbacks will not execute until either the call stack is
54empty, or the \code{\link[later]{run_now}()} function is called. This
55function tells R to execute any callbacks that have been scheduled by
56\code{\link[later]{later}()}. The \code{\link{service}()} function is
57essentially a wrapper for \code{\link[later]{run_now}()}.
58
59In older versions of httpuv (1.3.5 and below), it did not use a background
60thread for I/O, and when this function was called, it did not accept
61connections immediately. It was necessary to call \code{\link{service}}
62repeatedly in order to actually accept and handle connections.
63
64If the port cannot be bound (most likely due to permissions or because it
65is already bound), an error is raised.
66
67The application can also specify paths on the filesystem which will be
68served from the background thread, without invoking \code{$call()} or
69\code{$onHeaders()}. Files served this way will be only use a C++ code,
70which is faster than going through R, and will not be blocked when R code
71is executing. This can greatly improve performance when serving static
72assets.
73
74The \code{app} parameter is where your application logic will be provided
75to the server. This can be a list, environment, or reference class that
76contains the following methods and fields:
77
78\describe{
79\item{\code{call(req)}}{Process the given HTTP request, and return an
80HTTP response (see Response Values). This method should be implemented in
81accordance with the
82\href{https://github.com/jeffreyhorner/Rook/blob/a5e45f751/README.md}{Rook}
83specification. Note that httpuv augments \code{req} with an additional
84item, \code{req$HEADERS}, which is a named character vector of request
85headers.}
86\item{\code{onHeaders(req)}}{Optional. Similar to \code{call}, but occurs
87when headers are received. Return \code{NULL} to continue normal
88processing of the request, or a Rook response to send that response,
89stop processing the request, and ask the client to close the connection.
90(This can be used to implement upload size limits, for example.)}
91\item{\code{onWSOpen(ws)}}{Called back when a WebSocket connection is established.
92The given object can be used to be notified when a message is received from
93the client, to send messages to the client, etc. See \code{\link{WebSocket}}.}
94\item{\code{staticPaths}}{
95A named list of paths that will be served without invoking
96\code{call()} or \code{onHeaders}. The name of each one is the URL
97path, and the value is either a string referring to a local path, or an
98object created by the \code{\link{staticPath}} function.
99}
100\item{\code{staticPathOptions}}{
101A set of default options to use when serving static paths. If
102not set or \code{NULL}, then it will use the result from calling
103\code{\link{staticPathOptions}()} with no arguments.
104}
105}
106
107The \code{startPipeServer} variant can be used instead of
108\code{startServer} to listen on a Unix domain socket or named pipe rather
109than a TCP socket (this is not common).
110}
111\section{Response Values}{
112
113
114The \code{call} function is expected to return a list containing the
115following, which are converted to an HTTP response and sent to the client:
116
117\describe{
118\item{\code{status}}{A numeric HTTP status code, e.g. \code{200} or
119\code{404L}.}
120
121\item{\code{headers}}{A named list of HTTP headers and their values, as
122strings. This can also be missing, an empty list, or \code{NULL}, in which
123case no headers (other than the \code{Date} and \code{Content-Length}
124headers, as required) will be added.}
125
126\item{\code{body}}{A string (or \code{raw} vector) to be sent as the body
127of the HTTP response. This can also be omitted or set to \code{NULL} to
128avoid sending any body, which is useful for HTTP \code{1xx}, \code{204},
129and \code{304} responses, as well as responses to \code{HEAD} requests.}
130}
131}
132
133\examples{
134\dontrun{
135# A very basic application
136s <- startServer("0.0.0.0", 5000,
137  list(
138    call = function(req) {
139      list(
140        status = 200L,
141        headers = list(
142          'Content-Type' = 'text/html'
143        ),
144        body = "Hello world!"
145      )
146    }
147  )
148)
149
150s$stop()
151
152
153# An application that serves static assets at the URL paths /assets and /lib
154s <- startServer("0.0.0.0", 5000,
155  list(
156    call = function(req) {
157      list(
158        status = 200L,
159        headers = list(
160          'Content-Type' = 'text/html'
161        ),
162        body = "Hello world!"
163      )
164    },
165    staticPaths = list(
166      "/assets" = "content/assets/",
167      "/lib" = staticPath(
168        "content/lib",
169        indexhtml = FALSE
170      ),
171      # This subdirectory of /lib should always be handled by the R code path
172      "/lib/dynamic" = excludeStaticPath()
173    ),
174    staticPathOptions = staticPathOptions(
175      indexhtml = TRUE
176    )
177  )
178)
179
180s$stop()
181}
182}
183\seealso{
184\code{\link{stopServer}}, \code{\link{runServer}},
185\code{\link{listServers}}, \code{\link{stopAllServers}}.
186}
187