https://github.com/npryce/krouton

Typesafe, compositional routing and reverse routing for web apps and HTTP microservices
https://github.com/npryce/krouton

Last synced: about 1 year ago
JSON representation

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

• Host: GitHub
• URL: https://github.com/npryce/krouton
• Owner: npryce
• License: apache-2.0
• Created: 2016-02-25T23:21:42.000Z (over 10 years ago)
• Default Branch: master
• Last Pushed: 2020-11-20T08:50:38.000Z (over 5 years ago)
• Last Synced: 2025-02-06T00:43:25.524Z (over 1 year ago)
• Language: Kotlin
• Homepage:
• Size: 352 KB
• Stars: 25
• Watchers: 4
• Forks: 5
• Open Issues: 1
• Metadata Files:
  • Readme: README.md
  • License: LICENSE

Awesome Lists containing this project

README

          
# Krouton

Typesafe, compositional routing and reverse routing for [Kotlin](https://kotlinlang.org) web apps and HTTP microservices.

[![Kotlin](https://img.shields.io/badge/kotlin-1.2.51-blue.svg)](http://kotlinlang.org)

[![Build Status](https://travis-ci.org/npryce/krouton.svg?branch=master)](https://travis-ci.org/npryce/krouton)

[![Maven Central](https://img.shields.io/maven-central/v/com.natpryce/krouton.svg)](http://search.maven.org/#search%7Cga%7C1%7Cg%3A%22com.natpryce%22%20AND%20a%3A%22krouton%22)

[![Apache 2.0](https://img.shields.io/badge/license-Apache%20License%202.0-blue.svg?style=flat)](http//www.apache.org/licenses/LICENSE-2.0)

Krouton provides a routing API for [HTTP4K](https://http4k.org), but the core abstractions can be used with any web server library.

## Examples

 * [Routing and reverse routing with HTTP4K](src/test/kotlin/com/natpryce/krouton/example/HttpRoutingExample.kt)

## 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.parse(String) -> T?`

* Reverse Routing: `UrlScheme.path(T) -> String`

* Reporting: `UrlScheme.monitoredPath(T)-> String`

## Route composition

* Append: 

    * `UrlScheme + UrlScheme -> UrlScheme>`

    * `+` operator supports appending paths for scalars and tuples, forming paths for tuples with up to five elements

    * `UrlScheme + UrlScheme -> UrlScheme`

    * `UrlScheme + UrlScheme -> UrlScheme`

* Append fixed path element: `UrlScheme + String -> UrlScheme`

* Restrict: `UrlScheme where ((T)->Boolean) -> UrlScheme`

* Project: `UrlScheme asA Projection -> UrlScheme`

## 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](https://semver.org).  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.