Packages

package root

Provided herein is API documentation for Scamper, the HTTP library for Scala.

Definition Classes: root

package scamper

Defines core types.

HTTP Messages

At the core of Scamper is HttpMessage, which is a trait that defines the fundamental characteristics of an HTTP message. HttpRequest and HttpResponse extend the specification to define characteristics specific to their respective message types.

An HttpRequest is created using a factory method defined in its companion object. Or you can start with a RequestMethod and use builder methods to further define the request.

import scamper.Header
import scamper.Implicits.stringToUri
import scamper.RequestMethod.Registry.Get

val request = Get("/motd").setHeaders(
  Header("Host: localhost:8080"),
  Header("Accept: text/plain")
)

printf("Request Method: %s%n", request.method)
printf("Target URI: %s%n", request.target)

request.headers.foreach(println)

val host: Option[String] = request.getHeaderValue("Host")

An HttpResponse is created using a factory method defined in its companion object. Or you can start with a ResponseStatus and use builder methods to further define the response.

import scamper.{ BodyParser, Header }
import scamper.Implicits.stringToEntity
import scamper.ResponseStatus.Registry.Ok

val response = Ok("There is an answer.").setHeaders(
  Header("Content-Type: text/plain"),
  Header("Connection: close")
)

printf("Status Code: %s%n", response.statusCode)
printf("Reason Phrase: %s%n", response.reasonPhrase)

response.headers.foreach(println)

val contentType: Option[String] = response.getHeaderValue("Content-Type")

implicit val parser = BodyParser.text()

printf("Body: %s%n", response.as[String])

Definition Classes: root

package auth

Provides specialized access to authentication headers.

Challenges and Credentials

When working with authentication, a Challenge is presented in the response, and Credentials in the request. Each of these has an assigned scheme, which is associated with either a token or a set of parameters.

import scamper.Implicits.stringToUri
import scamper.RequestMethod.Registry.Get
import scamper.ResponseStatus.Registry.Unauthorized
import scamper.auth.{ Authorization, Challenge, Credentials, WwwAuthenticate }

// Present response challenge (scheme and parameters)
val challenge = Challenge("Bearer", "realm" -> "developer")
val res = Unauthorized().setWwwAuthenticate(challenge)

// Present request credentials (scheme and token)
val credentials = Credentials("Bearer", "QWxsIEFjY2VzcyEhIQo=")
val req = Get("/dev/projects").setAuthorization(credentials)

Basic Authentication

There are subclasses defined for Basic authentication: BasicChallenge and BasicCredentials.

import scamper.Implicits.stringToUri
import scamper.RequestMethod.Registry.Get
import scamper.ResponseStatus.Registry.Unauthorized
import scamper.auth.{ Authorization, BasicChallenge, BasicCredentials, WwwAuthenticate }

// Provide realm and optional parameters
val challenge = BasicChallenge("admin", "title" -> "Admin Console")
val res = Unauthorized().setWwwAuthenticate(challenge)

// Provide user and password
val credentials = BasicCredentials("sa", "l3tm31n")
val req = Get("/admin/users").setAuthorization(credentials)

In addition, there are methods for Basic authentication defined in the header classes.

import scamper.Implicits.stringToUri
import scamper.RequestMethod.Registry.Get
import scamper.ResponseStatus.Registry.Unauthorized
import scamper.auth.{ Authorization, WwwAuthenticate }

// Provide realm and optional parameters
val res = Unauthorized().setBasic("admin", "title" -> "Admin Console")

// Access basic auth in response
printf(s"Realm: %s%n", res.basic.realm)
printf(s"Title: %s%n", res.basic.params("title"))

// Provide user and password
val req = Get("/admin/users").setBasic("sa", "l3tm3m1n")

// Access basic auth in request
printf(s"User: %s%n", req.basic.user)
printf(s"Password: %s%n", req.basic.password)

Bearer Authentication

There are subclasses defined for Bearer authentication: BearerChallenge and BearerCredentials. In addition, there are Bearer-specific methods available in the header classes.

import scamper.Implicits.stringToUri
import scamper.RequestMethod.Registry.Get
import scamper.ResponseStatus.Registry.Unauthorized
import scamper.auth.{ Authorization, WwwAuthenticate }

