anmolitor / elm-grpc / Grpc

This is the public API for gRPC application usage. It is intended to be imported qualified.

Main Types


type alias Rpc req res =
Internal.Rpc req res

Opaque type for an rpc endpoint. These should be constructed by the protoc-gen-elm code generator. If for some reason, you need to define an endpoint by hand, you can do so by importing the Grpc.Internal module.


type alias RpcRequest req res =
InternalRpcRequest req res Basics.Never

A request to the server that has not been sent yet. This is designed to be used in a builder-pattern kind of way:

Grpc.new helloWorld "hello"
    |> Grpc.addHeader "authorization" token
    |> Grpc.setHost "http://example.com"

In this example `helloWorld` could be a value of type `Rpc String String` that was generated by `protoc-gen-elm`.

new : Rpc req res -> req -> RpcRequest req res

Build a request from an rpc endpoint by providing a request body.

Configuring the request

addHeader : String -> String -> InternalRpcRequest req res usesTracker -> InternalRpcRequest req res usesTracker

Add a header to a request. The first parameter is the header name, the second parameter is the value.

addHeaders : List ( String, String ) -> InternalRpcRequest req res usesTracker -> InternalRpcRequest req res usesTracker

Add multiple headers at once to a request.

setHost : String -> InternalRpcRequest req res usesTracker -> InternalRpcRequest req res usesTracker

Set the host for the request. By default the host is empty (i.e. the current website), which is recommended to avoid CORS issues.

setTimeout : Basics.Float -> InternalRpcRequest req res usesTracker -> InternalRpcRequest req res usesTracker

Make the request cancel itself after a given timeout in milliseconds.

setTracker : String -> InternalRpcRequest req res usesTracker -> InternalRpcRequest req res ()

The tracker lets you cancel and track requests via Http.cancel and Http.track. This only works if you use toCmd to send your Request, Tasks unfortunately do not support this. We use the type system to our advantage here to prevent you from calling toTask after using this function.

withRisk : InternalRpcRequest req res usesTracker -> InternalRpcRequest req res usesTracker

Make the request "risky" (i.e. "withCredentials=true" in javascript). This allows Set-Cookie to function in gRPC responses.

Sending the request

toTask : RpcRequest req res -> Task Error res

Convert the given RpcRequest into a Task. This can be useful if you want to chain multiple requests but are only interested in the end result.

toCmd : (Result Error res -> msg) -> InternalRpcRequest req res usesTracker -> Platform.Cmd.Cmd msg

Convert the given RpcRequest into a Command to make the Elm runtime execute the request.

Handling Errors


type Error
    = BadUrl String
    | Timeout
    | NetworkError
    | BadStatus ({ metadata : Http.Metadata, response : Bytes, errMessage : String, status : GrpcStatus })
    | BadBody Bytes
    | UnknownGrpcStatus String

A gRPC request may fail with in a variety of ways. Since the request is just a HTTP request under the hood, it may fail in the roughly same ways a HTTP request could.

  - something that is not an `Int`
  - an `Int` that is outside of the range of the `ErrCode` enum.

Note that not setting the header is fine and will delegate failure checking to the HTTP status.


type GrpcStatus
    = Ok_
    | Cancelled
    | Unknown
    | InvalidArgument
    | DeadlineExceeded
    | NotFound
    | AlreadyExists
    | PermissionDenied
    | ResourceExhausted
    | FailedPrecondition
    | Aborted
    | OutOfRange
    | Unimplemented
    | Internal
    | Unavailable
    | DataLoss
    | Unauthenticated

A valid grpc-status header encodes one of these possibilities as an Int.