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
logger	`scamper.logging.ConsoleLogger`
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 Params

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 Params

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 Params

port: port number

Returns

new server

Creates server at given host and port.

Value Params

host: host address
port: port number

Returns

new server

Creates server at given host and port.

Value Params

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 Params

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 Params

params: keep-alive parameters

Returns

this application

Enables persistent connections using specified timeout and max.

Value Params

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

Returns

this application

Sets logger to given file.

Value Params

file: file to which server logs are written

Returns

this application

Note

If file exists, it is opened in append mode.

Sets logger.

Value Params

logger: logger to which server logs are written

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 Params

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 Params

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 Params

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 Params

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 Params

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 Params

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 Params

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 Params

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 Params

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 Params

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 Params

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 Params

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 Params

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 Params

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