twirp: Haskell twirp foundations

[ bsd3, library, web ] [ Propose Tags ]

Please see the README on GitHub at

[Skip to Readme]
Versions [faq],
Dependencies aeson (>= && <1.5), base (>=4.7 && <5), bytestring (>=0.10.8), http-media (>=, http-types (>=0.12.3), proto-lens (>=, proto-lens-jsonpb (>=, proto-lens-runtime (==0.7.*), servant (==0.18.*), text (>= && <1.3), wai (>= && <3.3) [details]
License BSD-3-Clause
Copyright 2019 Timothy Clem
Author Timothy Clem
Category Web
Home page
Bug tracker
Source repo head: git clone
Uploaded by rewinfrey at 2020-08-25T19:27:34Z
Distributions NixOS:
Downloads 427 total (6 in the last 30 days)
Rating (no votes yet) [estimated by Bayesian average]
Your Rating
  • λ
  • λ
  • λ
Status Hackage Matrix CI
Docs uploaded by user
Build status unknown [no reports yet]


[Index] [Quick Jump]


Maintainer's Corner

For package maintainers and hackage trustees

Readme for twirp-

[back to package description]


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.


  1. Install protoc (e.g., brew install protoc)
  2. Install the required protoc plugins:
    • cabal install proto-lens-protoc
    • go get
    • go get


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 \

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