This is the public API for gRPC application usage. It is intended to be imported qualified.
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.
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.
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.
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.
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.
BadUrl
means you did not provide a valid URL.
Timeout
means it took too long to get a response.
NetworkError
means the user turned off their wifi, went in a cave, etc.
BadStatus
means you got a response back, but the http status code indicates failure. This can be either
a bad HTTP status code or a bad grpc-status
response header according to
https://github.com/grpc/grpc/blob/master/doc/http-grpc-status-mapping.md
BadBody
means you got a response back with a nice status code, but the body
of the response was something unexpected. The Bytes
in this case is the response that failed to be parsed.
UnknownGrpcStatus
means you got a response back but the grpc-status
header was set to either
- 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.
A valid grpc-status
header encodes one of these possibilities as an Int.
0
-> Ok_1
-> Cancelled2
-> Unknown