Hackage :: [Package]

twirp: Haskell twirp foundations

This is a package candidate release! Here you can preview how this package release will appear once published to the main package index (which can be accomplished via the 'maintain' link below). Please note that once a package has been published to the main package index it cannot be undone! Please consult the package uploading documentation for more information.

[maintain] [Publish]

Please see the README on GitHub at https://github.com/tclem/twirp-haskell#readme

[Skip to Readme]

Properties

Versions 0.2.0.0, 0.2.0.1, 0.2.0.1, 0.2.2.0
Change log None available
Dependencies aeson (>=1.4.5.0 && <1.5), base (>=4.7 && <5), bytestring (>=0.10.8), http-media (>=0.8.0.0), http-types (>=0.12.3), proto-lens (>=0.5.0.0), proto-lens-jsonpb (>=0.2.0.2), proto-lens-runtime (>=0.7 && <0.8), servant (>=0.18 && <0.19), text (>=1.2.3.2 && <1.3), wai (>=3.2.2.1 && <3.3) [details]
License BSD-3-Clause
Copyright 2019 Timothy Clem
Author Timothy Clem
Maintainer timothy.clem@gmail.com
Category Web
Home page https://github.com/tclem/twirp-haskell#readme
Bug tracker https://github.com/tclem/twirp-haskell/issues
Source repo head: git clone https://github.com/tclem/twirp-haskell
Uploaded by rewinfrey at 2020-08-25T19:27:15Z

Modules

[Index] [Quick Jump]

Downloads

Maintainer's Corner

Package maintainers

For package maintainers and hackage trustees

Readme for twirp-0.2.0.1

[back to package description]

twirp-haskell

Very, very alpha implementation of Twirp service generation for Haskell.

This project provides a number of things:

  1. A protoc plugin for generating a Haskell Twirp service (based on Servant) for Services defined in a proto file.
  2. A haskell library, twirp for quickly serving up the generated application.

It requires the use of proto-lens to generate haskell datatypes from proto messages.

An example, end-to-end application is included in app.

Requirements

  1. Install protoc (e.g., brew install protoc)
  2. Install the required protoc plugins:
    • cabal install proto-lens-protoc
    • go get github.com/tclem/twirp-haskell/protoc-gen-twirp_haskell
    • go get github.com/tclem/proto-lens-jsonpb/protoc-gen-jsonpb_haskell

Usage

Use the protoc plugin to generate a twirp service and associated protobuf types from a proto file.

protoc -I=. --proto_path=./proto \
  --plugin=protoc-gen-haskell=`which proto-lens-protoc` --haskell_out=./app \
  --jsonpb_haskell_out=./app \
  --plugin=protoc-gen-twirp_haskell=./script/run-twirp_haskell --twirp_haskell_out=./app/Twirp/Example/Haberdasher \
  haberdasher.proto

The result is a couple of files that describe your service. First, here are the types that define a Servant API:

-- Code generated by protoc-gen-twirp_haskell 0.1.0, DO NOT EDIT.
{-# LANGUAGE TypeOperators #-}
module Twirp.Example.Haberdasher.Haberdasher where

import Servant
import Twirp

import Proto.Haberdasher

--  This is an example set of twirp services.

type HaberdasherAPI
  =    "twirp" :> "twirp.example.haberdasher.Haberdasher" :> HaberdasherService
  :<|> "twirp" :> "twirp.example.haberdasher.Health" :> HealthService

--  Haberdasher service makes hats for clients.
type HaberdasherService
  --  MakeHat produces a hat of mysterious, randomly-selected color!
  =    "MakeHat" :> ReqBody [Protobuf, JSON] Size :> Post '[Protobuf, JSON] Hat
  --  Get paid
  :<|> "GetBill" :> ReqBody [Protobuf, JSON] Hat :> Post '[Protobuf, JSON] Bill

--  Health check service
type HealthService
  =    "Check" :> ReqBody [Protobuf, JSON] Ping :> Post '[Protobuf, JSON] Pong

The datatypes are defined in Proto.Haberdasher.

Plugging this into an existing warp/wai server is straightforward. See app/Main.hs for the full details:

type RequestID = String

type API
  = Header "X-Request-Id" RequestID
  :> HaberdasherAPI

main :: IO ()
main = run 8003 app

app :: Application
app = twirpErrorResponses apiApp

apiApp :: Application
apiApp = serve (Proxy :: Proxy API) server

server :: Server API
server _requestID = (makeHat :<|> getBill) :<|> checkHealth