Protocols

The HttpBody protocol ought to be implemented by any entity that can attach data to the body of an HTTP request. Any entities implementing this protocol should be scoped in an extension of the HttpData enum.

The paginated data protocol defines a common interface for result types of paginated requests. The properties of the protocol can be leveraged to enable handling paginated requests automatically by observing the provided properties.

The network request is a protocol that serves as a base protocol for requests on remote servers. The protocol is mainly used as a common base for Request and StreamRequest. You should never directly use this protocol as it hardly provides any functionality.

The request protocol is the core building block of the Squid framework. The general idea of a request is that it declaratively defines the content of an HTTP request. It is then scheduled against an API that is represented by a HttpService. Scheduling the request returns a Response. This response is a shared publisher that can be subscribed to.

The reason for abstracting requests away from APIs, i.e. HTTP services, is that often, requests are issued against differing domains with differing security requirements during testing/staging and development. Hence, it makes sense to capture methods, routing paths, headers, etc. in the request itself but abstract away the actual URL and common API headers into the HttpService.

This request protocol is a specialization of the Request protocol. It can be used often when working with a JSON API where the returned data is a JSON object. As a requirement, the request’s result type must implement the Decodable protocol. The decode(_:) method is then synthesized automatically by using a JSONDecoder and decoding the raw data to the specified type. decodeSnakeCase can further be used to modify the behavior of the aforementioned decoder.

A retrier represents a “callback” that is executed whenever a request fails. One option for a retrier is to retry a failed request only once. An example might be a retrier that refreshes an authentication token when the server returns a 401 status code. Another option for the retrier is to retry multiple times. A common example might be a retrier that “backs off” exponentially long to ensure that a request is fulfilled at some time.

A retrier factory is a simple class that creates retriers for failed requests on demand. The reason for using the factory is to allow for stateful retriers. As they cannot easily be shared across requests, each request requires its own instance of the retrier. Consequently, any entity implementing the HttpService protocol needs to provide a retrier factory yielding retriers instead of a retrier instance.

When using your own retriers, you will most likely use the same retrier no matter the request. In this case, you do not have to define a type implementing this protocol, but have a look at AnyRetrierFactory instead.

A service hook represents a component that is called at specific events during the processing of a request. A service hook can be attached to a service to e.g. provide caching behavior.

An HTTP service can be used to abstract a specific endpoint away from specific requests. Usually, you would have one HTTP service per API that you use and possibly different services for testing/staging and production. Intuitively, a specific implementation of an HTTP service represents a particular API.

A request for a steram is similar to a Request, only that it does not send an HTTP request, but asks for a web socket. Instead of a Response that yields at most one value, it therefore returns a Stream which allows for receiving arbitrarily many values as well as sending values. Apart from that, working with a stream request is very similar to working with an HTTP request. It is also scheduled against an API represented by an HttpService. However, the service’s retriers as well as its headers are ignored. Still, the Service.process(_:) method is called.

Similarly to the JsonRequest, this entity may be used whenever a JSON API is used, i.e. all messages being received and being sent are encoded as JSON. This requires messages to conform to the Encodable protocol as well as responses to conform to the Decodable protocol.

This entity then provides default implementations for encoding and decoding messages. Note that messages are always encoded to Data for a more efficient transmission. Messages received can be either String or Data: in both cases, they are decoded equally (note that Data messages might be more efficient.

Any entity implementing this protocol declares that it is able to possibly represent itself as a url. The conversion to this url may fail, however.