This project has two main parts. The first is an HTTP Server micro-framework called Flint. The second is a server implementation using Flint that implements the cob_spec specification.
All code is written in Java 8 and uses the Activator build tool
You can assemble the server into a jar using the following command. The result can be found at target/scala-2.11/http-server-assembly-1.0.jar
> bin/activator assembly
Tests use JUnit with the junit-dataprovider test runner. Tests can be run through activator.
> bin/activator test
The cob_spec part of this project has FitNesse tests. You can refer to that project to see how to run those tests.
You can run the server with activator
> bin/activator run
Or, run the assembled jar
> java -jar target/scala-2.11/http-server-assembly.jar
The server takes two optional arguments [-p PORT] [-d DIRECTORY]. Where PORT is the port the server will listen on and DIRECTORY is where many of the resources expected in cob_spec will be served from.
Defaults:
- PORT: 5000
- DIRECTORY: public
> bin/activator "run -p 5000 -d public"
> java -jar target/scala-2.11/http-server-assembly.jar -p 5000 -d public"
Logs are written to stdout and a file at ./logs.
Javaslang is a functional programming library that makes using functional patterns in Java a little nicer. This project prefers Javaslang data structures over Java data structures because they are immutable and because they allow use of Javaslang functional programming features that don't exist in Java.
JParsec is a parser combinator that is used to parse HTTP messages. Using something like this allows me to implement a parser in a syntax that is very similar to the ABNF syntax used in all the RFCs that define HTTP and other supporting specifications. This way I can be more confident that I am implementing the specification correctly and completely.
Flint is largely inspired by my favorite web micro-framework Silex, which in turn is inspired by Sinatra.
The Application class represents your application. You define your application by adding routes that it serves.
Application app = new Application();
app.get("/hello", request -> {
Response response = Response.create(StatusCode.OK);
response.setHeader("Content-Type", "text/plain; charset=utf-8");
response.setBody("world");
return response;
});You are free to define your controllers any way you like as long as they take a Request and return a Response.
MyController myController = new MyController();
app.get("/foo/bar", myController::get);
app.post("/foo", myController::post);
app.delete("/foo/bar", myController::delete);Route creation helper functions exist for the following HTTP methods: GET, POST, PUT, PATCH, DELETE, OPTIONS. If you want to use another method you can use Application::match to specify your method.
app.match("FOO", "/hello", request -> /* ... */);Middleware allows you to run some code before or after each request. It allows you to alter the behavior of the server without having to add dependencies to the core Flint library. For example, each application can choose how it wants to do logging rather than depending on the way the server chooses to do it. Other useful things it could be used for are caching and partial content responses. It's also useful for reducing duplication and general organization.
Application app = new Application()
.before(loggerMiddleware::logRequest)
.after(RangeMiddleware::handleRange);Before middleware functions take a Request and returns a Request. After middleware functions take a Request and a Response and return a Response.
Middleware can also be applied to Routes.
app.get("/hello", request -> helloController::get)
.before(authorizationMiddleware::authorize);The Request class represents an HTTP request message. It gives you access to the request's method, path, headers, and body. Headers are always returned as Options.
request.getHeader("Content-Type");
request.getBody();HTTP defines several request formats. This implementation supports only the most common way called "origin-form". This form expects the domain to be specified in the Host header and the request-target to be the absolute-path with resepect the the Host domain.
The Response class represents an HTTP response message. It allows you to set the status code, headers, and body of a response. Create responses with the Response::create factory method. The StatusCode class contains constants for all the standard status codes.
The Content-Length header is set automatically when you set the body of a response.
Response response = Response.create(StatusCode.OK);
response.setBody("foo");
response.getHeader("Content-Length"); // Some("3")
response.setBody("foobar");
response.getHeader("Content-Length"); // Some("6")The body can also be set as an InputStream to avoid reading large resources into memory.
response.setBody(Files.newInputStream(path);The FormUrlencoded class allows you read, manipulate, and write content in the application/x-www-form-urlencoded format. This is the format HTML Forms use by default and the format normally used for query params.
Option<FormUrlencoded> content = request.getBody().map(FormUrlencoded::new);
Option<FormUrlencoded> queryParams = request.getQuery();
String pageSize = queryParams
.flatMap(query -> query.get("pageSize")
.getOrElse("10");The Cookie class provides support for the Cookie and Set-Cookie headers. Cookie support is very minimal. It allows reading and writing key value pairs.
Option<Cookie> cookie = request.getHeader("Cookie").map(Cookie::new);
String fooCookie = cookie
.flatMap(c -> c.get("foo")
.getOrElse("42");The PATCH method is intended to be used with a media type that describes the changes to be applied to the resource. Such media types have been defined for JSON and XML, but none exist for text documents. Since cob_spec does PATCH requests on text documents, I created a media type for the job and called it application/unix-diff. It uses the unix diff format to describe changes and can be applied on the server using the unix patch command.
From ??? to ???
| AV | IP | CP | SP | Description |
|---|
Legend: AV => Available, IP => In Progress, CP => Completed, SP => Story Points
| SP | Description |
|---|---|
| 3 | Add support for URI Templates. This would allow routes like app.get("/foo/{id}", request -> ...). Currently routes can only do exact matches which limits how dynamic the server can be. |
| 2 | Multiple byte range partial content support. Once single byte range support is complete, this shouldn't be too difficult. |
| 2 | Decouple parser from flint and make it its own package. If the dependency only goes one way, it could later be expanded into a general purpose tool for parsing anything HTTP related. For example, an HTTP Client would require a parser that has a lot of overlap with the parsing needs for an HTTP Server. |
| 2 | Introduce a way to group routes so middleware can be applied to an arbitrary group rather than just one Route or all Routes. |
| 2 | Make default templates pluggable rather than hard-coded in Application |