Improve documentation and add more examples. (#152)

Author: floitsch

examples/client-get-tls.toit

@@ -0,0 +1,18 @@
+// Copyright (C) 2025 Toitware ApS.
+// Use of this source code is governed by a Zero-Clause BSD license that can
+// be found in the EXAMPLES_LICENSE file.
+
+import certificate-roots
+import http
+import net
+
+main:
+  certificate-roots.install-all-trusted-roots
+
+  network := net.open
+  client := http.Client network
+  response := client.get --uri="https://www.example.com"
+  while data := response.body.read:
+    print data.to-string
+
+  client.close

examples/package.lock

@@ -1,4 +1,4 @@
-sdk: ^2.0.0-alpha.91
+sdk: ^2.0.0-alpha.150
 prefixes:
   certificate_roots: toit-cert-roots
   http: ..
@@ -7,6 +7,6 @@ packages:
     path: ..
   toit-cert-roots:
     url: github.com/toitware/toit-cert-roots
-    name: certificate_roots
-    version: 1.6.1
-    hash: 55d3be82ed53d8d332338b2de931865cf69fe48b
+    name: certificate-roots
+    version: 1.9.0
+    hash: 1445c4a6cae47689674ae02c5f1dc03660f1df8c

examples/package.yaml

@@ -1,6 +1,6 @@
 dependencies:
   certificate_roots:
     url: github.com/toitware/toit-cert-roots
-    version: ^1.6.1
+    version: ^1.9.0
   http:
     path: ..

examples/tls-resume.toit

@@ -0,0 +1,60 @@
+// Copyright (C) 2025 Toitware ApS.
+// Use of this source code is governed by a Zero-Clause BSD license that can
+// be found in the EXAMPLES_LICENSE file.
+
+import certificate-roots
+import http
+import net
+import system
+import system.storage
+
+/**
+An example demonstrating the use of the SecurityStore to cache TLS
+  session state data in RTC memory.
+
+This example is intended to be run on an ESP32.
+*/
+
+/**
+A security store that saves the TLS session state in RTC memory.
+
+*/
+class SecurityStoreRtc extends http.SecurityStore:
+  // We store the cached session data in RTC memory. This means that
+  // it survives deep sleeps, but that any loss of power or firmware
+  // update will clear it.
+  bucket_/storage.Bucket
+
+  constructor path/string:
+    bucket_ = storage.Bucket.open --ram path
+
+  store-session-data host/string port/int data/ByteArray -> none:
+    bucket_[key_ host port] = data
+
+  delete-session-data host/string port/int -> none:
+    bucket_.remove (key_ host port)
+
+  retrieve-session-data host/string port/int -> ByteArray?:
+    return bucket_.get (key_ host port)
+
+  key_ host/string port/int -> string:
+    return "$host:$port"
+
+main:
+  // Install common trusted roots.
+  certificate-roots.install-common-trusted-roots
+  network := net.open
+
+  security-store := SecurityStoreRtc "toitlang.org/pkg-http/example/tls-session-store"
+  client := http.Client.tls network
+      --security-store=security-store
+
+  response := null
+  duration := Duration.of:
+    response = client.get --uri="https://www.example.com"
+  // Running this program a second time should be faster, as the TLS
+  // connection could just be resumed.
+  print "Took $duration to get response."
+
+  client.close
+  network.close

src/client.toit

@@ -18,28 +18,12 @@ import .status-codes
 import .web-socket
 
 /**
-An HTTP v1.1 client.
-
-This class provides methods to fetch data from HTTP servers.
-
-When the client is no longer needed, resources should be freed up with the
-  $close method.  This is an API incompatibility with version one of the
-  package, which would automatically close the client after one request.
-  See the documentation of the constructor for details.
-
-This client has built-in websocket support.  The separate websockets package
-  should no longer be used.
-
-The client caches connections to servers, so a second request to the same
-  server will use the same socket and may save a lot of CPU time for setting
-  up TLS connections.  It also caches session state for TLS connections, so
-  subsequent connections to a server will use the session state to speed up
-  the TLS handshake from about 1000ms to about 150ms (on ESP32).
+HTTP Client.
 
 # Get
-Use the $get method to fetch data using a $GET request.
+Use the $Client.get method to fetch data using a $GET request.
 
-The $get method keeps track of the underlying resources and is thus
+The $Client.get method keeps track of the underlying resources and is thus
   very easy to use.
 
 Example that takes the incoming data and reads it as JSON:
@@ -53,7 +37,7 @@ PATH ::= "/get"
 
 main:
   network := net.open
-  client := null
+  client/http.Client := null
   try:
     client = http.Client network
     response := client.get URI PATH
@@ -62,24 +46,53 @@ main:
     if client: client.close
 ```
 
-For https connection use the $Client.tls constructor with the certificate of
-  the server:
-```
-  client := http.Client.tls network
-      --root_certificates=[CERTIFICATE]
-```
-The certificate is server dependendent, and must be obtained before-hand.
-Most commonly one uses a combination of inspecting the certificate in Google Chrome,
-  and the package `certificate_roots`:
-  https://pkg.toit.io/package/github.com%2Ftoitware%2Ftoit-cert-roots
+For https connections either use the $Client.tls constructor or provide
+  a uri with the https scheme. You need to make sure that the server's
+  root certificate is installed or provided in the root-certificates list.
+  For public root certificates see the `certificate_roots` package.
+
+On embedded devices we recommend to provide a $SecurityStore if the server
+  supports TLS resume. See the tls-resume.toit example.
 
-For example, the `httpbin.org` server uses the `AMAZON_ROOT_CA_1` certificate:
 ```
-import certificate_roots
+import certificate-roots
+import http
+import net
 
-CERTIFICATE ::= certificate_roots.AMAZON_ROOT_CA_1
+URI ::= "https://www.example.com"
+
+main:
+  certificate-roots.install-common-trusted-roots
+  network := net.open
+  // On embedded devices consider providing a SecurityStore to speed up
+  // subsequent connections to the same server.
+  client := http.Client network
+  response := client.get --uri=URI
+  while data := response.body.read:
+    print data.to-string
+  client.close
 ```
 */
+
+/**
+An HTTP v1.1 client.
+
+This class provides methods to fetch data from HTTP servers.
+
+When the client is no longer needed, resources should be freed up with the
+  $close method.  This is an API incompatibility with version one of the
+  package, which would automatically close the client after one request.
+  See the documentation of the constructor for details.
+
+This client has built-in websocket support.  The separate websockets package
+  should no longer be used.
+
+The client caches connections to servers, so a second request to the same
+  server will use the same socket and may save a lot of CPU time for setting
+  up TLS connections.  It also caches session state for TLS connections, so
+  subsequent connections to a server will use the session state to speed up
+  the TLS handshake from about 1000ms to about 150ms (on ESP32).
+*/
 class Client:
   /**
   The maximum number of redirects to follow if 'follow_redirect' is true for $get and $post requests.
@@ -96,39 +109,53 @@ class Client:
   security-store_/SecurityStore
 
   /**
-  Constructs a new client instance over the given interface.
+  Constructs a new client instance over the given $network.
+
+  Use `net.open` to obtain an $network.
+
+  Clients that connect to secure servers may provide a $security-store.  This
+    is used to store session state for TLS connections, which can speed up
+    the TLS handshake from about 1000ms to about 150ms (on ESP32). The
+    handshake then also uses less memory.
+
+  The $root-certificates parameter is nowadays mostly unused, as the
+    recommended way to provide root certificates is to `install` them
+    instead.
+
   The client will default to an insecure HTTP connection, but this can be
-    overridden by a redirect or a URI specifying a secure scheme.
-  Therefore it can be meaningful to provide certificate roots despite the
+    overridden by a redirect or a URI specifying a secure scheme. Therefore
+    it can be meaningful to provide certificate roots despite the
     insecure default.
-  If the client is used for secure connections, the $root-certificates must
-    contain the root certificate of the server.
+
+  If the client is used for secure connections, its root certificate must
+    be installed or provided in the $root-certificates list.
+
   A client will try to keep a connection open to the last server it
     contacted, in the hope that the next request will connect to the same
     server.  This can save a lot of CPU time for TLS connections which are
     expensive to set up, but it also reserves a fairly large amount of
     buffer memory for the TLS connection.  Call $close (perhaps in a finally
     clause) to release the connection.
+
   See the `certificate_roots` package for common roots:
     https://pkg.toit.io/package/github.com%2Ftoitware%2Ftoit-cert-roots
-  Use `net.open` to obtain an interface.
   */
-  constructor .interface_
+  constructor network/tcp.Interface
       --root-certificates/List=[]
       --security-store/SecurityStore=SecurityStoreInMemory:
+    interface_ = network
     security-store_ = security-store
     root-certificates_ = root-certificates
     add-finalizer this:: this.finalize_
 
   /**
-  Constructs a new client.
-  The client will default to a secure HTTPS connection, but this can be
-    overridden by a redirect or a URI specifying an insecure scheme.
-  The $root-certificates must contain the root certificate of the server.
-  See the `certificate_roots` package for common roots:
-    https://pkg.toit.io/package/github.com%2Ftoitware%2Ftoit-cert-roots
+  Variant of $constructor.
+
+  Constructs a client that defaults to a secure HTTPS connection.
+
   A client $certificate can be specified for the rare case where the client
     authenticates itself.
+
   The $server-name can be specified for verifying the TLS certificate.  This is
     for the rare case where we wish to verify the TLS connections with a
     different server name from the one used to establish the connection.

src/server.toit

@@ -18,7 +18,7 @@ import .status-codes
 import .web-socket
 
 /**
-An HTTP server.
+HTTP server.
 
 # Examples
 ```
@@ -54,6 +54,10 @@ main:
     writer.close
 ```
 */
+
+/**
+An HTTP server.
+*/
 class Server:
   static DEFAULT-READ-TIMEOUT/Duration ::= Duration --s=30
 
@@ -68,10 +72,22 @@ class Server:
   // For testing.
   call-in-finalizer_/Lambda? := null
 
+  /**
+  Constructs an HTTP server with the given $read-timeout and $max-tasks.
+
+  The $max-tasks argument must be tuned to the expected load. More tasks consume
+    more memory, but can handle more requests concurrently. If the value is not
+    big enough, then browsers will time out when they try to connect to the server.
+  */
   constructor --.read-timeout=DEFAULT-READ-TIMEOUT --max-tasks/int=1 --logger=log.default:
     logger_ = logger
     if max-tasks > 1: semaphore_ = monitor.Semaphore --count=max-tasks
 
+  /**
+  Variant of $constructor.
+
+  This variant sets up the server to use TLS with the given $certificate.
+  */
   constructor.tls
       --.read-timeout=DEFAULT-READ-TIMEOUT
       --max-tasks/int=1
@@ -111,7 +127,7 @@ class Server:
     // Listen on a free port.
     tcp_socket := network.tcp_listen 0
     print "Server on http://localhost:$tcp_socket.local_address.port/"
-    server := http.Server
+    server := http.Server --max-tasks=5
     server.listen tcp_socket:: | request/http.Request writer/http.ResponseWriter |
       if request.path == "/":
         writer.headers.set "Content-Type" "text/html"