Skip to content

Latest commit

 

History

History
64 lines (41 loc) · 3.01 KB

README.md

File metadata and controls

64 lines (41 loc) · 3.01 KB
Raw

Krouton

Typesafe, compositional routing and reverse routing for Kotlin web apps and HTTP microservices.

Kotlin Build Status Maven Central Apache 2.0

Krouton provides a routing API for HTTP4K, but the core abstractions can be used with any web server library.

Examples

Principles

Type safe routing and reverse routing.

No reflection, annotations or classpath scanning.

Explicit, type-checked flow of data and control, instead of "spooky action at a distance" via reflection, annotations, classpath scanning, passing data in context maps or synthetic HTTP headers, or control flow via exceptions.

Separate code that routes and handles requests from definitions of URLs

  • URLs defined by constants (immutable objects)
  • Routing policy defined by operations on those constants
  • Routing done by functions/closures/objects that connect Krouton's routing policy API to a web server library.

Compositional: routes are composed from primitive parts and composition operators. User-defined routes can be used in exactly the same way as the predefined primitives.

Mandatory aspects of a resource locator go in the path

Query parameters are optional and are interpreted by the resource.

Routing policy operations

  • Parsing: UrlScheme<T>.parse(String) -> T?
  • Reverse Routing: UrlScheme<T>.path(T) -> String
  • Reporting: UrlScheme<T>.monitoredPath(T)-> String

Route composition

  • Append:
    • UrlScheme<T> + UrlScheme<U> -> UrlScheme<Tuple2<T,U>>
    • + operator supports appending paths for scalars and tuples, forming paths for tuples with up to five elements
    • UrlScheme<Unit> + UrlScheme<T> -> UrlScheme<T>
    • UrlScheme<T> + UrlScheme<Unit> -> UrlScheme<T>
  • Append fixed path element: UrlScheme<T> + String -> UrlScheme<T>
  • Restrict: UrlScheme<T> where ((T)->Boolean) -> UrlScheme<T>
  • Project: UrlScheme<T> asA Projection<T,U> -> UrlScheme<U>

What's with the version number?

The version number is {mental}.{major}.{minor}.{patch}. The last three digits are treated as a semantic version number. The first digit is incremented if there is a significant change in the mental model underpinning the library. A major version of zero always signifies a pre-release version, irrespective of the value of the first digit. The API of pre-release versions may go through significant changes in response to user feedback before the release of version x.1.0.0.