Solga

Serving APIs

serve :: Router r => r -> Application

Serve a Router with Solga, returning SolgaErrors as HTTP responses and other errors as HTTP 500.

serveThrow :: Router r => r -> Application

Serve a Router with Solga, throwing SolgaErrors.

Basic routers

type (:>) f g = f g infixr 2

Compose routers. This is just type application, ie.: Foo :> Bar :> Baz == Foo (Bar Baz)

type (/>) seg g = Seg seg :> g infixr 2

Match a path, segment, e.g "foo" /> JSON Bar

type Get a = Endpoint "GET" (JSON a)

Handle a GET request and produce a JSON response, with IO.

type Post a = Endpoint "POST" (JSON a)

Handle a POST request and produce a JSON response, with IO.

newtype JSON a

Return a given JSON object

Constructors

JSON

Fields

• jsonResponse :: a

Instances

Eq a => Eq (JSON a)

Methods

(==) :: JSON a -> JSON a -> Bool

(/=) :: JSON a -> JSON a -> Bool

Ord a => Ord (JSON a)

Methods

compare :: JSON a -> JSON a -> Ordering

(<) :: JSON a -> JSON a -> Bool

(<=) :: JSON a -> JSON a -> Bool

(>) :: JSON a -> JSON a -> Bool

(>=) :: JSON a -> JSON a -> Bool

max :: JSON a -> JSON a -> JSON a

min :: JSON a -> JSON a -> JSON a

Show a => Show (JSON a)

Methods

showsPrec :: Int -> JSON a -> ShowS

show :: JSON a -> String

showList :: [JSON a] -> ShowS

Abbreviated (JSON a)

Associated Types

type Brief (JSON a) :: *

Methods

brief :: Brief (JSON a) -> JSON a

ToJSON a => Router (JSON a)

Methods

tryRoute :: Request -> Maybe (JSON a -> Responder)

type Brief (JSON a)

type Brief (JSON a) = a

newtype Raw

Serve a given WAI Application.

Constructors

Raw

Fields

• rawApp :: Application

Instances

Abbreviated Raw

Associated Types

type Brief Raw :: *

Methods

brief :: Brief Raw -> Raw

Router Raw

Methods

tryRoute :: Request -> Maybe (Raw -> Responder)

type Brief Raw

type Brief Raw = Application

newtype RawResponse

Serve a given WAI Response.

Constructors

RawResponse

Fields

• rawResponse :: Response

Instances

Abbreviated RawResponse

Associated Types

type Brief RawResponse :: *

Methods

brief :: Brief RawResponse -> RawResponse

Router RawResponse

Methods

tryRoute :: Request -> Maybe (RawResponse -> Responder)

type Brief RawResponse

type Brief RawResponse = Response

newtype End next

Only accept the end of a path.

Constructors

End

Fields

• endNext :: next

Instances

Abbreviated next => Abbreviated (End next)

Associated Types

type Brief (End next) :: *

Methods

brief :: Brief (End next) -> End next

Router next => Router (End next)

Methods

tryRoute :: Request -> Maybe (End next -> Responder)

type Brief (End next)

type Brief (End next) = Brief next

newtype WithIO next

Produce a response with IO.

Constructors

WithIO

Fields

• withIONext :: IO next

Instances

Abbreviated next => Abbreviated (WithIO next)

Associated Types

type Brief (WithIO next) :: *

Methods

brief :: Brief (WithIO next) -> WithIO next

Router next => Router (WithIO next)

Methods

tryRoute :: Request -> Maybe (WithIO next -> Responder)

type Brief (WithIO next)

type Brief (WithIO next) = IO (Brief next)

newtype Seg seg next

Match a constant directory in the path.

When specifying APIs, use the /> combinator to specify sub-paths: "foo" /> JSON Bar

Constructors

Seg

Fields

• segNext :: next

Instances

Eq next => Eq (Seg seg next)

Methods

(==) :: Seg seg next -> Seg seg next -> Bool

(/=) :: Seg seg next -> Seg seg next -> Bool

Ord next => Ord (Seg seg next)

