Cascade is a collection of libraries that implement common patterns, convenience objects, implicit classes, utilities, and other foundational pieces used in Scala applications and servers at PayPal. The libraries herein are carefully designed to:
- Work well with Scala and the Typesafe libraries.
- Work independently from the others.
- Be well defined in their functionality.
- Minimize the number of external dependencies.
- Related to (4) - use the features of the Scala standard library before building their own.
The libraries live in separate sub-projects in this repository:
- common - utilities to help build any Scala program.
- http - building blocks for building Spray servers.
- akka - building blocks for building Akka systems.
- json - utilities to encode/decode JSON.
As mentioned in (2) above, these libraries are designed to work independently.
Although they have internal dependencies on each other (e.g. many libraries
depend on common
), you can mix and match which libraries you use.
The libraries in Cascade all follow some similar patterns. PATTERNS.md describes them in detail.
Current Version: 0.1.4
To use Cascade libraries in your project, simply add a dependency to your
build system. In an SBT project, add the following to your build.sbt
or
Build.scala
file:
"com.paypal" %% "cascade-$projectName" % "0.1.4"
For example, to use the Akka library:
"com.paypal" %% "cascade-akka" % "0.1.4"
If you're starting a new project, we recommend using SBT along with Horizon
Basic patterns, objects, and utilities for any project:
CascadeApp
is the starting place for building executable applications. It sets up logging and MDC values.LoggingSugar
provides easy access to SLF4J.trys
package object contains implicit classes/methods to convert Try objects to Either and Future objects.option
package object contains implicit classes/methods to wrap any object in an Option.casts
package object contains implicit classes/methods to cast objects to the class type provided.
Useful test objects include:
ActorSpecification
andMockActor
for testing Akka actors.- The
scalacheck
package object for extensions to Scalacheck.
Base objects and traits for creating Spray HTTP resources:
AbstractResource
is a starting point for HTTP resources.ResourceActor
provides an implementation of a basic HTTP request handling pipeline.ResourceDriver
spawns a ResourceActor, which should happen per request.ResourceService
is a routing base for HTTP services.resource
package object contains implicit classes for converting objects into Futures and Trys that return an exception on error.SprayActorComponent
provides the root actor implementation used by Spray.SprayConfigurationComponent
defines basic config for a Spray service.url
package object contains methods to break a query parameter list into a list or map.HttpUtil
pacakage object contains convenience methods for interacting with URLs.
http also provides two endpoints for projects that use it, implemented in the ResourceServiceComponent
:
-
/status
returns current build information for the project. This includes the service name, dependencies, and Git branch and commit information. Must include thex-service-status
header in request. For example, after running your project locally:curl -H "x-service-status:true" "http://localhost:9090/status
returns something like
{ "status":"ok", "service-name":"your-service", "dependencies":["all dependencies"], "git-info": { "branch":"develop", "branch-is-clean":"true", "commit-sha":"some-sha", "commit-date":"Wed Apr 16 12:01:28 PDT 2014" } }
-
/stats
returns internal Spray monitoring information for the build. Must include thex-service-stats
header in request, For example, after running your project locally:curl -H "x-service-stats:true" "http://localhost:9090/stats
returns something like
{ "uptime":{"finite":true}, "totalRequests":3, "openRequests":1, "maxOpenRequests":1, "totalConnections":3, "openConnections":1, "maxOpenConnections":1, "requestTimeouts":0 }
Useful test objects include:
DummyResource
for testing request logic.SprayMatchers
for confirming request/response patterns.SprayRoutingClient
for use in integration tests to test the full service stack, including Spray routes. Provides themakeRequest
methodfor interacting with a Spray service as if via HTTP, using the declared routes.
CommonActor
andServiceActor
are skeletons for building Akka actors. They provide logging during an actor's lifecycle and appropriately structure unhandled messages.ActorSystemComponent
defines an implicit actor system, actor ref factory, and execution context.config
package object provides an implicit class to get configuration values. It wraps Typesafe's Config getter methods in Options.ConfigComponent
providesval config
which uses Typesafe's ConfigFactory to load configuration files. Typically this will beapplication.conf
.
Simple functionality for fast JSON encoding/decoding that uses Jackson under the hood.
- The
JsonUtil
object provides two functions to do encoding and decoding:toJson(value: Any): Try[String]
- `fromJson[T: Manifest](json: String): Try[T]``
- The
json
package object provides implicit classes to wrapJsonUtil.toJson
andJsonUtil.fromJson
. If youimport com.paypal.cascade.json._
you can decode aString
using.fromJson[T]
and you can encode anAny
(any type) using.toJson
.
If you have Vagrant, simply vagrant up
in this project to get a VM with all the necessary
tools for development. When inside the VM, the sources for this project are inside /vagrant
, and they're
synched with your host machine. Edit your code on the host machine and build/run it inside the VM.
If you don't have Vagrant, you'll need Scala 2.11.2 and SBT 0.13.5 to build and run this project.
THIS FILE WAS AUTO GENERATED BY THE README TEMPLATE. DO NOT EDIT DIRECTLY.