Hackage :: [Package]

twirp: Haskell twirp foundations

[ bsd3, library, web ] [ Propose Tags ] [ Report a vulnerability ]

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

[Skip to Readme]

Downloads

Maintainer's Corner

Package maintainers

For package maintainers and hackage trustees

Candidates

Versions [RSS] 0.2.0.0, 0.2.0.1, 0.2.2.0
Dependencies aeson (>=1.4 && <3), base (>=4.13 && <5), bytestring (>=0.10.8 && <12), http-media (>=0.8), http-types (>=0.12.3), proto-lens (>=0.5 && <0.8), proto-lens-jsonpb (==0.2.2), proto-lens-runtime, servant (>=0.16 && <0.20), text (>=1.2.3.2 && <3), wai (>=3.2.2.1) [details]
Tested with ghc ==8.10.7, ghc ==9.2.2
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 patrick_thomson at 2023-01-06T16:45:33Z
Distributions
Downloads 763 total (1 in the last 30 days)
Rating 2.0 (votes: 1) [estimated by Bayesian average]
Your Rating
  • λ
  • λ
  • λ
Status Docs uploaded by user
Build status unknown [no reports yet]

Readme for twirp-0.2.2.0

[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