http
« Previous section Next section »
UCloud Developer Guide / Developing UCloud / Micro Library Reference / HTTP
HTTP
In this article we will cover the HTTP server and client implementation details of UCloud. Both the server and client implementations are both provided by Ktor. Before you read this article, you should read about the general server and client systems. The client/server is used, only, if the RPC call has the http block attached to it. Additionally, the client will only be used if it is using the OutgoingHttpCall
backend.
Server
Almost all ktor server code in use by UCloud is placed in the dk.sdu.cloud.calls.server.IngoingHttpInterceptor
class. A Ktor engine is prepared by the KtorServerProviderFeature, this engine is passed to the IngoingHttpInterceptor
. This class performs the following tasks, according to the semantics defined by the http block.
Register a call handler with Ktor
Parsing the request
Producing the response
Register a call handler with Ktor
A call handler is registered with Ktor in IngoingHttpInterceptor.addCallListenerForCall
, which is called in response to anRpcServer.implement
invocation. The function immediately checks if an http block is attached, if not it will silently do nothing.
From here a handler is registered with Ktor in the ordinary way:
Parsing the request
The request object is parsed from the HTTP request using the semantics provided in the http block. Ktor is used only to read the raw request information, we do not rely on the built-in parsing mechanisms. You can read more about serialization/deserialization here.
Producing the response
Once the CallHandler
has run the IngoingHttpInterceptor
receives the response (success/error) from the RpcServer
. The IngoingHttpInterceptor
makes the corresponding calls to the Ktor server to write the response. For most calls, which do not implement the HttpServerConverter.OutgoingBody
(see below), the standard serialization mechanisms are used. We do not rely on the built-in mechanisms of Ktor.
Custom converters
It is possible to override the default serialization/deserialization mechanisms of UCloud, in favor of something made specifically for the HTTP backend. To do this you must implement one of the HttpServerConverter
interfaces.
Table: Commonly used types with custom converters (part of service-lib
)
Name | Description |
---|---|
| Provides streaming content. This implements both the ingoing direction and outgoing direction for both the client and server component |
Examples
Example: A custom object implementing a deserializer
Example: A custom object implementing the serializer
interface HttpServerConverter.IngoingPath<T : Any>
UCloud will invoke the IngoingPath
interface if the value being deserialized is bound in the path
section of an http block.
interface HttpServerConverter.IngoingQuery<T : Any>
UCloud will invoke the IngoingQuery
interface if the value being deserialized is bound in the params
section of an http block. Both the name
and the value
of the parameter will be supplied.
interface HttpServerConverter.IngoingBody<T : Any>
UCloud will invoke the IngoingBody
interface if the value being deserialized is bound in the body
section of an http block.
interface HttpServerConverter.IngoingHeader<T : Any>
UCloud will invoke the IngoingHeader
interface if the value being deserialized is bound in the headers
section of an http block.
interface HttpServerConverter.OutgoingBody
UCloud will invoke the OutgoingBody
interface if the value being produced as either a success or error type.
Client
The client is implemented in a way, very similar to the server. The client uses the http block to determine how the request should be serialized and how the response should be deserialized. Exactly like the server, the HTTP client will delegate this work to the serialization component. It is possible to override this behavior by implementing one of the interfaces in HttpClientConverter
.
Custom converters
interface HttpClientConverter.OutgoingPath
UCloud will invoke the OutgoingPath
interface if the value being serialized is bound in the path
section of an http block.
interface HttpClientConverter.OutgoingQuery
UCloud will invoke the OutgoingQuery
interface if the value being serialized is bound in the params
section of an http block.
interface HttpClientConverter.OutgoingBody
UCloud will invoke the OutgoingBody
interface if the value being serialized is bound in the body
section of an http block.
interface HttpClientConverter.OutgoingHeader
UCloud will invoke the OutgoingHeader
interface if the value being serialized is bound in the headers
section of an http block. This will not base64 decode the header.
interface HttpClientConverter.OutgoingCustomHeaders
UCloud will invoke the OutgoingCustomHeaders
interface if the value being serialized is bound in the headers
section of an http block. This will base64 decode the header.
interface HttpClientConverter.IngoingBody<T : Any>
UCloud will invoke the IngoingBody
interface if the value being deserialized as either a success or error type.
Last updated