// Provide challenge parameters
val res = Unauthorized().setBearer(
  "scope" -> "user profile",
  "error" -> "invalid_token",
  "error_description" -> "Expired access token"
)

// Print optional realm parameter
res.bearer.realm.foreach(println)

// Print scope from space-delimited parameter
val scope: Seq[String] = res.bearer.scope
scope.foreach(println)

// Print error parameters
res.bearer.error.foreach(println)
res.bearer.errorDescription.foreach(println)
res.bearer.errorUri.foreach(println)

// Test for error conditions
println(res.bearer.isInvalidToken)
println(res.bearer.isInvalidRequest)
println(res.bearer.isInsufficientScope)

// Create request with Bearer token
val req = Get("/users").setBearer("R290IDUgb24gaXQhCg==")

// Access bearer auth in request
printf("Token: %s%n", req.bearer.token)

Definition Classes: scamper

package client

Provides HTTP client implementation.

Using HTTP Client

The HttpClient object can be used to send a request and handle the response.

import scamper.BodyParser
import scamper.Implicits.stringToUri
import scamper.RequestMethod.Registry.Get
import scamper.client.HttpClient

implicit val parser = BodyParser.text()

def getMessageOfTheDay(): Either[Int, String] = {
  val req = Get("localhost:8080/motd")

  // Send request and handle response
  HttpClient.send(req) { res =>
    res.isSuccessful match {
      case true  => Right(res.as[String])
      case false => Left(res.statusCode)
    }
  }
}

Note the request must be created with an absolute URI to make effective use of the client.

Creating HTTP Client

When using the HttpClient object as the client, it creates an HttpClient instance for one-time usage. If you plan to send multiple requests, you can create and maintain a reference to a client. With it, you also get access to methods corresponding to standard HTTP request methods.

import scamper.BodyParser
import scamper.Implicits.stringToUri
import scamper.client.HttpClient

implicit val parser = BodyParser.text()

// Create HttpClient instance
val client = HttpClient()

def getMessageOfTheDay(): Either[Int, String] = {
  // Use client instance
  client.get("http://localhost:8080/motd") { res =>
    res.isSuccessful match {
      case true  => Right(res.as[String])
      case false => Left(res.statusCode)
    }
  }
}

And, if an implicit client is in scope, you can make use of send() on the request itself.

import scamper.BodyParser
import scamper.Implicits.stringToUri
import scamper.RequestMethod.Registry.Get
import scamper.client.HttpClient
import scamper.client.Implicits.ClientHttpRequestType // Adds send method to request
import scamper.headers.{ Accept, AcceptLanguage }
import scamper.types.Implicits.{ stringToMediaRange, stringToLanguageRange }

implicit val client = HttpClient()
implicit val parser = BodyParser.text(4096)

Get("http://localhost:8080/motd")
  .setAccept("text/plain")
  .setAcceptLanguage("en-US; q=0.6", "fr-CA; q=0.4")
  .send(res => println(res.as[String])) // Send request and print response

See also ClientSettings for information about configuring the HTTP client before it is created.

Definition Classes: scamper

package cookies

Provides specialized access to message cookies.

Request Cookies

In HttpRequest, cookies are stringed together in the Cookie header. You can access them using extension methods provided by RequestCookies, with each cookie represented as PlainCookie.

import scamper.Implicits.stringToUri
import scamper.RequestMethod.Registry.Get
import scamper.cookies.{ PlainCookie, RequestCookies }

// Build request with cookies
val req = Get("https://localhost:8080/motd").setCookies(
  PlainCookie("ID", "bG9zCg"), PlainCookie("Region", "SE-US")
)

// Print all cookies
req.cookies.foreach(println)

// Get cookies by name
val id: Option[PlainCookie] = req.getCookie("ID")
val region: Option[PlainCookie] = req.getCookie("Region")

// Get cookie values by name
assert(req.getCookieValue("ID").contains("bG9zCg"))
assert(req.getCookieValue("Region").contains("SE-US"))

Response Cookies

In HttpResponse, the cookies are a collection of Set-Cookie header values. Specialized access is provided by ResponseCookies, with each cookie represented as SetCookie.

import scamper.Implicits.stringToEntity
import scamper.ResponseStatus.Registry.Ok
import scamper.cookies.{ ResponseCookies, SetCookie }

