Scamper/scamper.http.server/ServerApplication

ServerApplication

Defines server application for creating HttpServer.

Default Configuration

The initial application is constructed with the following default configuration:

Key	Value
backlogSize	`50`
poolSize	`Runtime.getRuntime().availableProcessors()`
queueSize	`Runtime.getRuntime().availableProcessors() * 4`
bufferSize	`8192`
readTimeout	`5000`
headerLimit	`100`
keepAlive	(Not configured)
secure	(Not configured)
trigger	(Not configured)
incoming	(Not configured)
outgoing	(Not configured)
recover	(Sends `500 Internal Server Error`)

Building HTTP Server

ServerApplication is a mutable structure. With each applied change, the application is modified and returned. After the desired configuration is applied, a server is created using a factory method.

import java.io.File

import scala.language.implicitConversions

import scamper.http.{ BodyParser, stringToEntity }
import scamper.http.ResponseStatus.Registry.{ NotFound, NoContent, Ok }
import scamper.http.server.{ *, given }

// Get server application
val app = ServerApplication()

// Add request handler to log all requests
app.incoming { req =>
 println(req.startLine)
 req
}

// Add request handler for GET requests at specified path
app.get("/about") { req =>
 Ok("This server is powered by Scamper.")
}

// Add request handler for PUT requests at specified path
app.put("/data/:id") { req =>
 def update(id: Int, data: String): Boolean = ???

 given BodyParser[String] = BodyParser.string()

 // Get path parameter
 val id = req.params.getInt("id")

 update(id, req.as[String]) match
   case true  => NoContent()
   case false => NotFound()
}

// Serve files from file directory
app.files("/main", File("/path/to/public"))

// Gzip response body if not empty
app.outgoing { res =>
 res.body.isKnownEmpty match
   case true  => res
   case false => res.setGzipContentEncoding()
}

// Create server
val server = app.create(8080)

try
 printf("Host: %s%n", server.host)
 printf("Port: %d%n", server.port)

 // Run server for 60 seconds
 Thread.sleep(60 * 1000)
finally
 // Close server when done
 server.close()

trait Router

class Object

trait Matchable

class Any

Value members

Concrete methods

Sets backlog size.

The backlogSize specifies the maximum number of incoming connections that can wait before being accepted. Incoming connections that exceed this limit are refused.

Value parameters:

size: backlog size

Returns:

this application

Sets buffer size.

The bufferSize specifies in bytes the size of buffer used when reading from and writing to socket.

The bufferSize also determines the maximum length of any header line. Incoming requests containing a header that exceeds this limit are sent 431 (Request Header Fields Too Large).

Value parameters:

size: buffer size in bytes

Returns:

this application

Note:

bufferSize is also used as the optimal chunk size when writing a response with chunked transfer encoding.

Creates server at given port.

Value parameters:

port: port number

Returns:

new server

Creates server at given host and port.

Value parameters:

host: host address
port: port number

Returns:

new server

Creates server at given host and port.

Value parameters:

host: host address
port: port number

Returns:

new server

Sets header limit.

The headerLimit specifies the maximum number of headers allowed. Incoming requests containing headers that exceed this limit are sent 431 (Request Header Fields Too Large).

Value parameters:

limit: header limit

Returns:

this application

Adds supplied request handler.

The handler is appended to existing request handler chain.

Adds supplied handler for requests with given router path and any of specified request methods.

The handler is appended to existing request handler chain.

Enables persistent connections using specified parameters.

Value parameters:

params: keep-alive parameters

Returns:

this application

Enables persistent connections using specified timeout and max.

Value parameters:

max: maximum number of requests per connection
timeout: idle timeout in seconds

Returns:

this application

Gets mount path.

Returns:: "/"

Adds supplied response filter.

The filter is appended to existing response filter chain.

Sets pool size.

The poolSize specifies the maximum number of requests processed concurrently.

Value parameters:

size: pool size

Returns:

this application

Sets queue size.

The queueSize specifies the maximum number of requests that can be queued for processing. Incoming requests that exceed this limit are sent 503 (Service Unavailable).

Value parameters:

size: queue size

Returns:

this application

Sets read timeout.

The readTimeout specifies how long a read from a socket blocks before it times out, whereafter 408 (Request Timeout) is sent to client.

Value parameters:

timeout: read timeout in milliseconds

Returns:

this application

Adds error handler.

The handler is appended to existing error handler chain.

Resets router.

Sets key store to be used for SSL/TLS.

Value parameters:

keyStore: server key store
password: key store password
storeType: key store type (i.e., JKS, JCEKS, etc.)

Returns:

this application

Sets key store to be used for SSL/TLS.

Value parameters:

keyStore: server key store
password: key store password
storeType: key store type (i.e., JKS, JCEKS, etc.)

Returns:

this application

Note:

The password can be discarded after invoking this method.

Sets key and certificate to be used for SSL/TLS.

Value parameters:

certificate: public key certificate
key: private key

Returns:

this application

Adds server lifecycle hook.

Inherited methods

Adds supplied handler for DELETE requests to given router path.

The handler is appended to existing request handler chain.

Value parameters:

handler: request handler
path: router path

Returns:

this router

Note:

If request handler implements LifecycleHook, it is also added as a lifecycle hook.

Inherited from:

Router

Mounts file server at given path.

At request time, the mount path is stripped from the router path, and the remaining path is used to locate a file in the source directory.

File Mapping Examples

Mount Path	Source Directory	Router Path	Maps to
/images	/tmp	/images/logo.png	/tmp/logo.png
/images	/tmp	/images/icons/warning.png	/tmp/icons/warning.png

Value parameters:

defaults: default file names used when request matches directory
path: router path at which directory is mounted
source: directory from which files are served

Returns:

this router

Note:

If a request matches a directory, and if a file with one of the default file names exists in that directory, the server sends 303 (See Other) with a Location header value set to path of default file.

Inherited from:

Router

Adds supplied handler for GET requests to given router path.

The handler is appended to existing request handler chain.

Value parameters:

handler: request handler
path: router path

Returns:

this router

Note:

If request handler implements LifecycleHook, it is also added as a lifecycle hook.

Inherited from:

Router

Adds supplied handler for POST requests to given router path.

The handler is appended to existing request handler chain.

Value parameters:

handler: request handler
path: router path

Returns:

this router

Note:

If request handler implements LifecycleHook, it is also added as a lifecycle hook.

Inherited from:

Router

Adds supplied handler for PUT requests to given router path.

The handler is appended to existing request handler chain.

Value parameters:

handler: request handler
path: router path

Returns:

this router

Note:

If request handler implements LifecycleHook, it is also added as a lifecycle hook.

Inherited from:

Router

Mounts router application at given path.

Value parameters:

app: router application
path: router path at which application is mounted

Returns:

this router

Note:

If router app implements LifecycleHook, it is also added as a lifecycle hook.

Inherited from:

Router

Expands supplied router path to its absolute path.

Value parameters:

path: router path

Throws:

java.lang.IllegalArgumentException: if router path is not * and does not begin with / or if it escapes mount path

Note:

If * is supplied as router path, its absolute path is also *.

Inherited from:

Router

Mounts WebSocket application at given path.

Value parameters:

app: WebSocket application
path: router path at which application is mounted

Returns:

this router

Note:

If WebSocket app implements LifecycleHook, it is also added as a lifecycle hook.

Inherited from:

Router