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