// Build response with cookies
val res = Ok("There is an answer.").setCookies(
  SetCookie("ID", "bG9zCg", path = Some("/motd"), secure = true),
  SetCookie("Region", "SE-US")
)

// Print all cookies
res.cookies.foreach(println)

// Get cookies by name
val id: Option[SetCookie] = res.getCookie("ID")
val region: Option[SetCookie] = res.getCookie("Region")

// Get attributes of ID cookie
val path: String = id.flatMap(_.path).getOrElse("/")
val secure: Boolean = id.map(_.secure).getOrElse(false)

// Get cookie values by name
assert(res.getCookieValue("ID").contains("bG9zCg"))
assert(res.getCookieValue("Region").contains("SE-US"))

Definition Classes: scamper

package headers

Provides specialized access to message headers.

Using Header Classes

Specialized header access is provided by type classes. Some headers are available to both requests and responses, and others are available only to a specific message type. This behavior is driven by the HTTP specification.

import scamper.Implicits.stringToUri
import scamper.RequestMethod.Registry.Get
import scamper.headers.{ Accept, Host }
import scamper.types.Implicits.stringToMediaRange

// Build request using 'Host' and 'Accept' headers
val req = Get("/motd")
  .setHost("localhost:8080")
  .setAccept("text/plain")

// Access and print header values
printf("Host: %s%n", req.host)
printf("Accept: %s%n", req.accept.mkString(", "))

Definition Classes: scamper

package logging

Provides logging facilities.

Definition Classes: scamper

package server

Provides HTTP server implementation.

Building HTTP Server

To build a server, you begin with ServerApplication. This is a mutable structure to which you apply changes to configure the server. Once the desired settings are applied, you invoke one of several methods to create the server.

import java.io.File
import scamper.BodyParser
import scamper.Implicits.stringToEntity
import scamper.ResponseStatus.Registry.{ NotFound, Ok }
import scamper.server.HttpServer
import scamper.server.Implicits._

// Get server application
val app = HttpServer.app()

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

// Add request handler to specific request method and path
app.get("/about") { req =>
  Ok("This server is powered by Scamper.")
}

