EVOLUTION-MANAGER
Edit File: startServer.html
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Strict//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd"><html xmlns="http://www.w3.org/1999/xhtml"><head><title>R: Create an HTTP/WebSocket server</title> <meta http-equiv="Content-Type" content="text/html; charset=utf-8" /> <link rel="stylesheet" type="text/css" href="R.css" /> </head><body> <table width="100%" summary="page for startServer {httpuv}"><tr><td>startServer {httpuv}</td><td style="text-align: right;">R Documentation</td></tr></table> <h2>Create an HTTP/WebSocket server</h2> <h3>Description</h3> <p>Creates an HTTP/WebSocket server on the specified host and port. </p> <h3>Usage</h3> <pre> startServer(host, port, app, quiet = FALSE) startPipeServer(name, mask, app, quiet = FALSE) </pre> <h3>Arguments</h3> <table summary="R argblock"> <tr valign="top"><td><code>host</code></td> <td> <p>A string that is a valid IPv4 address that is owned by this server, or <code>"0.0.0.0"</code> to listen on all IP addresses.</p> </td></tr> <tr valign="top"><td><code>port</code></td> <td> <p>A number or integer that indicates the server port that should be listened on. Note that on most Unix-like systems including Linux and Mac OS X, port numbers smaller than 1025 require root privileges.</p> </td></tr> <tr valign="top"><td><code>app</code></td> <td> <p>A collection of functions that define your application. See Details.</p> </td></tr> <tr valign="top"><td><code>quiet</code></td> <td> <p>If <code>TRUE</code>, suppress error messages from starting app.</p> </td></tr> <tr valign="top"><td><code>name</code></td> <td> <p>A string that indicates the path for the domain socket (on Unix-like systems) or the name of the named pipe (on Windows).</p> </td></tr> <tr valign="top"><td><code>mask</code></td> <td> <p>If non-<code>NULL</code> and non-negative, this numeric value is used to temporarily modify the process's umask while the domain socket is being created. To ensure that only root can access the domain socket, use <code>strtoi("777", 8)</code>; or to allow owner and group read/write access, use <code>strtoi("117", 8)</code>. If the value is <code>NULL</code> then the process's umask is left unchanged. (This parameter has no effect on Windows.)</p> </td></tr> </table> <h3>Details</h3> <p><code>startServer</code> binds the specified port and listens for connections on an thread running in the background. This background thread handles the I/O, and when it receives a HTTP request, it will schedule a call to the user-defined R functions in <code>app</code> to handle the request. This scheduling is done with <code><a href="../../later/html/later.html">later</a>()</code>. When the R call stack is empty – in other words, when an interactive R session is sitting idle at the command prompt – R will automatically run the scheduled calls. However, if the call stack is not empty – if R is evaluating other R code – then the callbacks will not execute until either the call stack is empty, or the <code><a href="../../later/html/run_now.html">run_now</a>()</code> function is called. This function tells R to execute any callbacks that have been scheduled by <code><a href="../../later/html/later.html">later</a>()</code>. The <code><a href="service.html">service</a>()</code> function is essentially a wrapper for <code><a href="../../later/html/run_now.html">run_now</a>()</code>. </p> <p>In older versions of httpuv (1.3.5 and below), it did not use a background thread for I/O, and when this function was called, it did not accept connections immediately. It was necessary to call <code><a href="service.html">service</a></code> repeatedly in order to actually accept and handle connections. </p> <p>If the port cannot be bound (most likely due to permissions or because it is already bound), an error is raised. </p> <p>The application can also specify paths on the filesystem which will be served from the background thread, without invoking <code>$call()</code> or <code>$onHeaders()</code>. Files served this way will be only use a C++ code, which is faster than going through R, and will not be blocked when R code is executing. This can greatly improve performance when serving static assets. </p> <p>The <code>app</code> parameter is where your application logic will be provided to the server. This can be a list, environment, or reference class that contains the following methods and fields: </p> <dl> <dt><code>call(req)</code></dt><dd><p>Process the given HTTP request, and return an HTTP response. This method should be implemented in accordance with the <a href="https://github.com/jeffreyhorner/Rook/blob/a5e45f751/README.md">Rook</a> specification.</p> </dd></dl> <p> Note that httpuv augments <code>req</code> with an additional item, <code>req$HEADERS</code>, which is a named character vector of request headers. </p> <dl> <dt><code>onHeaders(req)</code></dt><dd><p>Optional. Similar to <code>call</code>, but occurs when headers are received. Return <code>NULL</code> to continue normal processing of the request, or a Rook response to send that response, stop processing the request, and ask the client to close the connection. (This can be used to implement upload size limits, for example.)</p> </dd> <dt><code>onWSOpen(ws)</code></dt><dd><p>Called back when a WebSocket connection is established. The given object can be used to be notified when a message is received from the client, to send messages to the client, etc. See <code><a href="WebSocket.html">WebSocket</a></code>.</p> </dd> <dt><code>staticPaths</code></dt><dd> <p>A named list of paths that will be served without invoking <code>call()</code> or <code>onHeaders</code>. The name of each one is the URL path, and the value is either a string referring to a local path, or an object created by the <code><a href="staticPath.html">staticPath</a></code> function. </p> </dd> <dt><code>staticPathOptions</code></dt><dd> <p>A set of default options to use when serving static paths. If not set or <code>NULL</code>, then it will use the result from calling <code><a href="staticPathOptions.html">staticPathOptions</a>()</code> with no arguments. </p> </dd> </dl> <p>The <code>startPipeServer</code> variant can be used instead of <code>startServer</code> to listen on a Unix domain socket or named pipe rather than a TCP socket (this is not common). </p> <h3>Value</h3> <p>A handle for this server that can be passed to <code><a href="stopServer.html">stopServer</a></code> to shut the server down. </p> <p>A <code><a href="WebServer.html">WebServer</a></code> or <code><a href="PipeServer.html">PipeServer</a></code> object. </p> <h3>See Also</h3> <p><code><a href="stopServer.html">stopServer</a></code>, <code><a href="runServer.html">runServer</a></code>, <code><a href="listServers.html">listServers</a></code>, <code><a href="stopAllServers.html">stopAllServers</a></code>. </p> <h3>Examples</h3> <pre> ## Not run: # A very basic application s <- startServer("0.0.0.0", 5000, list( call = function(req) { list( status = 200L, headers = list( 'Content-Type' = 'text/html' ), body = "Hello world!" ) } ) ) s$stop() # An application that serves static assets at the URL paths /assets and /lib s <- startServer("0.0.0.0", 5000, list( call = function(req) { list( status = 200L, headers = list( 'Content-Type' = 'text/html' ), body = "Hello world!" ) }, staticPaths = list( "/assets" = "content/assets/", "/lib" = staticPath( "content/lib", indexhtml = FALSE ), # This subdirectory of /lib should always be handled by the R code path "/lib/dynamic" = excludeStaticPath() ), staticPathOptions = staticPathOptions( indexhtml = TRUE ) ) ) s$stop() ## End(Not run) </pre> <hr /><div style="text-align: center;">[Package <em>httpuv</em> version 1.5.4 <a href="00Index.html">Index</a>]</div> </body></html>