This module is not meant to be used directly. You should include an Adapter implementing this
feature (as http_client_ahc) in order to create HTTP clients.
You create an HTTP Client instance with default options as follows:
1234567
// Adapter injectedClient()// No base endpoint, whole URL must be passed each requestClient("http://host:1234/base")// Requests' paths will be appended to supplied base URL// Adapter provided explicitlyClient(adapter)Client(adapter,"http://host:1234/base")
If you want to configure options for the client, you can create it with the following code:
1 2 3 4 5 6 7 8 910
// All client settings parameters are optionals and provide default valuesClient("http://host:1234/base",ClientSettings(contentType="application/json",useCookies=true,headers=mapOf("X-Api-Key"tolistOf("cafebabe")),// Headers to use in all requestsuser="user",// HTTP Basic auth userpassword="password",// HTTP Basic auth passwordinsecure=false,// If true, the client doesn't check server certificatessslSettings=SslSettings()// Key stores settings (check TLS section for details)))
The most common use case is to send a request and get a response. For details about how to
use requests and responses, refer to the Request and the Response API.
Check this code snippet to get a glimpse on how to send the most general requests:
The HTTP client support setting cookies from client side and updates them after any server request.
Check the details in the following code fragment:
1 2 3 4 5 6 7 8 9101112
valcookieName="sampleCookie"valcookieValue="sampleCookieValue"// Set the cookie in the clientclient.cookies["sampleCookie"]=Cookie(cookieName,cookieValue)// Assert that it is received in the server and change its value afterwardsclient.post("/assertHasCookie?cookieName=$cookieName")client.post("/addCookie?cookieName=$cookieName&cookieValue=${cookieValue}_changed")// Verify that the client cookie is updatedassert(client.cookies[cookieName]?.value==cookieValue+"_changed")
You can also check the full test for more details.
The HTTP client supports server certificates (to use HTTPS and HTTP/2) and also client certificates
(to be able to do mutual TLS). Key stores may have the JKS format (deprecated), or the newer PKCS12
format.
To set up client/server certificates, you need to include SslSettings in your ClientSettings. In
the sections below you can see how to configure these parameters.
This store holds the identity certificate, this certificate is presented to the server by the client
in the handshake for the server to authorize or deny the connection. The following code:
This key store should include all the trusted certificates. Any certificate added as CA (certificate
authority) makes the client trust any other certificate signed by them. However, you can also add
standalone server certificates.
If you set up the identity (service's own certificate) and the trust store (CAs and servers trusted
by the client), you will achieve double ended authentication (server authenticated by the client,
and client authenticated by the server). You can see a complete example below:
// Key store filesvalidentity="hexagonkt.p12"valtrust="trust.p12"// Default passwords are file name reversedvalkeyStorePassword=identity.reversed()valtrustStorePassword=trust.reversed()// Key stores can be set as URIs to classpath resources (the triple slash is needed)valkeyStore=URL("classpath:ssl/$identity")valtrustStore=URL("classpath:ssl/$trust")valsslSettings=SslSettings(keyStore=keyStore,keyStorePassword=keyStorePassword,trustStore=trustStore,trustStorePassword=trustStorePassword,clientAuth=true// Requires a valid certificate from the client (mutual TLS))valserverSettings=ServerSettings(bindPort=0,protocol=HTTPS,// You can also use HTTP2sslSettings=sslSettings)valserver=serve(serverSettings,serverAdapter){get("/hello"){// We can access the certificate used by the client from the requestvalsubjectDn=request.certificate?.subjectDN?.nameresponse.headers["cert"]=subjectDnok("Hello World!")}}// We'll use the same certificate for the client (in a real scenario it would be different)valclientSettings=ClientSettings(sslSettings=sslSettings)// Create a HTTP client and make a HTTPS requestvalclient=Client(AhcAdapter(),"https://localhost:${server.runtimePort}",clientSettings)client.get("/hello").apply{logger.debug{body}// Assure the certificate received (and returned) by the server is correctassert(headers.require("cert").first().startsWith("CN=hexagonkt.com"))assert(body=="Hello World!")}