Methods

compare :: Seg seg next -> Seg seg next -> Ordering

(<) :: Seg seg next -> Seg seg next -> Bool

(<=) :: Seg seg next -> Seg seg next -> Bool

(>) :: Seg seg next -> Seg seg next -> Bool

(>=) :: Seg seg next -> Seg seg next -> Bool

max :: Seg seg next -> Seg seg next -> Seg seg next

min :: Seg seg next -> Seg seg next -> Seg seg next

Show next => Show (Seg seg next)

Methods

showsPrec :: Int -> Seg seg next -> ShowS

show :: Seg seg next -> String

showList :: [Seg seg next] -> ShowS

Abbreviated next => Abbreviated (Seg seg next)

Associated Types

type Brief (Seg seg next) :: *

Methods

brief :: Brief (Seg seg next) -> Seg seg next

(KnownSymbol seg, Router next) => Router (Seg seg next)

Methods

tryRoute :: Request -> Maybe (Seg seg next -> Responder)

type Brief (Seg seg next)

type Brief (Seg seg next) = Brief next

data OneOfSegs segs next

Match any of a set of path segments.

Constructors

OneOfSegs

Fields

• oneOfSegsNext :: next

Instances

Abbreviated next => Abbreviated (OneOfSegs segs next)

Associated Types

type Brief (OneOfSegs segs next) :: *

Methods

brief :: Brief (OneOfSegs segs next) -> OneOfSegs segs next

(KnownSymbol seg, Router next, Router (OneOfSegs segs next)) => Router (OneOfSegs ((:) Symbol seg segs) next)

Methods

