| Safe Haskell | None |
|---|---|
| Language | Haskell2010 |
Web.Spock.Api.Client
Description
Typed clients for the same endpoint definitions used by Spock's server.
Use browserClient from Web.Spock.Api.Client.Browser with GHC's JavaScript
backend, or supply a transport to newClient. Errors are explicit values;
this module never prints response bodies or credentials.
Synopsis
- data Client
- data ClientConfig = ClientConfig {
- cc_baseUrl :: Text
- cc_headers :: [Header]
- cc_credentials :: Credentials
- cc_timeoutMilliseconds :: Int
- cc_maxResponseBytes :: Int
- cc_slashPolicy :: SlashPolicy
- defaultClientConfig :: ClientConfig
- data Credentials
- data ClientError
- type Header = (Text, Text)
- data Request = Request {
- rq_method :: Text
- rq_url :: Text
- rq_headers :: [(ByteString, ByteString)]
- rq_body :: Maybe ByteString
- rq_credentials :: Credentials
- rq_timeoutMilliseconds :: Int
- rq_maxResponseBytes :: Int
- data Response = Response {}
- type Transport = Request -> IO (Either ClientError Response)
- newClient :: ClientConfig -> Transport -> Either ClientError Client
- callEndpoint :: forall (p :: [Type]) (i :: Maybe Type) o. (HasRep p, HasRep (MaybeToList i), AllHave ToHttpApiData p) => Client -> Endpoint p i o -> HVectElim p (HVectElim (MaybeToList i) (IO (Either ClientError o)))
- callEndpoint' :: forall (p :: [Type]) (i :: Maybe Type) o. (HasRep p, HasRep (MaybeToList i), AllHave ToHttpApiData p) => Client -> Endpoint p i o -> [Header] -> HVectElim p (HVectElim (MaybeToList i) (IO (Either ClientError o)))
- callDocumentedEndpoint :: forall (p :: [Type]) (q :: [Type]) (i :: Maybe Type) o. (HasRep p, HasRep q, HasRep (MaybeToList i), AllHave ToHttpApiData p) => Client -> DocumentedEndpoint p q i o -> HVectElim p (HVectElim q (HVectElim (MaybeToList i) (IO (Either ClientError o))))
- callDocumentedEndpoint' :: forall (p :: [Type]) (q :: [Type]) (i :: Maybe Type) o. (HasRep p, HasRep q, HasRep (MaybeToList i), AllHave ToHttpApiData p) => Client -> DocumentedEndpoint p q i o -> [Header] -> HVectElim p (HVectElim q (HVectElim (MaybeToList i) (IO (Either ClientError o))))
- prepareEndpoint :: forall (p :: [Type]) (i :: Maybe Type) o. AllHave ToHttpApiData p => ClientConfig -> Endpoint p i o -> [Header] -> HVect p -> HVect (MaybeToList i) -> Either ClientError Request
- prepareDocumentedEndpoint :: forall (p :: [Type]) (q :: [Type]) (i :: Maybe Type) o. AllHave ToHttpApiData p => ClientConfig -> DocumentedEndpoint p q i o -> [Header] -> HVect p -> HVect q -> HVect (MaybeToList i) -> Either ClientError Request
Documentation
Validated configuration and transport. Construct with newClient, or
browserClient from Web.Spock.Api.Client.Browser in JavaScript builds.
data ClientConfig Source #
Request defaults validated by newClient. Start with defaultClientConfig
and change the fields your application needs.
Constructors
| ClientConfig | |
Fields
| |
Instances
| Eq ClientConfig Source # | |
Defined in Web.Spock.Api.Client | |
defaultClientConfig :: ClientConfig Source #
Same-origin URLs and cookies, a 30-second timeout and 1 MiB response limit. The browser transport enforces time and streaming byte limits. Custom transports must implement the timeout; the decoder also checks body size.
data Credentials Source #
Fetch cookie credentials policy. Cross-origin credentials also require server CORS and cookie policies permitting the requesting origin.
Constructors
| SameOrigin | |
| OmitCredentials | |
| IncludeCredentials |
Instances
| Show Credentials Source # | |
Defined in Web.Spock.Api.Client Methods showsPrec :: Int -> Credentials -> ShowS show :: Credentials -> String showList :: [Credentials] -> ShowS | |
| Eq Credentials Source # | |
Defined in Web.Spock.Api.Client | |
data ClientError Source #
Errors omit request headers, URLs, payloads and server response bodies.
Constructors
| InvalidClientConfig | |
| InvalidEndpoint | |
| InvalidRequest | |
| NetworkFailure | |
| RequestTimedOut | |
| ResponseTooLarge | |
| HttpError Int | |
| DecodeFailure |
Instances
| Show ClientError Source # | |
Defined in Web.Spock.Api.Client Methods showsPrec :: Int -> ClientError -> ShowS show :: ClientError -> String showList :: [ClientError] -> ShowS | |
| Eq ClientError Source # | |
Defined in Web.Spock.Api.Client | |
type Header = (Text, Text) Source #
Extra headers are UTF-8 encoded. Typed HeaderParam values use their ToHttpApiData.toHeader encoding. Duplicate names, including case variants, and CR/LF or control bytes are rejected before invoking the transport.
A prepared request. Treat headers/body as sensitive; it has no Show instance.
Constructors
| Request | |
Fields
| |
Raw custom-transport result. HTTP errors are classified before JSON decoding.
type Transport = Request -> IO (Either ClientError Response) Source #
Send a prepared request, returning structured transport failures. Custom implementations must enforce the requested timeout and credential policy.
newClient :: ClientConfig -> Transport -> Either ClientError Client Source #
Validate configuration before any request. Base URLs may be an empty same-origin prefix, an absolute path prefix, or an http(s) URL. Query strings, fragments, embedded credentials, protocol-relative URLs and backslashes are rejected. Cross-origin browser calls still require the server's CORS policy.
callEndpoint :: forall (p :: [Type]) (i :: Maybe Type) o. (HasRep p, HasRep (MaybeToList i), AllHave ToHttpApiData p) => Client -> Endpoint p i o -> HVectElim p (HVectElim (MaybeToList i) (IO (Either ClientError o))) Source #
Arguments follow path capture order, then the JSON body (if present). Any 2xx response must contain JSON matching the endpoint's result type. Non-2xx responses yield HttpError; malformed or empty JSON yields DecodeFailure.
callEndpoint' :: forall (p :: [Type]) (i :: Maybe Type) o. (HasRep p, HasRep (MaybeToList i), AllHave ToHttpApiData p) => Client -> Endpoint p i o -> [Header] -> HVectElim p (HVectElim (MaybeToList i) (IO (Either ClientError o))) Source #
As callEndpoint, with extra headers such as an explicit CSRF token.
callDocumentedEndpoint :: forall (p :: [Type]) (q :: [Type]) (i :: Maybe Type) o. (HasRep p, HasRep q, HasRep (MaybeToList i), AllHave ToHttpApiData p) => Client -> DocumentedEndpoint p q i o -> HVectElim p (HVectElim q (HVectElim (MaybeToList i) (IO (Either ClientError o)))) Source #
Arguments are path captures, declared query/header parameters, then body. Optional parameters are omitted for Nothing; repeated query values preserve order. Encoders are carried by the shared Parameter definitions.
callDocumentedEndpoint' :: forall (p :: [Type]) (q :: [Type]) (i :: Maybe Type) o. (HasRep p, HasRep q, HasRep (MaybeToList i), AllHave ToHttpApiData p) => Client -> DocumentedEndpoint p q i o -> [Header] -> HVectElim p (HVectElim q (HVectElim (MaybeToList i) (IO (Either ClientError o)))) Source #
As callDocumentedEndpoint, with extra per-call headers (for example CSRF).
prepareEndpoint :: forall (p :: [Type]) (i :: Maybe Type) o. AllHave ToHttpApiData p => ClientConfig -> Endpoint p i o -> [Header] -> HVect p -> HVect (MaybeToList i) -> Either ClientError Request Source #
Prepare an encoded request without sending it; useful with custom transports.
prepareDocumentedEndpoint :: forall (p :: [Type]) (q :: [Type]) (i :: Maybe Type) o. AllHave ToHttpApiData p => ClientConfig -> DocumentedEndpoint p q i o -> [Header] -> HVect p -> HVect q -> HVect (MaybeToList i) -> Either ClientError Request Source #
Validate endpoint metadata and encode typed pathqueryheader/body values without sending a request. Arguments follow the shared declaration's order.