Backend: WebClient with required HTTP/2 and client certificates (#5990)

docs/demos/backend/src/main/java/com/codenameone/developerguide/backend/PartnerApi.java

@@ -0,0 +1,61 @@
+/*
+ * Copyright (c) 2012, Codename One and/or its affiliates. All rights reserved.
+ * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
+ * This code is free software; you can redistribute it and/or modify it
+ * under the terms of the GNU General Public License version 2 only, as
+ * published by the Free Software Foundation.  Codename One designates this
+ * particular file as subject to the "Classpath" exception as provided
+ * by Oracle in the LICENSE file that accompanied this code.
+ *
+ * This code is distributed in the hope that it will be useful, but WITHOUT
+ * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
+ * FITNESS FOR A PARTICULAR PURPOSE.  See the GNU General Public License
+ * version 2 for more details (a copy is included in the LICENSE file that
+ * accompanied this code).
+ *
+ * You should have received a copy of the GNU General Public License version
+ * 2 along with this work; if not, write to the Free Software Foundation,
+ * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA.
+ *
+ * Please contact Codename One through http://www.codenameone.com/ if you
+ * need additional information or have any questions.
+ */
+package com.codenameone.developerguide.backend;
+
+import com.codename1.backend.Base64;
+import com.codename1.backend.ClientCertificate;
+import com.codename1.backend.Web;
+import com.codename1.backend.WebClient;
+import com.codename1.backend.annotations.Component;
+import com.codename1.backend.annotations.Value;
+import java.io.IOException;
+
+/**
+ * Calls a partner API that authenticates its clients with a certificate.
+ * Referenced from the backend chapter's section on calling other services.
+ */
+@Component
+public class PartnerApi {
+    // tag::backend-web-client[]
+    private final WebClient partner;
+
+    /** The PKCS#12 archive and its password, from configuration. */
+    public PartnerApi(@Value("${partner.p12}") String p12Base64,
+                      @Value("${partner.p12Password}") String password) {
+        byte[] archive = Base64.decode(p12Base64);
+        this.partner = new WebClient()
+                .setClientCertificate(ClientCertificate.pkcs12(archive, password))
+                .setRequireHttp2(true)
+                .setRequestTimeoutMillis(10000);
+    }
+
+    public String balance(String account) throws IOException {
+        Web.Result result = partner.getJson(
+                "https://api.partner.example/v1/accounts/" + account, null);
+        if (!result.isSuccess()) {
+            throw new IOException("The partner API answered " + result.getStatus());
+        }
+        return result.getBodyAsString();
+    }
+    // end::backend-web-client[]
+}

docs/developer-guide/Backend-Web.asciidoc

@@ -727,6 +727,48 @@ Sections 12 and 13 are excluded while permessage-deflate is unimplemented. They'
 excluded rather than tolerated: accepting their result as a pass would also accept
 it for a case that used to work.
 
+[[backend-web-client]]
+=== Calling other services
+
+`Web` makes an outbound HTTP or HTTPS request: `Web.get`, `Web.getJson`,
+`Web.postJson` and `Web.request`. The server's certificate and its host name are
+always verified, and there is no option to turn that off. A `WebClient` is the
+same request with settings of its own:
+
+* a client certificate, for a service that authenticates its callers with mutual
+  TLS. `ClientCertificate.pem` takes a PEM certificate and key, and
+  `ClientCertificate.pkcs12` takes a `.p12` archive and its password.
+* `setRequireHttp2(true)`, which makes the request over HTTP/2 or fails it. A
+  server that only speaks HTTP/1.1 never receives the request.
+* a connect timeout, a read timeout (how long the transfer may stall) and a
+  request timeout (the whole request).
+* a pool of connections, so the next request to the same server skips the TCP
+  and TLS handshakes. `setReuseConnections(false)` opens a new connection for
+  each request.
+
+[source,java]
+----
+include::../demos/backend/src/main/java/com/codenameone/developerguide/backend/PartnerApi.java[tag=backend-web-client,indent=0]
+----
+
+Create a client once and share it between requests. Its settings are fixed by its
+first request, and two clients never share a connection, so a connection
+authenticated with one certificate is never used for a request made with another.
+`close()` releases the pool.
+
+`Web.Result.getProtocol()` names the protocol the response used. Without the
+requirement, the packaged server offers HTTP/2 and uses HTTP/1.1 when the other
+side declines.
+
+The local Java SE runtime speaks HTTP/1.1 only, so there a client that requires
+HTTP/2 fails every request with an exception that says so. It reads PKCS#12
+archives, and PEM keys in unencrypted PKCS#8 or RSA form. The packaged server also
+reads encrypted PEM keys. A PKCS#12 archive works the same in both.
+
+A static binary in a `scratch` image has no certificate store. Copy a
+`ca-certificates.crt` into the image and name it in `CURL_CA_BUNDLE` or
+`SSL_CERT_FILE`.
+
 [[backend-push]]
 === Sending push notifications