tryRoute :: Request -> Maybe (OneOfSegs ((Symbol ': seg) segs) next -> Responder)

Router next => Router (OneOfSegs ([] Symbol) next)

Methods

tryRoute :: Request -> Maybe (OneOfSegs [Symbol] next -> Responder)

type Brief (OneOfSegs segs next)

type Brief (OneOfSegs segs next) = Brief next

class FromSegment a where

The class of types that can be parsed from a path segment.

Minimal complete definition

fromSegment

Methods

fromSegment :: Text -> Maybe a

Instances

FromSegment Text

Methods

fromSegment :: Text -> Maybe Text

newtype Capture a next

Capture a path segment and pass it on.

Constructors

Capture

Fields

• captureNext :: a -> next

Instances

Abbreviated next => Abbreviated (Capture a next)

Associated Types

type Brief (Capture a next) :: *

Methods

brief :: Brief (Capture a next) -> Capture a next

(FromSegment a, Router next) => Router (Capture a next)

Methods

tryRoute :: Request -> Maybe (Capture a next -> Responder)

type Brief (Capture a next)

type Brief (Capture a next) = a -> Brief next

newtype Method method next

Accepts requests with a certain method.

Constructors

Method

Fields

• methodNext :: next

Instances

Eq next => Eq (Method method next)

Methods

(==) :: Method method next -> Method method next -> Bool

(/=) :: Method method next -> Method method next -> Bool

Ord next => Ord (Method method next)

Methods

compare :: Method method next -> Method method next -> Ordering

(<) :: Method method next -> Method method next -> Bool

(<=) :: Method method next -> Method method next -> Bool

(>) :: Method method next -> Method method next -> Bool

(>=) :: Method method next -> Method method next -> Bool

max :: Method method next -> Method method next -> Method method next

min :: Method method next -> Method method next -> Method method next

Show next => Show (Method method next)

Methods

showsPrec :: Int -> Method method next -> ShowS

show :: Method method next -> String

showList :: [Method method next] -> ShowS

Abbreviated next => Abbreviated (Method method next)

Associated Types

type Brief (Method method next) :: *

Methods

brief :: Brief (Method method next) -> Method method next

(KnownSymbol method, Router next) => Router (Method method next)

Methods

tryRoute :: Request -> Maybe (Method method next -> Responder)

type Brief (Method method next)

type Brief (Method method next) = Brief next

data ExtraHeaders next

Set extra headers on responses. Existing headers will be overriden if specified here.

Constructors

ExtraHeaders

Fields

• extraHeaders :: ResponseHeaders
• extraHeadersNext :: next

Instances

Abbreviated (ExtraHeaders next)

Associated Types

type Brief (ExtraHeaders next) :: *

Methods

brief :: Brief (ExtraHeaders next) -> ExtraHeaders next

Router next => Router (ExtraHeaders next)

Methods

tryRoute :: Request -> Maybe (ExtraHeaders next -> Responder)

type Brief (ExtraHeaders next)

type Brief (ExtraHeaders next) = ExtraHeaders next

newtype NoCache next

Prevent caching for sub-routers.

Constructors

NoCache

Fields

• noCacheNext :: next

Instances

Abbreviated next => Abbreviated (NoCache next)

Associated Types

type Brief (NoCache next) :: *

Methods

brief :: Brief (NoCache next) -> NoCache next

Router next => Router (NoCache next)

Methods

tryRoute :: Request -> Maybe (NoCache next -> Responder)

type Brief (NoCache next)

type Brief (NoCache next) = Brief next

newtype ReqBodyJSON a next

Parse a JSON request body.

Constructors

ReqBodyJSON

Fields

• reqBodyJSONNext :: a -> next

Instances

Abbreviated next => Abbreviated (ReqBodyJSON a next)

Associated Types

type Brief (ReqBodyJSON a next) :: *

Methods

brief :: Brief (ReqBodyJSON a next) -> ReqBodyJSON a next

(FromJSON a, Router next) => Router (ReqBodyJSON a next)

Methods

tryRoute :: Request -> Maybe (ReqBodyJSON a next -> Responder)

type Brief (ReqBodyJSON a next)

type Brief (ReqBodyJSON a next) = a -> Brief next

type MultiPartData = ([Param], [File FilePath])

A parsed "multipart/form-data" request.

data ReqBodyMultipart a next

Accept a "multipart/form-data" request. Files will be stored in a temporary directory and will be deleted automatically after the request is processed.

Constructors

ReqBodyMultipart

Fields

• reqMultiPartParse :: MultiPartData -> Either String a
• reqMultiPartNext :: a -> next

Instances

Abbreviated (ReqBodyMultipart a next)

Associated Types

type Brief (ReqBodyMultipart a next) :: *

Methods

brief :: Brief (ReqBodyMultipart a next) -> ReqBodyMultipart a next

Router next => Router (ReqBodyMultipart a next)

Methods

tryRoute :: Request -> Maybe (ReqBodyMultipart a next -> Responder)

type Brief (ReqBodyMultipart a next)

type Brief (ReqBodyMultipart a next) = ReqBodyMultipart a next

type Endpoint method a = End :> (NoCache :> (Method method :> (WithIO :> a)))

Useful synonym for dynamic endpoints: accept requests with a given method, compute a JSON response in IO and don't cache.

data left :<|> right infixr 1

Try to route with left, or try to route with right.

Constructors

(:<|>) infixr 1

Fields

• altLeft :: left
• altRight :: right

Instances

(Eq right, Eq left) => Eq ((:<|>) left right)

Methods

(==) :: (left :<|> right) -> (left :<|> right) -> Bool

(/=) :: (left :<|> right) -> (left :<|> right) -> Bool

(Ord right, Ord left) => Ord ((:<|>) left right)

Methods

compare :: (left :<|> right) -> (left :<|> right) -> Ordering

(<) :: (left :<|> right) -> (left :<|> right) -> Bool

(<=) :: (left :<|> right) -> (left :<|> right) -> Bool

(>) :: (left :<|> right) -> (left :<|> right) -> Bool

(>=) :: (left :<|> right) -> (left :<|> right) -> Bool

max :: (left :<|> right) -> (left :<|> right) -> left :<|> right

min :: (left :<|> right) -> (left :<|> right) -> left :<|> right

(Show right, Show left) => Show ((:<|>) left right)

Methods

showsPrec :: Int -> (left :<|> right) -> ShowS

show :: (left :<|> right) -> String

showList :: [left :<|> right] -> ShowS

(Abbreviated left, Abbreviated right) => Abbreviated ((:<|>) left right)

Associated Types

type Brief ((:<|>) left right) :: *

Methods

brief :: Brief (left :<|> right) -> left :<|> right

(Router left, Router right) => Router ((:<|>) left right)

Methods

tryRoute :: Request -> Maybe ((left :<|> right) -> Responder)

type Brief ((:<|>) left right)

type Brief ((:<|>) left right) = (:<|>) (Brief left) (Brief right)

Abbreviation

class Abbreviated a where

Most Routers are really just newtypes. By using brief, you can construct trees of Routers by providing only their inner types, much like Servant.

Associated Types

type Brief a :: *

Methods

brief :: Brief a -> a

brief :: a -> a

Instances

Abbreviated RawResponse

Associated Types

type Brief RawResponse :: *

Methods

brief :: Brief RawResponse -> RawResponse

Abbreviated Raw

Associated Types

type Brief Raw :: *

Methods

brief :: Brief Raw -> Raw

Abbreviated next => Abbreviated (WithIO next)

Associated Types

type Brief (WithIO next) :: *

Methods

brief :: Brief (WithIO next) -> WithIO next

Abbreviated next => Abbreviated (NoCache next)

Associated Types

type Brief (NoCache next) :: *

Methods

brief :: Brief (NoCache next) -> NoCache next

Abbreviated (ExtraHeaders next)

Associated Types

type Brief (ExtraHeaders next) :: *

Methods

brief :: Brief (ExtraHeaders next) -> ExtraHeaders next

Abbreviated (JSON a)

Associated Types

type Brief (JSON a) :: *

Methods

brief :: Brief (JSON a) -> JSON a

Abbreviated next => Abbreviated (End next)

Associated Types

type Brief (End next) :: *

Methods

brief :: Brief (End next) -> End next

Abbreviated (ReqBodyMultipart a next)

Associated Types

type Brief (ReqBodyMultipart a next) :: *

Methods

brief :: Brief (ReqBodyMultipart a next) -> ReqBodyMultipart a next

Abbreviated next => Abbreviated (ReqBodyJSON a next)

Associated Types

type Brief (ReqBodyJSON a next) :: *

Methods

brief :: Brief (ReqBodyJSON a next) -> ReqBodyJSON a next

Abbreviated next => Abbreviated (Method method next)

Associated Types

type Brief (Method method next) :: *

Methods

brief :: Brief (Method method next) -> Method method next

Abbreviated next => Abbreviated (Capture a next)

Associated Types

type Brief (Capture a next) :: *

Methods

brief :: Brief (Capture a next) -> Capture a next

Abbreviated next => Abbreviated (OneOfSegs segs next)

Associated Types

type Brief (OneOfSegs segs next) :: *

Methods

brief :: Brief (OneOfSegs segs next) -> OneOfSegs segs next

(Abbreviated left, Abbreviated right) => Abbreviated ((:<|>) left right)

Associated Types

type Brief ((:<|>) left right) :: *

Methods

brief :: Brief (left :<|> right) -> left :<|> right

Abbreviated next => Abbreviated (Seg seg next)

Associated Types

type Brief (Seg seg next) :: *

Methods

brief :: Brief (Seg seg next) -> Seg seg next

Error handling

data SolgaError

A Router-related exception with a corresponding HTTP error code.

Instances

Eq SolgaError

Methods

(==) :: SolgaError -> SolgaError -> Bool

(/=) :: SolgaError -> SolgaError -> Bool

Ord SolgaError

Methods

compare :: SolgaError -> SolgaError -> Ordering

(<) :: SolgaError -> SolgaError -> Bool

(<=) :: SolgaError -> SolgaError -> Bool

(>) :: SolgaError -> SolgaError -> Bool

(>=) :: SolgaError -> SolgaError -> Bool

max :: SolgaError -> SolgaError -> SolgaError

min :: SolgaError -> SolgaError -> SolgaError

Show SolgaError

Methods

showsPrec :: Int -> SolgaError -> ShowS

show :: SolgaError -> String

showList :: [SolgaError] -> ShowS

Exception SolgaError

Methods

toException :: SolgaError -> SomeException

fromException :: SomeException -> Maybe SolgaError

displayException :: SolgaError -> String

badRequest :: Text -> SolgaError

Create a 400 Bad Request error with a given message.

notFound :: Text -> SolgaError

Create a 404 Not Found error with a given message.

Router implementation

class Router r where

Routers are the basic typeclass of Solga: their types describe what type of requests they accept, and their values describe how to handle them.

You can use Generic to get free instance of Router for any data type with one constructor and Routers as fields. The fields will be considered alternatives, as if you wrote :<|> between them.

Methods

tryRoute :: Request -> Maybe (r -> Responder)

Given a request, if the router supports the given request return a function that constructs a response with a concrete router.

tryRoute :: (Generic r, Router (Rep r ())) => Request -> Maybe (r -> Responder)

Given a request, if the router supports the given request return a function that constructs a response with a concrete router.

Instances

Router RawResponse

Methods

tryRoute :: Request -> Maybe (RawResponse -> Responder)

Router Raw

Methods

tryRoute :: Request -> Maybe (Raw -> Responder)

Router next => Router (WithIO next)

Methods

tryRoute :: Request -> Maybe (WithIO next -> Responder)

Router next => Router (NoCache next)

Methods

tryRoute :: Request -> Maybe (NoCache next -> Responder)

Router next => Router (ExtraHeaders next)

Methods

tryRoute :: Request -> Maybe (ExtraHeaders next -> Responder)

ToJSON a => Router (JSON a)

Methods

tryRoute :: Request -> Maybe (JSON a -> Responder)

Router next => Router (End next)

Methods

tryRoute :: Request -> Maybe (End next -> Responder)

Router next => Router (ReqBodyMultipart a next)

Methods

tryRoute :: Request -> Maybe (ReqBodyMultipart a next -> Responder)

(FromJSON a, Router next) => Router (ReqBodyJSON a next)

Methods

tryRoute :: Request -> Maybe (ReqBodyJSON a next -> Responder)

(KnownSymbol method, Router next) => Router (Method method next)

Methods

tryRoute :: Request -> Maybe (Method method next -> Responder)

(FromSegment a, Router next) => Router (Capture a next)

Methods

tryRoute :: Request -> Maybe (Capture a next -> Responder)

(KnownSymbol seg, Router next, Router (OneOfSegs segs next)) => Router (OneOfSegs ((:) Symbol seg segs) next)

Methods

tryRoute :: Request -> Maybe (OneOfSegs ((Symbol ': seg) segs) next -> Responder)

Router next => Router (OneOfSegs ([] Symbol) next)

Methods

tryRoute :: Request -> Maybe (OneOfSegs [Symbol] next -> Responder)

(Router left, Router right) => Router ((:<|>) left right)

Methods

tryRoute :: Request -> Maybe ((left :<|> right) -> Responder)

(KnownSymbol seg, Router next) => Router (Seg seg next)

Methods

tryRoute :: Request -> Maybe (Seg seg next -> Responder)

Router r => Router (K1 i r p)

Methods

tryRoute :: Request -> Maybe (K1 i r p -> Responder)

(Router (left p), Router (right p)) => Router ((:*:) left right p)

Methods

tryRoute :: Request -> Maybe ((left :*: right) p -> Responder)

Router (f p) => Router (M1 i c f p)

Methods

tryRoute :: Request -> Maybe (M1 i c f p -> Responder)

type Responder = (Response -> IO ResponseReceived) -> IO ResponseReceived

The right hand side of Application. Request is already known.

tryRouteNext :: Router r' => (r -> r') -> Request -> Maybe (r -> Responder)

Try to route using a type r by providing a function to turn it into a Router r'. Useful for passing routing on to the next step.

tryRouteNextIO :: Router r' => (r -> IO r') -> Request -> Maybe (r -> Responder)

Like tryRouteNext but in IO.