// Add request handler using path parameter
app.put("/data/:id") { req =>
  def update(id: Int, data: String): Boolean = ???

  implicit val parser = BodyParser.text()

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

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

// Serve static files
app.files("/main", new 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)

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

// Run server for 60 seconds
Thread.sleep(60 * 1000)

// Close server when done
server.close()

Definition Classes: scamper

ErrorHandler

HttpServer

Implicits

ParameterNotConvertible

ParameterNotFound

PathParameters

RequestHandler

ResponseAborted

ResponseFilter

Router

ServerApplication

WebSocketUpgrade

package types

Defines standard types for header values.

import scamper.Implicits.{ stringToEntity, stringToUri }
import scamper.RequestMethod.Registry.Get
import scamper.ResponseStatus.Registry.Ok
import scamper.headers.{ Accept, ContentType, TransferEncoding }
import scamper.types.{ MediaRange, MediaType, TransferCoding }

val json = MediaRange("application", "json", 0.9f)
val html = MediaRange("text/html; q=0.1")

val req = Get("/motd")
  .setAccept(json, html)

val text = MediaType("text/plain")
val gzip = TransferCoding("gzip")

val res = Ok("There is an answer.")
  .setContentType(text)
  .setTransferEncoding(gzip)

Using values defined in Implicits, properly formatted strings can be implicitly converted to standardized types.

import scamper.Implicits.{ stringToEntity, stringToUri }
import scamper.RequestMethod.Registry.Get
import scamper.ResponseStatus.Registry.Ok
import scamper.headers.{ Accept, ContentType, TransferEncoding }
import scamper.types.Implicits._

val req = Get("/motd")
  .setAccept("application/json; q=0.9", "text/html; q=0.1")

val res = Ok("There is an answer.")
  .setContentType("text/plain")
  .setTransferEncoding("gzip")

Definition Classes: scamper
See also: scamper.headers

package websocket

Provides WebSocket implementation.

Definition Classes: scamper

scamper

server

package server

Provides HTTP server implementation.

Building HTTP Server

import java.io.File
import scamper.BodyParser
import scamper.Implicits.stringToEntity
import scamper.ResponseStatus.Registry.{ NotFound, Ok }
import scamper.server.HttpServer
import scamper.server.Implicits._

// Get server application
val app = HttpServer.app()

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

// Add request handler to specific request method and path
app.get("/about") { req =>
  Ok("This server is powered by Scamper.")
}

// Add request handler using path parameter
app.put("/data/:id") { req =>
  def update(id: Int, data: String): Boolean = ???

  implicit val parser = BodyParser.text()

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

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

// Serve static files
app.files("/main", new 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)

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

// Run server for 60 seconds
Thread.sleep(60 * 1000)

// Close server when done
server.close()

Linear Supertypes

AnyRef, Any

Ordering

Alphabetic
By Inheritance

Inherited

server
AnyRef
Any

Hide All
Show All

Visibility

Public
All

Type Members

trait ErrorHandler extends AnyRef
Provides utility for handling error when servicing request.
trait HttpServer extends AnyRef
Provides handle to server instance.
Provides handle to server instance.

See also
HttpServer, ServerApplication
case class ParameterNotConvertible(name: String, value: String) extends HttpException with Product with Serializable
Indicates parameter cannot be converted.
case class ParameterNotFound(name: String) extends HttpException with Product with Serializable
Indicates parameter is not found.
trait PathParameters extends AnyRef
Provides access to path parameters.
trait RequestHandler extends AnyRef
Provides utility for handling incoming request.
case class ResponseAborted(message: String) extends HttpException with Product with Serializable
Indicates response was aborted.
Indicates response was aborted.
A RequestHandler throws ResponseAborted if no response should be sent for the request.
trait ResponseFilter extends AnyRef
Provides utility for filtering outgoing response.

trait Router extends AnyRef

Used for routing request handlers.

import scamper.Implicits.stringToEntity
import scamper.ResponseStatus.Registry.{ NotFound, Ok }
import scamper.server.HttpServer
import scamper.server.Implicits.ServerHttpRequestType

val app = HttpServer.app()

// Mount router to /api
app.route("/api") { router =>
  val messages = Map(1 -> "Hello, world!", 2 -> "Goodbye, cruel world!")

  // Map handler to /api/messages
  router.get("/messages") { req =>
    Ok(messages.mkString("\r\n"))
  }

  // Map handler to /api/messages/:id
  router.get("/messages/:id") { req =>
    val id = req.params.getInt("id")
    messages.get(id)
     .map(Ok(_))
     .getOrElse(NotFound())
  }
}

See also: ServerApplication.route

class ServerApplication extends Router
Configures and creates HttpServer.
Configures and creates HttpServer.
ServerApplication is a mutable structure. With each applied change, the application is modified and returned. After the desired settings are applied, a server is created using one of several factory methods.

Value Members

object HttpServer
Provides factory for creating HttpServer.
object Implicits
Includes server-side type classes.
object RequestHandler
Provides RequestHandler utilities.
object ResponseFilter
Provides ResponseFilter utilities.
object ServerApplication
Provides factory for ServerApplication.

object WebSocketUpgrade

Upgrades request to WebSocket connection.

import scamper.HttpRequest
import scamper.ResponseStatus.Registry.Unauthorized
import scamper.server.{ ServerApplication, WebSocketUpgrade }

val app = ServerApplication()

app.get("/chat/:roomId") { req =>
  def authorize(req: HttpRequest): Boolean = ...

  authorize(req) match {
    case true  =>
      WebSocketUpgrade(req) { session =>
        // Set up session
        ...
        session.open()
      }
    case false => Unauthorized()
  }
}

Packages

HTTP Messages

Challenges and Credentials

Basic Authentication

Bearer Authentication

Using HTTP Client

Creating HTTP Client

Request Cookies

Response Cookies

Using Header Classes

Building HTTP Server

server

package server

Building HTTP Server

Type Members

Value Members

Inherited from AnyRef

Inherited from Any

Ungrouped

Packages

HTTP Messages

Challenges and Credentials

Basic Authentication

Bearer Authentication

Using HTTP Client

Creating HTTP Client

Request Cookies

Response Cookies

Using Header Classes

Building HTTP Server

server 

package server

Building HTTP Server

Type Members

Value Members

Inherited from AnyRef

Inherited from Any

Ungrouped

server