Merge pull request #121 from talex5/docs

Update docs

CHANGES.md

@@ -1,3 +1,87 @@
+### 0.2 Persistence, encryption and access control
+
+This release brings support for RPC Level 2.
+
+The API for implementing services and clients is mostly unchanged,
+but the APIs for setting up networking are very different.
+If you read the tutorial with the 0.1 release, you will probably
+want to read the new version again from the "Networking" point
+onwards.
+
+The main change is that when connecting to a service you now give a URI of the form:
+
+`capnp://hash:digest@address/service`
+
+The client will connect to `address`, check the server's public key matches `hash:digest`,
+and then pass the (secret) `service` ID to get access to a particular service.
+The server will typically display the URI to use on start-up, or write it to a file.
+
+The communications are encrypted using TLS.
+If you want to disable TLS, use the form `capnp://insecure@address`.
+This should only be needed for interoperability with non-TLS services,
+as the system will generate keys and certificates automatically,
+making secure use just as easy as the non-secure case.
+
+The other major new feature is support for persistent services.
+In version 0.1 you could specify an `offer` argument when creating a vat,
+telling it a service to provide in response to bootstrap requests.
+Now, you pass a `restore` argument, which can restore different services
+depending on the service ID provided by the client.
+
+The new `Restorer.Table` module provides a table-based lookup restorer,
+to which services can be added dynamically.
+If you have a lot of services and don't want to add them all at startup,
+you can use `Restorer.Table.of_loader` and provide your own function for loading services.
+
+#### Other changes
+
+Documentation changes:
+
+- The tutorial has been extended and a FAQ added.
+
+- The recommended layout of protocol files has changed.
+  The `Client` sub-module is gone, and `service` becomes `local`.
+
+- The examples now have `.mli` files and there is a new `store.ml` example demonstrating persistence.
+  The examples have been updated to the new layout convention.
+
+Main API changes:
+
+- The `Capnp_rpc_lwt.Capability` module adds some useful functions:
+  - `broken` creates a broken capability.
+  - `when_broken` allows you to be notified when a capability breaks (e.g. because of a network failure).
+  - `wait_until_settled` waits until a promise has resolved, if you don't want to pipeline (e.g. you want to send a large amount of data, so prefer to find out where the service is and avoid any forwarding).
+  - `equal` tests if two capabilities designate the same service.
+
+- The new `Capnp_rpc_lwt.Sturdy_ref` module provides an abstraction for off-line capabilities.
+  `Sturdy_ref.connect` can be used to get a live connection.
+  If you try to connect to multiple services in the same vat, it will share a single connection automatically.
+  `Sturdy_ref.reader` and `Sturdy_ref.builder` can be used for passing sturdy refs in messages.
+
+- The new `Capnp_rpc_lwt.Restorer` module is used to implement sturdy-refs at the hosting side.
+
+- The new `Capnp_rpc_lwt.Persistence` module provides support for the Cap'n Proto persistence protocol.
+  Clients use `Persistence.save` to request a sturdy ref from a service, and
+  services can use `Persistence.with_sturdy_ref` to answer such requests automatically.
+
+- The new `Capnp_rpc_unix.Vat_config` collects together all vat configuration in one place.
+
+- The new `Capnp_rpc_unix.File_store` can store Cap'n Proto structs in a directory.
+  It can be useful when implementing persistence.
+
+- The new `Capnp_rpc_lwt.Auth` module provides support for generating and handling secret keys and fingerprints.
+
+- The new `Capnp_rpc_lwt.Tls_wrapper` provides support for doing TLS handshakes, with authentication and encryption.
+
+In the core `capnp-rpc` package (which applications do not normally use directly):
+
+- The new `cap#when_released` method can be used to find out when a capability is no longer needed.
+  The restorer uses this to remove dynamically loaded services from its table automatically.
+
+- The new `when_broken` helper adds a callback to call when a promise or far-ref becomes broken.
+
+- `NETWORK_TYPES` is now separate from `CORE_TYPES`.
+
 ### 0.1
 
-- Initial release.
+- Initial release. RPC Level 1 is fully implemented.

Dockerfile

@@ -3,9 +3,9 @@ FROM ocaml/opam@sha256:5e8ebc171a90fb62209e67dcaeedafd02018bc43ebc1e3074a5d03f97
 RUN cd opam-repository && git fetch && git reset --hard 3cad9b6baa95451f294008d0b791c2b0d54b0968 && opam update
 ADD *.opam /home/opam/capnp-rpc/
 WORKDIR /home/opam/capnp-rpc/
-RUN opam pin add -ny capnp-rpc . && \
-    opam pin add -ny capnp-rpc-lwt . && \
-    opam pin add -ny capnp-rpc-unix . && \
+RUN opam pin add -ny capnp-rpc.dev . && \
+    opam pin add -ny capnp-rpc-lwt.dev . && \
+    opam pin add -ny capnp-rpc-unix.dev . && \
     opam depext capnp-rpc-unix
 RUN opam install capnp-rpc-unix alcotest afl-persistent
 ADD . /home/opam/capnp-rpc