From 80c47044e57b7c21651108b8bb78c9beed976413 Mon Sep 17 00:00:00 2001 From: Simon Cruanes Date: Sat, 7 Mar 2020 12:27:07 -0600 Subject: [PATCH] add a sync version of capnp-rpc --- capnp-rpc-sync.opam | 31 + capnp-rpc-sync/capability.ml | 116 +++ capnp-rpc-sync/capnp_core.ml | 18 + capnp-rpc-sync/capnp_rpc_sync.ml | 74 ++ capnp-rpc-sync/capnp_rpc_sync.mli | 320 +++++++ capnp-rpc-sync/dune | 17 + capnp-rpc-sync/msg.ml | 126 +++ capnp-rpc-sync/msg.mli | 44 + capnp-rpc-sync/persistence.ml | 63 ++ capnp-rpc-sync/persistent.capnp | 109 +++ capnp-rpc-sync/private.ml | 7 + capnp-rpc-sync/request.ml | 32 + capnp-rpc-sync/request.mli | 8 + capnp-rpc-sync/response.ml | 30 + capnp-rpc-sync/rpc_schema.capnp | 1404 +++++++++++++++++++++++++++++ capnp-rpc-sync/schema.ml | 23 + capnp-rpc-sync/service.ml | 91 ++ capnp-rpc-sync/sturdy_ref.ml | 22 + capnp-rpc-sync/utils.ml | 62 ++ capnp-rpc-sync/xform.ml | 22 + capnp-rpc-sync/xform.mli | 8 + 21 files changed, 2627 insertions(+) create mode 100644 capnp-rpc-sync.opam create mode 100644 capnp-rpc-sync/capability.ml create mode 100644 capnp-rpc-sync/capnp_core.ml create mode 100644 capnp-rpc-sync/capnp_rpc_sync.ml create mode 100644 capnp-rpc-sync/capnp_rpc_sync.mli create mode 100644 capnp-rpc-sync/dune create mode 100644 capnp-rpc-sync/msg.ml create mode 100644 capnp-rpc-sync/msg.mli create mode 100644 capnp-rpc-sync/persistence.ml create mode 100644 capnp-rpc-sync/persistent.capnp create mode 100644 capnp-rpc-sync/private.ml create mode 100644 capnp-rpc-sync/request.ml create mode 100644 capnp-rpc-sync/request.mli create mode 100644 capnp-rpc-sync/response.ml create mode 100644 capnp-rpc-sync/rpc_schema.capnp create mode 100644 capnp-rpc-sync/schema.ml create mode 100644 capnp-rpc-sync/service.ml create mode 100644 capnp-rpc-sync/sturdy_ref.ml create mode 100644 capnp-rpc-sync/utils.ml create mode 100644 capnp-rpc-sync/xform.ml create mode 100644 capnp-rpc-sync/xform.mli diff --git a/capnp-rpc-sync.opam b/capnp-rpc-sync.opam new file mode 100644 index 000000000..4e8d9a8ac --- /dev/null +++ b/capnp-rpc-sync.opam @@ -0,0 +1,31 @@ +opam-version: "2.0" +synopsis: + "Cap'n Proto is a capability-based RPC system with bindings for many languages" +description: """ +This package provides a version of the Cap'n Proto RPC system using the Cap'n +Proto serialisation format and Unix for the IO""" +maintainer: "Thomas Leonard " +authors: "Thomas Leonard " +license: "Apache" +homepage: "https://github.com/mirage/capnp-rpc" +bug-reports: "https://github.com/mirage/capnp-rpc/issues" +doc: "https://mirage.github.io/capnp-rpc/" +depends: [ + "ocaml" {>= "4.03.0"} + "conf-capnproto" {build} + "capnp" {>= "3.4.0"} + "capnp-rpc" {= version} + "base-unix" + "astring" + "fmt" + "logs" + "asetmap" + "containers" + "uri" {>= "1.6.0"} + "dune" {>= "1.0"} +] +build: [ + ["dune" "build" "-p" name "-j" jobs] + ["dune" "runtest" "-p" name "-j" jobs] {with-test} +] +dev-repo: "git+https://github.com/mirage/capnp-rpc.git" diff --git a/capnp-rpc-sync/capability.ml b/capnp-rpc-sync/capability.ml new file mode 100644 index 000000000..a48871b21 --- /dev/null +++ b/capnp-rpc-sync/capability.ml @@ -0,0 +1,116 @@ +open Capnp_core +open Utils + +module Log = Capnp_rpc.Debug.Log +module StructStorage = Capnp.BytesMessage.StructStorage + +type 'a t = Core_types.cap +type 'a capability_t = 'a t +type ('t, 'a, 'b) method_t = ('t, 'a, 'b) Capnp.RPC.MethodID.t + +module Request = Request + +let inc_ref = Core_types.inc_ref +let dec_ref = Core_types.dec_ref + +let with_ref t fn = + CCFun.finally1 ~h:(fun () -> dec_ref t) fn t + +let pp f x = x#pp f + +let broken = Core_types.broken_cap +let when_broken = Core_types.when_broken +let when_released (x:Core_types.cap) f = x#when_released f +let problem x = x#problem + +let wait_until_settled (x:'a t) : 'a Fut.t = + let sync = SyncPoint.create () in + let result = Fut.make (fun () -> SyncPoint.wait sync) in + (* watch for unblocking *) + let rec aux x = + if x#blocker = None then ( + () (* done *) + ) else ( + x#when_more_resolved + (fun x -> Core_types.dec_ref x; aux x) + ) + in + aux x; + result + +let equal a b = + match a#blocker, b#blocker with + | None, None -> + let a = a#shortest in + let b = b#shortest in + begin match a#problem, b#problem with + | None, None -> Ok (a = b) + | Some a, Some b -> Ok (a = b) + | _ -> Ok false + end + | _ -> Error `Unsettled + +let call (target : 't capability_t) (m : ('t, 'a, 'b) method_t) + (req : 'a Request.t) : Core_types.struct_ref = + Log.info (fun f -> f "Calling %a" Capnp.RPC.MethodID.pp m); + let msg = Request.finish m req in + let results, resolver = Local_struct_promise.make () in + target#call resolver msg; + results + +let call_and_wait cap (m : ('t, 'a, 'b StructStorage.reader_t) method_t) req : _ result = + let mvar, resolve = MVar.create () in + let result = call cap m req in + let finish = lazy (Core_types.dec_ref result) in + result#when_resolved (function + | Error e -> + Lazy.force finish; + resolve (Error (`Capnp e)) + | Ok resp -> + Lazy.force finish; + let payload = Msg.Response.readable resp in + let release_response_caps () = Core_types.Response_payload.release resp in + let contents = Schema.Reader.Payload.content_get payload |> Schema.Reader.of_pointer in + resolve @@ Ok (contents, release_response_caps) + ); + MVar.wait mvar + +let call_for_value cap m req = + match call_and_wait cap m req with + | Error _ as response -> response + | Ok (response, release_response_caps) -> + release_response_caps (); + Ok response + +let call_for_value_exn cap m req = + match call_for_value cap m req with + | Ok x -> x + | Error (`Capnp e) -> + let msg = Fmt.asprintf "Error calling %t(%a): %a" + cap#pp + Capnp.RPC.MethodID.pp m + Capnp_rpc.Error.pp e in + raise (Failure msg) + +let call_for_unit cap m req = + match call_for_value cap m req with + | Ok _ -> Ok () + | Error _ as e -> e + +let call_for_unit_exn cap m req = call_for_value_exn cap m req |> ignore + +let call_for_caps cap m req fn = + let q = call cap m req in + match fn q with + | r -> Core_types.dec_ref q; r + | exception ex -> Core_types.dec_ref q; raise ex + +type 'a resolver = Cap_proxy.resolver_cap + +let promise () = + let cap = Cap_proxy.local_promise () in + (cap :> Core_types.cap), (cap :> 'a resolver) + +let resolve_ok r x = r#resolve x + +let resolve_exn r ex = r#resolve (Core_types.broken_cap ex) diff --git a/capnp-rpc-sync/capnp_core.ml b/capnp-rpc-sync/capnp_core.ml new file mode 100644 index 000000000..e5a7c944b --- /dev/null +++ b/capnp-rpc-sync/capnp_core.ml @@ -0,0 +1,18 @@ + +module Capnp_content = struct + include Msg + let ref_leak_detected fn = fn() +end + +module Core_types = Capnp_rpc.Core_types(Capnp_content) + +module Local_struct_promise = Capnp_rpc.Local_struct_promise.Make(Core_types) +module Cap_proxy = Capnp_rpc.Cap_proxy.Make(Core_types) + +module type ENDPOINT = Capnp_rpc.Message_types.ENDPOINT with + module Core_types = Core_types + +class type sturdy_ref = object + method connect : (Core_types.cap, Capnp_rpc.Exception.t) result + method to_uri_with_secrets : Uri.t +end diff --git a/capnp-rpc-sync/capnp_rpc_sync.ml b/capnp-rpc-sync/capnp_rpc_sync.ml new file mode 100644 index 000000000..c1da39223 --- /dev/null +++ b/capnp-rpc-sync/capnp_rpc_sync.ml @@ -0,0 +1,74 @@ +open Capnp_core + +include Capnp.Message.BytesMessage + +module Log = Capnp_rpc.Debug.Log +module RO_array = Capnp_rpc.RO_array + +module Capability = Capability + +module StructRef = struct + type 'a t = Core_types.struct_ref + + let inc_ref = Core_types.inc_ref + let dec_ref = Core_types.dec_ref +end + +module Sturdy_ref = Sturdy_ref + +module Untyped = struct + let struct_field t i = + (* todo: would be better to have a separate type for this *) + object (_ : Core_types.struct_ref) + method cap path = t#cap (Xform.Field i :: path) + method when_resolved _ = failwith "Can't use when_resolved on a sub-struct" + method response = failwith "Can't use response on a sub-struct" + method update_rc = failwith "Can't use rec-counts on a sub-struct" + method sealed_dispatch _ = None + method pp f = Fmt.pf f "pointer %d in %t" i t#pp + method blocker = failwith "struct_field: blocker" + method check_invariants = () + end + + let capability_field t f = t#cap [Xform.Field f] + + let local = Service.local + + type abstract_method_t = Service.abstract_method_t + + let abstract_method x req release = + x (StructStorage.cast_reader req) release + + let get_cap a i = + Core_types.Attachments.cap (Stdint.Uint32.to_int i) (Msg.unwrap_attachments a) + + let add_cap a cap = + Core_types.Attachments.add_cap (Msg.unwrap_attachments a) cap |> Stdint.Uint32.of_int + + let clear_cap a i = + Core_types.Attachments.clear_cap (Msg.unwrap_attachments a) (Stdint.Uint32.to_int i) + + let unknown_interface ~interface_id _req release_params = + release_params (); + Core_types.fail ~ty:`Unimplemented "Unknown interface %a" Stdint.Uint64.printer interface_id + + let unknown_method ~interface_id ~method_id _req release_params = + release_params (); + Core_types.fail ~ty:`Unimplemented "Unknown method %a.%d" Stdint.Uint64.printer interface_id method_id + + class type generic_service = Service.generic +end + +module Service = Service + +module Private = Private + +module Cast = struct + let cap_of_raw x = x + let cap_to_raw x = x + + let sturdy_of_raw x = x + let sturdy_to_raw x = x +end + +module Persistence = Persistence diff --git a/capnp-rpc-sync/capnp_rpc_sync.mli b/capnp-rpc-sync/capnp_rpc_sync.mli new file mode 100644 index 000000000..4713d884f --- /dev/null +++ b/capnp-rpc-sync/capnp_rpc_sync.mli @@ -0,0 +1,320 @@ +(** Cap'n Proto RPC using the Cap'n Proto serialisation and Lwt for concurrency. *) + +open Capnp.RPC +open Utils + +include (module type of Capnp.BytesMessage) + +module StructRef : sig + (** A promise for a response structure. + You can use the generated [_get_pipelined] functions on a promise to get + a promise for a capability inside the promise, and then pipeline messages + to that promise without waiting for the response struct to arrive. *) + + type 'a t + (** An ['a t] is a reference to a response message (that may not have arrived yet) + with content type ['a]. *) + + val inc_ref : 'a t -> unit + (** [inc_ref t] increases the reference count on [t] by one. *) + + val dec_ref : 'a t -> unit + (** [dec_ref t] reduces the reference count on [t] by one. + When the count reaches zero, this result must never be used again. + If the results have not yet arrived when the count reaches zero, we send + a cancellation request (which may or may not succeed). As soon as the + results are available, they are released. *) +end + +module Capability : sig + (** A capability is a reference to an object, or to a promise for an object. + You can invoke methods on a capability even while it is still only a + promise. *) + + type +'a t + (** An ['a t] is a capability reference to a service of type ['a]. *) + + val broken : Capnp_rpc.Exception.t -> 'a t + (** [broken ex] is a broken capability, with problem [ex]. + Any attempt to call methods on it will fail with [ex]. *) + + val when_broken : (Capnp_rpc.Exception.t -> unit) -> 'a t -> unit + (** [when_broken fn x] calls [fn problem] when [x] becomes broken. + If [x] is already broken, [fn] is called immediately. + If [x] can never become broken (e.g. it is a near ref), this does nothing. + If [x]'s ref-count reaches zero without [fn] being called, it will never + be called. *) + + val when_released : 'a t -> (unit -> unit) -> unit + (** [when_released t fn] will call [fn ()] when [t]'s ref-count drops to zero. + This is used for caches, to remove entries when they become invalid. + For promises, [fn] will be transferred to the resolution if resolved. + For broken caps, this method does nothing (exceptions are never released). *) + + val problem : 'a t -> Capnp_rpc.Exception.t option + (** [problem t] is [Some ex] if [t] is broken, or [None] if it is still + believed to be healthy. Once a capability is broken, it will never + work again and any calls made on it will fail with exception [ex]. *) + + val wait_until_settled : 'a t -> unit Fut.t + (** [wait_until_settled x] resolves once [x] is a "settled" (non-promise) reference. + If [x] is a near, far or broken reference, this returns immediately. + If it is currently a local or remote promise, it waits until it isn't. + [wait_until_settled] takes ownership of [x] until it returns (you must not + [dec_ref] it before then). *) + + val equal : 'a t -> 'a t -> (bool, [`Unsettled]) result + (** [equal a b] indicates whether [a] and [b] designate the same settled service. + Returns [Error `Unsettled] if [a] or [b] is still a promise (and they therefore + may yet turn out to be equal when the promise resolves). *) + + module Request : sig + type 'a t + (** An ['a t] is a builder for the out-going request's payload. *) + + val create : (Capnp.Message.rw Slice.t -> 'a) -> 'a t * 'a + (** [create init] is a fresh request payload and contents builder. + Use one of the generated [init_pointer] functions for [init]. *) + + val create_no_args : unit -> 'a t + (** [create_no_args ()] is a payload with no content. *) + + val release : 'a t -> unit + (** Clear the exported refs, dropping their ref-counts. This is called automatically + when you send a message, but you might need it if you decide to abort. *) + end + + val call : 't t -> ('t, 'a, 'b) MethodID.t -> 'a Request.t -> 'b StructRef.t + (** [call target m req] invokes [target#m req] and returns a promise for the result. + Messages may be sent to the capabilities that will be in the result + before the result arrives - they will be pipelined to the service + responsible for resolving the promise. The caller must call [StructRef.dec_ref] + when finished with the result (consider using one of the [call_*] functions below + instead for a simpler interface). *) + + val call_and_wait : 't t -> ('t, 'a, 'b StructStorage.reader_t) MethodID.t -> + 'a Request.t -> + (('b StructStorage.reader_t * (unit -> unit)), [> `Capnp of Capnp_rpc.Error.t]) + result + (** [call_and_wait t m req] does [call t m req] and waits for the response. + This is simpler than using [call], but doesn't support pipelining + (you can't use any capabilities in the response in another message until the + response arrives). + On success, it returns [Ok (response, release_response_caps)]. + Call [release_response_caps] when done with the results, to release any capabilities it might + contain that you didn't use (remembering that future versions of the protocol might add + new optional capabilities you don't know about yet). + If you don't need any capabilities from the result, consider using [call_for_value] instead. + Doing [Lwt.cancel] on the result will send a cancel message to the target + for remote calls. *) + + val call_for_value : 't t -> ('t, 'a, 'b StructStorage.reader_t) MethodID.t -> + 'a Request.t -> ('b StructStorage.reader_t, [> `Capnp of Capnp_rpc.Error.t]) + result + (** [call_for_value t m req] is similar to [call_and_wait], but automatically + releases any capabilities in the response before returning. Use this if + you aren't expecting any capabilities in the response. *) + + val call_for_value_exn : 't t -> ('t, 'a, 'b StructStorage.reader_t) MethodID.t -> + 'a Request.t -> 'b StructStorage.reader_t + (** Wrapper for [call_for_value] that turns errors into Lwt failures. *) + + val call_for_unit : 't t -> ('t, 'a, 'b StructStorage.reader_t) MethodID.t -> + 'a Request.t -> (unit, [> `Capnp of Capnp_rpc.Error.t]) result + (** Wrapper for [call_for_value] that ignores the result. *) + + val call_for_unit_exn : 't t -> ('t, 'a, 'b StructStorage.reader_t) MethodID.t -> + 'a Request.t -> unit + (** Wrapper for [call_for_unit] that turns errors into Lwt failures. *) + + val call_for_caps : 't t -> ('t, 'a, 'b StructStorage.reader_t) MethodID.t -> + 'a Request.t -> ('b StructRef.t -> 'c) -> 'c + (** [call_for_caps target m req extract] is a wrapper for [call] that passes the results promise to + [extract], which should extract any required capability promises from it. + In the common case where you want a single cap "foo" from the result, use + [call_for_caps target m req Results.foo_get_pipelined]. + When the remote call finally returns, the result will be released automatically. *) + + type 'a resolver + (** An ['a resolver] can be used to resolve a promise for an ['a]. It can only be used once. *) + + val promise : unit -> 'a t * 'a resolver + (** [promise ()] returns a fresh local promise and a resolver for it. + Any calls made on the promise will be queued until it is resolved. *) + + val resolve_ok : 'a resolver -> 'a t -> unit + (** [resolve_ok r x] resolves [r]'s promise to [x]. [r] takes ownership of [x] + (the caller must use [inc_ref] first if they want to continue using it). *) + + val resolve_exn : 'a resolver -> Capnp_rpc.Exception.t -> unit + (** [resolve_exn r x] breaks [r]'s promise with exception [x]. *) + + val inc_ref : _ t -> unit + (** [inc_ref t] increases the ref-count on [t] by one. *) + + val dec_ref : _ t -> unit + (** [dec_ref t] decreases the ref-count on [t] by one. When the count reaches zero, + the capability is released. This may involve sending a notification to a remote + peer. Any time you extract a capability from a struct or struct promise, + it must eventually be freed by calling [dec_ref] on it. *) + + val with_ref : 'a t -> ('a t -> 'b) -> 'b + (** [with_ref t fn] runs [fn t] and then calls [dec_ref t] (whether [fn] + succeeds or not). *) + + val pp : 'a t Fmt.printer +end + +module Sturdy_ref : sig + type +'a t + (** An off-line (persistent) capability reference. + + A sturdy ref contains all the information necessary to get a live reference to a service: + + - The network address of the hosting vat (e.g. TCP host and port) + - A way to authenticate the hosting vat (e.g. a fingerprint of the vat's public key) + - A way to identify the target service within the vat and prove permission to access it + (e.g. a "Swiss number") + *) + + val connect : 'a t -> ('a Capability.t, Capnp_rpc.Exception.t) result Fut.t + (** [connect t] returns a live reference to [t]'s service. *) + + val connect_exn : 'a t -> 'a Capability.t Fut.t + (** [connect_exn] is a wrapper for [connect] that returns a failed Lwt thread on error. *) + + val reader : + ('a StructStorage.reader_t -> Capnp.MessageSig.ro Slice.t option) -> + 'a StructStorage.reader_t -> Uri.t + (** [reader accessor] is a field accessor for reading a sturdy ref. + e.g. if [sr_get] is a generated field accessor for an AnyPointer field, then + [reader Reader.Struct.sr_get] is an accessor that treats it as a SturdyRef field. + todo: This should really return a sturdy ref, not a URI, but that requires a change + to the spec to add a sturdy ref cap-descriptor table entry type. *) + + val builder : + ('a StructStorage.builder_t -> Capnp.MessageSig.rw Slice.t) -> + 'a StructStorage.builder_t -> _ t -> unit + (** [builder setter] converts a generated AnyPointer field setter [setter] to a SturdyRef + setter. Use it to add a SturdyRef to a message with [builder Params.sr_get params sr]. *) + + val cast : 'a t -> 'b t +end + +module Service : sig + (** Functions for service implementors. *) + + type ('a, 'b) method_t = 'a -> (unit -> unit) -> 'b StructRef.t + (** An ('a, 'b) method_t is a method implementation that takes + a reader for the parameters and + a function to release the capabilities in the parameters, + and returns a promise for the results. *) + + module Response : sig + type 'b t + (** An ['a t] is a builder for the out-going response. *) + + val create : (Capnp.Message.rw Slice.t -> 'a) -> 'a t * 'a + (** [create init] is a fresh response and contents builder. + Use one of the generated [init_pointer] functions for [init]. *) + + val create_empty : unit -> 'a t + (** [empty ()] is an empty response. *) + + val release : 'a t -> unit + (** Clear the exported refs, dropping their ref-counts. This is called automatically + when you send a message, but you might need it if you decide to abort. *) + end + + val return : 'a Response.t -> 'a StructRef.t + (** [return r] wraps up a simple local result as a promise. *) + + val return_empty : unit -> 'a StructRef.t + (** [return_empty ()] is a promise for a response with no payload. *) + + val return_fut : + (unit -> ('a Response.t, [< `Capnp of Capnp_rpc.Error.t]) result Fut.t) -> + 'a StructRef.t + (** [return_lwt fn] is a local promise for the result of Lwt thread [fn ()]. + If [fn ()] fails, the error is logged and an "Internal error" returned to the caller. + If it returns an [Error] value then that error is returned to the caller. + Note that this does not support pipelining (any messages sent to the response + will be queued locally until it [fn] has produced a result), so it may be better + to return immediately a result containing a promise in some cases. *) + + val fail : ?ty:Capnp_rpc.Exception.ty -> ('a, Format.formatter, unit, 'b StructRef.t) format4 -> 'a + (** [fail msg] is an exception with reason [msg]. *) +end + +(**/**) + +module Untyped : sig + (** This module is only for use by the code generated by the capnp-ocaml + schema compiler. The generated code provides type-safe wrappers for + everything here. *) + + type abstract_method_t + + val abstract_method : ('a StructStorage.reader_t, 'b) Service.method_t -> abstract_method_t + + val struct_field : 'a StructRef.t -> int -> 'b StructRef.t + + val capability_field : 'a StructRef.t -> int -> 'b Capability.t + + class type generic_service = object + method dispatch : interface_id:Uint64.t -> method_id:int -> abstract_method_t + method release : unit + method pp : Format.formatter -> unit + end + + val local : #generic_service -> 'a Capability.t + + val get_cap : Capnp.MessageSig.attachments -> Uint32.t -> _ Capability.t + val add_cap : Capnp.MessageSig.attachments -> _ Capability.t -> Uint32.t + val clear_cap : Capnp.MessageSig.attachments -> Uint32.t -> unit + + val unknown_interface : interface_id:Uint64.t -> abstract_method_t + val unknown_method : interface_id:Uint64.t -> method_id:int -> abstract_method_t +end + +module Private = Private + +module Cast : sig + val cap_of_raw : Capnp_core.Core_types.cap -> 'a Capability.t + val cap_to_raw : 'a Capability.t -> Capnp_core.Core_types.cap + + val sturdy_of_raw : Capnp_core.sturdy_ref -> 'a Sturdy_ref.t + val sturdy_to_raw : 'a Sturdy_ref.t -> Capnp_core.sturdy_ref +end + +(**/**) + +module Persistence : sig + class type ['a] persistent = object + method save : ('a Sturdy_ref.t, Capnp_rpc.Exception.t) result Fut.t + end + + val with_persistence : + ('a #persistent) -> + ('impl -> 'a Capability.t) -> + (#Untyped.generic_service as 'impl) -> + 'a Capability.t + (** [with_persistence persist Service.Foo.local obj] is like [Service.Foo.local obj], but the + resulting service also handles the Cap'n Proto persistence protocol, using [persist]. *) + + val with_sturdy_ref : + 'a Sturdy_ref.t -> + ('impl -> 'a Capability.t) -> + (#Untyped.generic_service as 'impl) -> + 'a Capability.t + (** [with_sturdy_ref sr Service.Foo.local obj] is like [Service.Foo.local obj], + but responds to [save] calls by returning [sr]. *) + + val save : 'a Capability.t -> (Uri.t, [> `Capnp of Capnp_rpc.Error.t]) result Fut.t + (** [save cap] calls the persistent [save] method on [cap]. + Note that not all capabilities can be saved. + todo: this should return an ['a Sturdy_ref.t]; see {!Sturdy_ref.reader}. *) + + val save_exn : 'a Capability.t -> Uri.t Fut.t + (** [save_exn] is a wrapper for [save] that returns a failed thread on error. *) +end diff --git a/capnp-rpc-sync/dune b/capnp-rpc-sync/dune new file mode 100644 index 000000000..63dfbd037 --- /dev/null +++ b/capnp-rpc-sync/dune @@ -0,0 +1,17 @@ +(library + (name capnp_rpc_sync) + (public_name capnp-rpc-sync) + (ocamlc_flags :standard -w -55-53) + (ocamlopt_flags :standard -w -55-53) + (libraries astring capnp capnp-rpc logs unix containers + containers.unix containers.thread uri)) + +(rule + (targets rpc_schema.ml rpc_schema.mli) + (deps rpc_schema.capnp) + (action (run capnpc -o %{bin:capnpc-ocaml} %{deps}))) + +(rule + (targets persistent.ml persistent.mli) + (deps persistent.capnp) + (action (run capnpc -o %{bin:capnpc-ocaml} %{deps}))) diff --git a/capnp-rpc-sync/msg.ml b/capnp-rpc-sync/msg.ml new file mode 100644 index 000000000..f828f72aa --- /dev/null +++ b/capnp-rpc-sync/msg.ml @@ -0,0 +1,126 @@ +module Log = Capnp_rpc.Debug.Log +module B = Schema.Builder +module R = Schema.Reader +module RO_array = Capnp_rpc.RO_array +module StructStorage = Capnp.Message.BytesMessage.StructStorage + +type Capnp.MessageSig.attachments += RPC_attachments of Capnp_rpc.S.attachments + +module Path = struct + type t = Xform.t list + let compare = compare + let pp = Fmt.Dump.list Xform.pp + let root = [] +end + +type request = [`Call_836a53ce789d4cd4] +type response = [`Return_9e19b28d3db3573a] +type 'a msg = + | Builder of 'a StructStorage.builder_t + | Readonly of 'a StructStorage.reader_t +(* We can sometimes avoid a copy by returning the builder directly. + e.g. the application code builds a call and passes it to a proxy, which transmits + it over the network. A message can only be transmitted once. *) + +let with_attachments a t = + match t with + | Builder x -> Builder (StructStorage.with_attachments (RPC_attachments a) x) + | Readonly None -> Readonly None + | Readonly (Some x) -> Readonly (Some (StructStorage.with_attachments (RPC_attachments a) x)) + +let unwrap_attachments = function + | RPC_attachments x -> x + | Capnp.MessageSig.No_attachments -> Capnp_rpc.S.No_attachments + | _ -> failwith "Unknown attachment type!" + +let attachments = function + | Readonly None -> Capnp_rpc.S.No_attachments + | Readonly (Some ss) -> unwrap_attachments @@ StructStorage.get_attachments ss + | Builder ss -> unwrap_attachments @@ StructStorage.get_attachments ss + +let wrap_attachments a = RPC_attachments a + +module Request = struct + type t = request msg + (* Call message with interface_id, method_id and payload.content filled in *) + + let copy rcall = (* todo: set init size from src; also for copy_resp *) + let msg = B.Message.init_root () in + let call = B.Message.call_init msg in + B.Call.interface_id_set call (R.Call.interface_id_get rcall); + B.Call.method_id_set_exn call (R.Call.method_id_get rcall); + (* Only copy the contents, not the caps. *) + let payload = B.Call.params_init call in + let rpayload = R.Call.params_get rcall in + B.Payload.content_set_reader payload (R.Payload.content_get rpayload) |> ignore; + call + + let writable : t -> _ = function + | Readonly call -> copy call + | Builder call -> call + + let readable = function + | Readonly call -> call + | Builder call -> R.Call.of_builder call + + let of_builder x = Builder x + let of_reader x = Readonly x + + let cap_index t path = + let call = readable t in + Xform.resolve (R.Call.params_get call) path + + let pp f _ = Fmt.string f "(request content)" + + let with_attachments = with_attachments + let attachments = attachments +end + +module Response = struct + type t = response msg + + let copy (rret : R.Return.t) = + let msg = B.Message.init_root () in + let ret = B.Message.return_init msg in + begin match R.Return.get rret with + | R.Return.Results rpayload -> + (* Only copy the contents, not the caps. *) + let payload = B.Return.results_init ret in + B.Payload.content_set_reader payload (R.Payload.content_get rpayload) |> ignore + | _ -> failwith "Not a results message!" + end; + ret + + let writable = function + | Readonly x -> copy x + | Builder ret -> ret + + let readable resp = + let resp = + match resp with + | Readonly x -> x + | Builder x -> R.Return.of_builder x + in + match R.Return.get resp with + | R.Return.Results r -> r + | _ -> assert false + + let bootstrap () = + let msg = B.Message.init_root () in + let ret = B.Message.return_init msg in + let p = B.Return.results_init ret in + B.Payload.content_set_interface p (Some Stdint.Uint32.zero); (* Cap index 0 *) + Builder ret + + let of_builder x = Builder x + let of_reader x = Readonly x + + let cap_index t path = + let results = readable t in + Xform.resolve results path + + let pp f _ = Fmt.string f "(response content)" + + let with_attachments = with_attachments + let attachments = attachments +end diff --git a/capnp-rpc-sync/msg.mli b/capnp-rpc-sync/msg.mli new file mode 100644 index 000000000..5574a8c43 --- /dev/null +++ b/capnp-rpc-sync/msg.mli @@ -0,0 +1,44 @@ +type request +type response +type 'a msg + +module Path : sig + type t = Xform.t list + val compare : t -> t -> int + val pp : t Fmt.t + val root : t +end + +module Request : sig + include Capnp_rpc.S.WIRE_PAYLOAD with type path := Path.t and type t = request msg + + val writable : t -> Schema.Builder.Call.t + (** We're about to transmit this message and we need to fill in the target and CapDescriptor table. + If the message is read-only (e.g. we received it over the network and are forwarding it) + then make a copy. The copy has no CapDescriptor table and no attachments. *) + + val readable : t -> Schema.Reader.Call.t + + val of_builder : Schema.Builder.Call.t -> t + val of_reader : Schema.Reader.Call.t -> t +end + +module Response : sig + include Capnp_rpc.S.WIRE_PAYLOAD with type path := Path.t and type t = response msg + + val writable : t -> Schema.Builder.Return.t + (** We're about to transmit this message and we need to fill in the CapDescriptor table. + If the message is read-only (e.g. we received it over the network and are forwarding it) + then make a copy. The copy has no CapDescriptor table and no attachments. *) + + val readable : t -> Schema.Reader.Payload.t + + val of_builder : Schema.Builder.Return.t -> t + val of_reader : Schema.Reader.Return.t -> t + + val bootstrap : unit -> t + (** [bootstrap ()] is a fresh bootstrap response. *) +end + +val wrap_attachments : Capnp_rpc.S.attachments -> Capnp.MessageSig.attachments +val unwrap_attachments : Capnp.MessageSig.attachments -> Capnp_rpc.S.attachments diff --git a/capnp-rpc-sync/persistence.ml b/capnp-rpc-sync/persistence.ml new file mode 100644 index 000000000..2a6ef9518 --- /dev/null +++ b/capnp-rpc-sync/persistence.ml @@ -0,0 +1,63 @@ + +open Utils + +module Api = Persistent.Make(Capnp.BytesMessage) + +class type ['a] persistent = object + method save : ('a Sturdy_ref.t, Capnp_rpc.Exception.t) result Fut.t +end + +let with_persistence + (persistent:'b #persistent) + (_:(#Service.generic as 'a) -> 'b Capability.t) + (impl : 'a) = + (* We ignore the second argument. It's just to force the user to prove that [impl] + really does have type ['a]. *) + let dispatch_persistent method_id _params release_params = + if method_id = Capnp.RPC.MethodID.method_id Api.Client.Persistent.Save.method_id then ( + let open Api.Service.Persistent.Save in + release_params (); + let open Fut.Infix in + Service.return_fut @@ fun () -> + persistent#save >|= function + | Error e -> Error (`Capnp (`Exception e)) + | Ok sr -> + let resp, results = Service.Response.create Results.init_pointer in + Sturdy_ref.builder Results.sturdy_ref_get results sr; + Ok resp + ) else ( + release_params (); + Service.fail ~ty:`Unimplemented "Unknown persistence method %d" method_id + ) + in + let wrapper = object (_ : #Service.generic) + method release = impl#release + method pp = impl#pp + method dispatch ~interface_id ~method_id = + if interface_id = Api.Service.Persistent.interface_id + then dispatch_persistent method_id + else impl#dispatch ~interface_id ~method_id + end in + Service.local wrapper + +let with_sturdy_ref sr local impl = + let persistent = object + method save = Fut.return @@ Ok sr + end in + with_persistence persistent local impl + +let save cap : _ Fut.t = + let open Api.Client.Persistent.Save in + let request = Capability.Request.create_no_args () in + let open Fut.Infix in + Fut.make + (fun () -> + match Capability.call_for_value cap method_id request with + | Error _ as e -> e + | Ok response -> Ok (Sturdy_ref.reader Results.sturdy_ref_get response)) + +let save_exn cap : _ Fut.t = + let open Fut.Infix in + save cap >>= function + | Error (`Capnp e) -> failwith (Fmt.to_string Capnp_rpc.Error.pp e) + | Ok x -> Fut.return x diff --git a/capnp-rpc-sync/persistent.capnp b/capnp-rpc-sync/persistent.capnp new file mode 100644 index 000000000..bf4017c1d --- /dev/null +++ b/capnp-rpc-sync/persistent.capnp @@ -0,0 +1,109 @@ +# Copyright (c) 2014 Sandstorm Development Group, Inc. and contributors +# Licensed under the MIT License: +# +# Permission is hereby granted, free of charge, to any person obtaining a copy +# of this software and associated documentation files (the "Software"), to deal +# in the Software without restriction, including without limitation the rights +# to use, copy, modify, merge, publish, distribute, sublicense, and/or sell +# copies of the Software, and to permit persons to whom the Software is +# furnished to do so, subject to the following conditions: +# +# The above copyright notice and this permission notice shall be included in +# all copies or substantial portions of the Software. +# +# THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR +# IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, +# FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE +# AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER +# LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, +# OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN +# THE SOFTWARE. + +@0xb8630836983feed7; + +#$import "/capnp/c++.capnp".namespace("capnp"); + +interface Persistent@0xc8cb212fcd9f5691 { + # Interface implemented by capabilities that outlive a single connection. A client may save() + # the capability, producing a SturdyRef. The SturdyRef can be stored to disk, then later used to + # obtain a new reference to the capability on a future connection. + # + # The exact format of SturdyRef depends on the "realm" in which the SturdyRef appears. A "realm" + # is an abstract space in which all SturdyRefs have the same format and refer to the same set of + # resources. Every vat is in exactly one realm. All capability clients within that vat must + # produce SturdyRefs of the format appropriate for the realm. + # + # Similarly, every VatNetwork also resides in a particular realm. Usually, a vat's "realm" + # corresponds to the realm of its main VatNetwork. However, a Vat can in fact communicate over + # a VatNetwork in a different realm -- in this case, all SturdyRefs need to be transformed when + # coming or going through said VatNetwork. The RPC system has hooks for registering + # transformation callbacks for this purpose. + # + # Since the format of SturdyRef is realm-dependent, it is not defined here. An application should + # choose an appropriate realm for itself as part of its design. Note that under Sandstorm, every + # application exists in its own realm and is therefore free to define its own SturdyRef format; + # the Sandstorm platform handles translating between realms. + # + # Note that whether a capability is persistent is often orthogonal to its type. In these cases, + # the capability's interface should NOT inherit `Persistent`; instead, just perform a cast at + # runtime. It's not type-safe, but trying to be type-safe in these cases will likely lead to + # tears. In cases where a particular interface only makes sense on persistent capabilities, it + # still should not explicitly inherit Persistent because the `SturdyRef` and `Owner` types will + # vary between realms (they may even be different at the call site than they are on the + # implementation). Instead, mark persistent interfaces with the $persistent annotation (defined + # below). + # + # Sealing + # ------- + # + # As an added security measure, SturdyRefs may be "sealed" to a particular owner, such that + # if the SturdyRef itself leaks to a third party, that party cannot actually restore it because + # they are not the owner. To restore a sealed capability, you must first prove to its host that + # you are the rightful owner. The precise mechanism for this authentication is defined by the + # realm. + # + # Sealing is a defense-in-depth mechanism meant to mitigate damage in the case of catastrophic + # attacks. For example, say an attacker temporarily gains read access to a database full of + # SturdyRefs: it would be unfortunate if it were then necessary to revoke every single reference + # in the database to prevent the attacker from using them. + # + # In general, an "owner" is a course-grained identity. Because capability-based security is still + # the primary mechanism of security, it is not necessary nor desirable to have a separate "owner" + # identity for every single process or object; that is exactly what capabilities are supposed to + # avoid! Instead, it makes sense for an "owner" to literally identify the owner of the machines + # where the capability is stored. If untrusted third parties are able to run arbitrary code on + # said machines, then the sandbox for that code should be designed using Distributed Confinement + # such that the third-party code never sees the bits of the SturdyRefs and cannot directly + # exercise the owner's power to restore refs. See: + # + # http://www.erights.org/elib/capability/dist-confine.html + # + # Resist the urge to represent an Owner as a simple public key. The whole point of sealing is to + # defend against leaked-storage attacks. Such attacks can easily result in the owner's private + # key being stolen as well. A better solution is for `Owner` to contain a simple globally unique + # identifier for the owner, and for everyone to separately maintain a mapping of owner IDs to + # public keys. If an owner's private key is compromised, then humans will need to communicate + # and agree on a replacement public key, then update the mapping. + # + # As a concrete example, an `Owner` could simply contain a domain name, and restoring a SturdyRef + # would require signing a request using the domain's private key. Authenticating this key could + # be accomplished through certificate authorities or web-of-trust techniques. + + save @0 SaveParams -> SaveResults; + # Save a capability persistently so that it can be restored by a future connection. Not all + # capabilities can be saved -- application interfaces should define which capabilities support + # this and which do not. + + struct SaveParams { + sealFor @0 :AnyPointer; + # Seal the SturdyRef so that it can only be restored by the specified Owner. This is meant + # to mitigate damage when a SturdyRef is leaked. See comments above. + # + # Leaving this value null may or may not be allowed; it is up to the realm to decide. If a + # realm does allow a null owner, this should indicate that anyone is allowed to restore the + # ref. + } + struct SaveResults { + sturdyRef @0 :AnyPointer; + } +} diff --git a/capnp-rpc-sync/private.ml b/capnp-rpc-sync/private.ml new file mode 100644 index 000000000..4a1f52dc9 --- /dev/null +++ b/capnp-rpc-sync/private.ml @@ -0,0 +1,7 @@ +(* Some internal modules that we expose to capnp-rpc-net only. *) + +module Schema = Schema +module Rpc_schema = Rpc_schema +module Msg = Msg +module Xform = Xform +module Capnp_core = Capnp_core diff --git a/capnp-rpc-sync/request.ml b/capnp-rpc-sync/request.ml new file mode 100644 index 000000000..416b95b7b --- /dev/null +++ b/capnp-rpc-sync/request.ml @@ -0,0 +1,32 @@ +open Capnp_core +open Schema.Builder +module RO_array = Capnp_rpc.RO_array +module StructStorage = Capnp.Message.BytesMessage.StructStorage + +type 'a t = Message.t + +let create init = + let msg = + Message.init_root () + |> StructStorage.with_attachments (Msg.wrap_attachments (Core_types.Attachments.builder ())) in + let call = Message.call_init msg in + let p = Call.params_get call in + let content = init (Payload.content_get p) in + msg, content + +let create_no_args () = + let msg = Message.init_root () in + ignore (Message.call_init msg); + msg + +let finish m t = + match Message.get t with + | Message.Call c -> + let msg = Msg.Request.of_builder c in + Call.interface_id_set c @@ Capnp.RPC.MethodID.interface_id m; + Call.method_id_set_exn c @@ Capnp.RPC.MethodID.method_id m; + msg + | _ -> assert false + +let release t = + Core_types.Attachments.release_caps (Msg.unwrap_attachments (StructStorage.get_attachments t)) diff --git a/capnp-rpc-sync/request.mli b/capnp-rpc-sync/request.mli new file mode 100644 index 000000000..fb167ef3d --- /dev/null +++ b/capnp-rpc-sync/request.mli @@ -0,0 +1,8 @@ +type 'a t + +module RO_array = Capnp_rpc.RO_array + +val create : (Capnp.Message.rw Capnp.BytesMessage.Slice.t -> 'a) -> 'a t * 'a +val create_no_args : unit -> 'a t +val finish : (_, 'a, _) Capnp.RPC.MethodID.t -> 'a t -> Msg.Request.t +val release : 'a t -> unit diff --git a/capnp-rpc-sync/response.ml b/capnp-rpc-sync/response.ml new file mode 100644 index 000000000..9f7b77487 --- /dev/null +++ b/capnp-rpc-sync/response.ml @@ -0,0 +1,30 @@ +open Capnp_core +open Schema.Builder +module RO_array = Capnp_rpc.RO_array +module StructStorage = Capnp.Message.BytesMessage.StructStorage + +type 'a cap = Core_types.cap + +type 'a t = Message.t + +let create init = + let msg = + Message.init_root () + |> StructStorage.with_attachments (Msg.wrap_attachments (Core_types.Attachments.builder ())) in + let ret = Message.return_init msg in + let p = Return.results_init ret in + let content = init (Payload.content_get p) in + msg, content + +let create_empty () = + let msg = Message.init_root () in + let _ = Message.return_init msg in + msg + +let finish t = + match Message.get t with + | Message.Return r -> Msg.Response.of_builder r + | _ -> assert false + +let release t = + Core_types.Attachments.release_caps (Msg.unwrap_attachments (StructStorage.get_attachments t)) diff --git a/capnp-rpc-sync/rpc_schema.capnp b/capnp-rpc-sync/rpc_schema.capnp new file mode 100644 index 000000000..241d236fc --- /dev/null +++ b/capnp-rpc-sync/rpc_schema.capnp @@ -0,0 +1,1404 @@ +# Copyright (c) 2013-2014 Sandstorm Development Group, Inc. and contributors +# Licensed under the MIT License: +# +# Permission is hereby granted, free of charge, to any person obtaining a copy +# of this software and associated documentation files (the "Software"), to deal +# in the Software without restriction, including without limitation the rights +# to use, copy, modify, merge, publish, distribute, sublicense, and/or sell +# copies of the Software, and to permit persons to whom the Software is +# furnished to do so, subject to the following conditions: +# +# The above copyright notice and this permission notice shall be included in +# all copies or substantial portions of the Software. +# +# THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR +# IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, +# FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE +# AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER +# LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, +# OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN +# THE SOFTWARE. + +@0xb312981b2552a250; +# Recall that Cap'n Proto RPC allows messages to contain references to remote objects that +# implement interfaces. These references are called "capabilities", because they both designate +# the remote object to use and confer permission to use it. +# +# Recall also that Cap'n Proto RPC has the feature that when a method call itself returns a +# capability, the caller can begin calling methods on that capability _before the first call has +# returned_. The caller essentially sends a message saying "Hey server, as soon as you finish +# that previous call, do this with the result!". Cap'n Proto's RPC protocol makes this possible. +# +# The protocol is significantly more complicated than most RPC protocols. However, this is +# implementation complexity that underlies an easy-to-grasp higher-level model of object oriented +# programming. That is, just like TCP is a surprisingly complicated protocol that implements a +# conceptually-simple byte stream abstraction, Cap'n Proto is a surprisingly complicated protocol +# that implements a conceptually-simple object abstraction. +# +# Cap'n Proto RPC is based heavily on CapTP, the object-capability protocol used by the E +# programming language: +# http://www.erights.org/elib/distrib/captp/index.html +# +# Cap'n Proto RPC takes place between "vats". A vat hosts some set of objects and talks to other +# vats through direct bilateral connections. Typically, there is a 1:1 correspondence between vats +# and processes (in the unix sense of the word), although this is not strictly always true (one +# process could run multiple vats, or a distributed virtual vat might live across many processes). +# +# Cap'n Proto does not distinguish between "clients" and "servers" -- this is up to the application. +# Either end of any connection can potentially hold capabilities pointing to the other end, and +# can call methods on those capabilities. In the doc comments below, we use the words "sender" +# and "receiver". These refer to the sender and receiver of an instance of the struct or field +# being documented. Sometimes we refer to a "third-party" that is neither the sender nor the +# receiver. Documentation is generally written from the point of view of the sender. +# +# It is generally up to the vat network implementation to securely verify that connections are made +# to the intended vat as well as to encrypt transmitted data for privacy and integrity. See the +# `VatNetwork` example interface near the end of this file. +# +# When a new connection is formed, the only interesting things that can be done are to send a +# `Bootstrap` (level 0) or `Accept` (level 3) message. +# +# Unless otherwise specified, messages must be delivered to the receiving application in the same +# order in which they were initiated by the sending application. The goal is to support "E-Order", +# which states that two calls made on the same reference must be delivered in the order which they +# were made: +# http://erights.org/elib/concurrency/partial-order.html +# +# Since the full protocol is complicated, we define multiple levels of support that an +# implementation may target. For many applications, level 1 support will be sufficient. +# Comments in this file indicate which level requires the corresponding feature to be +# implemented. +# +# * **Level 0:** The implementation does not support object references. Only the bootstrap interface +# can be called. At this level, the implementation does not support object-oriented protocols and +# is similar in complexity to JSON-RPC or Protobuf services. This level should be considered only +# a temporary stepping-stone toward level 1 as the lack of object references drastically changes +# how protocols are designed. Applications _should not_ attempt to design their protocols around +# the limitations of level 0 implementations. +# +# * **Level 1:** The implementation supports simple bilateral interaction with object references +# and promise pipelining, but interactions between three or more parties are supported only via +# proxying of objects. E.g. if Alice (in Vat A) wants to send Bob (in Vat B) a capability +# pointing to Carol (in Vat C), Alice must create a proxy of Carol within Vat A and send Bob a +# reference to that; Bob cannot form a direct connection to Carol. Level 1 implementations do +# not support checking if two capabilities received from different vats actually point to the +# same object ("join"), although they should be able to do this check on capabilities received +# from the same vat. +# +# * **Level 2:** The implementation supports saving persistent capabilities -- i.e. capabilities +# that remain valid even after disconnect, and can be restored on a future connection. When a +# capability is saved, the requester receives a `SturdyRef`, which is a token that can be used +# to restore the capability later. +# +# * **Level 3:** The implementation supports three-way interactions. That is, if Alice (in Vat A) +# sends Bob (in Vat B) a capability pointing to Carol (in Vat C), then Vat B will automatically +# form a direct connection to Vat C rather than have requests be proxied through Vat A. +# +# * **Level 4:** The entire protocol is implemented, including joins (checking if two capabilities +# are equivalent). +# +# Note that an implementation must also support specific networks (transports), as described in +# the "Network-specific Parameters" section below. An implementation might have different levels +# depending on the network used. +# +# New implementations of Cap'n Proto should start out targeting the simplistic two-party network +# type as defined in `rpc-twoparty.capnp`. With this network type, level 3 is irrelevant and +# levels 2 and 4 are much easier than usual to implement. When such an implementation is paired +# with a container proxy, the contained app effectively gets to make full use of the proxy's +# network at level 4. And since Cap'n Proto IPC is extremely fast, it may never make sense to +# bother implementing any other vat network protocol -- just use the correct container type and get +# it for free. + +# Fails on Debian 9 with: +# +# lib/rpc_schema.capnp:112:20-38: error: Import failed: /capnp/c++.capnp +# lib/rpc_schema.capnp:113:2-5: error: Not defined: Cxx +# +#using Cxx = import "/capnp/c++.capnp"; +#$Cxx.namespace("capnp::rpc"); + +# ======================================================================================== +# The Four Tables +# +# Cap'n Proto RPC connections are stateful (although an application built on Cap'n Proto could +# export a stateless interface). As in CapTP, for each open connection, a vat maintains four state +# tables: questions, answers, imports, and exports. See the diagram at: +# http://www.erights.org/elib/distrib/captp/4tables.html +# +# The question table corresponds to the other end's answer table, and the imports table corresponds +# to the other end's exports table. +# +# The entries in each table are identified by ID numbers (defined below as 32-bit integers). These +# numbers are always specific to the connection; a newly-established connection starts with no +# valid IDs. Since low-numbered IDs will pack better, it is suggested that IDs be assigned like +# Unix file descriptors -- prefer the lowest-number ID that is currently available. +# +# IDs in the questions/answers tables are chosen by the questioner and generally represent method +# calls that are in progress. +# +# IDs in the imports/exports tables are chosen by the exporter and generally represent objects on +# which methods may be called. Exports may be "settled", meaning the exported object is an actual +# object living in the exporter's vat, or they may be "promises", meaning the exported object is +# the as-yet-unknown result of an ongoing operation and will eventually be resolved to some other +# object once that operation completes. Calls made to a promise will be forwarded to the eventual +# target once it is known. The eventual replacement object does *not* get the same ID as the +# promise, as it may turn out to be an object that is already exported (so already has an ID) or +# may even live in a completely different vat (and so won't get an ID on the same export table +# at all). +# +# IDs can be reused over time. To make this safe, we carefully define the lifetime of IDs. Since +# messages using the ID could be traveling in both directions simultaneously, we must define the +# end of life of each ID _in each direction_. The ID is only safe to reuse once it has been +# released by both sides. +# +# When a Cap'n Proto connection is lost, everything on the four tables is lost. All questions are +# canceled and throw exceptions. All imports become broken (all future calls to them throw +# exceptions). All exports and answers are implicitly released. The only things not lost are +# persistent capabilities (`SturdyRef`s). The application must plan for this and should respond by +# establishing a new connection and restoring from these persistent capabilities. + +using QuestionId = UInt32; +# **(level 0)** +# +# Identifies a question in the sender's question table (which corresponds to the receiver's answer +# table). The questioner (caller) chooses an ID when making a call. The ID remains valid in +# caller -> callee messages until a Finish message is sent, and remains valid in callee -> caller +# messages until a Return message is sent. + +using AnswerId = QuestionId; +# **(level 0)** +# +# Identifies an answer in the sender's answer table (which corresponds to the receiver's question +# table). +# +# AnswerId is physically equivalent to QuestionId, since the question and answer tables correspond, +# but we define a separate type for documentation purposes: we always use the type representing +# the sender's point of view. + +using ExportId = UInt32; +# **(level 1)** +# +# Identifies an exported capability or promise in the sender's export table (which corresponds +# to the receiver's import table). The exporter chooses an ID before sending a capability over the +# wire. If the capability is already in the table, the exporter should reuse the same ID. If the +# ID is a promise (as opposed to a settled capability), this must be indicated at the time the ID +# is introduced (e.g. by using `senderPromise` instead of `senderHosted` in `CapDescriptor`); in +# this case, the importer shall expect a later `Resolve` message that replaces the promise. +# +# ExportId/ImportIds are subject to reference counting. Whenever an `ExportId` is sent over the +# wire (from the exporter to the importer), the export's reference count is incremented (unless +# otherwise specified). The reference count is later decremented by a `Release` message. Since +# the `Release` message can specify an arbitrary number by which to reduce the reference count, the +# importer should usually batch reference decrements and only send a `Release` when it believes the +# reference count has hit zero. Of course, it is possible that a new reference to the export is +# in-flight at the time that the `Release` message is sent, so it is necessary for the exporter to +# keep track of the reference count on its end as well to avoid race conditions. +# +# When a connection is lost, all exports are implicitly released. It is not possible to restore +# a connection state after disconnect (although a transport layer could implement a concept of +# persistent connections if it is transparent to the RPC layer). + +using ImportId = ExportId; +# **(level 1)** +# +# Identifies an imported capability or promise in the sender's import table (which corresponds to +# the receiver's export table). +# +# ImportId is physically equivalent to ExportId, since the export and import tables correspond, +# but we define a separate type for documentation purposes: we always use the type representing +# the sender's point of view. +# +# An `ImportId` remains valid in importer -> exporter messages until the importer has sent +# `Release` messages that (it believes) have reduced the reference count to zero. + +# ======================================================================================== +# Messages + +struct Message { + # An RPC connection is a bi-directional stream of Messages. + + union { + unimplemented @0 :Message; + # The sender previously received this message from the peer but didn't understand it or doesn't + # yet implement the functionality that was requested. So, the sender is echoing the message + # back. In some cases, the receiver may be able to recover from this by pretending the sender + # had taken some appropriate "null" action. + # + # For example, say `resolve` is received by a level 0 implementation (because a previous call + # or return happened to contain a promise). The level 0 implementation will echo it back as + # `unimplemented`. The original sender can then simply release the cap to which the promise + # had resolved, thus avoiding a leak. + # + # For any message type that introduces a question, if the message comes back unimplemented, + # the original sender may simply treat it as if the question failed with an exception. + # + # In cases where there is no sensible way to react to an `unimplemented` message (without + # resource leaks or other serious problems), the connection may need to be aborted. This is + # a gray area; different implementations may take different approaches. + + abort @1 :Exception; + # Sent when a connection is being aborted due to an unrecoverable error. This could be e.g. + # because the sender received an invalid or nonsensical message (`isCallersFault` is true) or + # because the sender had an internal error (`isCallersFault` is false). The sender will shut + # down the outgoing half of the connection after `abort` and will completely close the + # connection shortly thereafter (it's up to the sender how much of a time buffer they want to + # offer for the client to receive the `abort` before the connection is reset). + + # Level 0 features ----------------------------------------------- + + bootstrap @8 :Bootstrap; # Request the peer's bootstrap interface. + call @2 :Call; # Begin a method call. + return @3 :Return; # Complete a method call. + finish @4 :Finish; # Release a returned answer / cancel a call. + + # Level 1 features ----------------------------------------------- + + resolve @5 :Resolve; # Resolve a previously-sent promise. + release @6 :Release; # Release a capability so that the remote object can be deallocated. + disembargo @13 :Disembargo; # Lift an embargo used to enforce E-order over promise resolution. + + # Level 2 features ----------------------------------------------- + + obsoleteSave @7 :AnyPointer; + # Obsolete request to save a capability, resulting in a SturdyRef. This has been replaced + # by the `Persistent` interface defined in `persistent.capnp`. This operation was never + # implemented. + + obsoleteDelete @9 :AnyPointer; + # Obsolete way to delete a SturdyRef. This operation was never implemented. + + # Level 3 features ----------------------------------------------- + + provide @10 :Provide; # Provide a capability to a third party. + accept @11 :Accept; # Accept a capability provided by a third party. + + # Level 4 features ----------------------------------------------- + + join @12 :Join; # Directly connect to the common root of two or more proxied caps. + } +} + +# Level 0 message types ---------------------------------------------- + +struct Bootstrap { + # **(level 0)** + # + # Get the "bootstrap" interface exported by the remote vat. + # + # For level 0, 1, and 2 implementations, the "bootstrap" interface is simply the main interface + # exported by a vat. If the vat acts as a server fielding connections from clients, then the + # bootstrap interface defines the basic functionality available to a client when it connects. + # The exact interface definition obviously depends on the application. + # + # We call this a "bootstrap" because in an ideal Cap'n Proto world, bootstrap interfaces would + # never be used. In such a world, any time you connect to a new vat, you do so because you + # received an introduction from some other vat (see `ThirdPartyCapId`). Thus, the first message + # you send is `Accept`, and further communications derive from there. `Bootstrap` is not used. + # + # In such an ideal world, DNS itself would support Cap'n Proto -- performing a DNS lookup would + # actually return a new Cap'n Proto capability, thus introducing you to the target system via + # level 3 RPC. Applications would receive the capability to talk to DNS in the first place as + # an initial endowment or part of a Powerbox interaction. Therefore, an app can form arbitrary + # connections without ever using `Bootstrap`. + # + # Of course, in the real world, DNS is not Cap'n-Proto-based, and we don't want Cap'n Proto to + # require a whole new internet infrastructure to be useful. Therefore, we offer bootstrap + # interfaces as a way to get up and running without a level 3 introduction. Thus, bootstrap + # interfaces are used to "bootstrap" from other, non-Cap'n-Proto-based means of service discovery, + # such as legacy DNS. + # + # Note that a vat need not provide a bootstrap interface, and in fact many vats (especially those + # acting as clients) do not. In this case, the vat should either reply to `Bootstrap` with a + # `Return` indicating an exception, or should return a dummy capability with no methods. + + questionId @0 :QuestionId; + # A new question ID identifying this request, which will eventually receive a Return message + # containing the restored capability. + + deprecatedObjectId @1 :AnyPointer; + # ** DEPRECATED ** + # + # A Vat may export multiple bootstrap interfaces. In this case, `deprecatedObjectId` specifies + # which one to return. If this pointer is null, then the default bootstrap interface is returned. + # + # As of verison 0.5, use of this field is deprecated. If a service wants to export multiple + # bootstrap interfaces, it should instead define a single bootstarp interface that has methods + # that return each of the other interfaces. + # + # **History** + # + # In the first version of Cap'n Proto RPC (0.4.x) the `Bootstrap` message was called `Restore`. + # At the time, it was thought that this would eventually serve as the way to restore SturdyRefs + # (level 2). Meanwhile, an application could offer its "main" interface on a well-known + # (non-secret) SturdyRef. + # + # Since level 2 RPC was not implemented at the time, the `Restore` message was in practice only + # used to obtain the main interface. Since most applications had only one main interface that + # they wanted to restore, they tended to designate this with a null `objectId`. + # + # Unfortunately, the earliest version of the EZ RPC interfaces set a precedent of exporting + # multiple main interfaces by allowing them to be exported under string names. In this case, + # `objectId` was a Text value specifying the name. + # + # All of this proved problematic for several reasons: + # + # - The arrangement assumed that a client wishing to restore a SturdyRef would know exactly what + # machine to connect to and would be able to immediately restore a SturdyRef on connection. + # However, in practice, the ability to restore SturdyRefs is itself a capability that may + # require going through an authentication process to obtain. Thus, it makes more sense to + # define a "restorer service" as a full Cap'n Proto interface. If this restorer interface is + # offered as the vat's bootstrap interface, then this is equivalent to the old arrangement. + # + # - Overloading "Restore" for the purpose of obtaining well-known capabilities encouraged the + # practice of exporting singleton services with string names. If singleton services are desired, + # it is better to have one main interface that has methods that can be used to obtain each + # service, in order to get all the usual benefits of schemas and type checking. + # + # - Overloading "Restore" also had a security problem: Often, "main" or "well-known" + # capabilities exported by a vat are in fact not public: they are intended to be accessed only + # by clients who are capable of forming a connection to the vat. This can lead to trouble if + # the client itself has other clients and wishes to foward some `Restore` requests from those + # external clients -- it has to be very careful not to allow through `Restore` requests + # addressing the default capability. + # + # For example, consider the case of a sandboxed Sandstorm application and its supervisor. The + # application exports a default capability to its supervisor that provides access to + # functionality that only the supervisor is supposed to access. Meanwhile, though, applications + # may publish other capabilities that may be persistent, in which case the application needs + # to field `Restore` requests that could come from anywhere. These requests of course have to + # pass through the supervisor, as all communications with the outside world must. But, the + # supervisor has to be careful not to honor an external request addressing the application's + # default capability, since this capability is privileged. Unfortunately, the default + # capability cannot be given an unguessable name, because then the supervisor itself would not + # be able to address it! + # + # As of Cap'n Proto 0.5, `Restore` has been renamed to `Bootstrap` and is no longer planned for + # use in restoring SturdyRefs. + # + # Note that 0.4 also defined a message type called `Delete` that, like `Restore`, addressed a + # SturdyRef, but indicated that the client would not restore the ref again in the future. This + # operation was never implemented, so it was removed entirely. If a "delete" operation is desired, + # it should exist as a method on the same interface that handles restoring SturdyRefs. However, + # the utility of such an operation is questionable. You wouldn't be able to rely on it for + # garbage collection since a client could always disappear permanently without remembering to + # delete all its SturdyRefs, thus leaving them dangling forever. Therefore, it is advisable to + # design systems such that SturdyRefs never represent "owned" pointers. + # + # For example, say a SturdyRef points to an image file hosted on some server. That image file + # should also live inside a collection (a gallery, perhaps) hosted on the same server, owned by + # a user who can delete the image at any time. If the user deletes the image, the SturdyRef + # stops working. On the other hand, if the SturdyRef is discarded, this has no effect on the + # existence of the image in its collection. +} + +struct Call { + # **(level 0)** + # + # Message type initiating a method call on a capability. + + questionId @0 :QuestionId; + # A number, chosen by the caller, that identifies this call in future messages. This number + # must be different from all other calls originating from the same end of the connection (but + # may overlap with question IDs originating from the opposite end). A fine strategy is to use + # sequential question IDs, but the recipient should not assume this. + # + # A question ID can be reused once both: + # - A matching Return has been received from the callee. + # - A matching Finish has been sent from the caller. + + target @1 :MessageTarget; + # The object that should receive this call. + + interfaceId @2 :UInt64; + # The type ID of the interface being called. Each capability may implement multiple interfaces. + + methodId @3 :UInt16; + # The ordinal number of the method to call within the requested interface. + + allowThirdPartyTailCall @8 :Bool = false; + # Indicates whether or not the receiver is allowed to send a `Return` containing + # `acceptFromThirdParty`. Level 3 implementations should set this true. Otherwise, the callee + # will have to proxy the return in the case of a tail call to a third-party vat. + + params @4 :Payload; + # The call parameters. `params.content` is a struct whose fields correspond to the parameters of + # the method. + + sendResultsTo :union { + # Where should the return message be sent? + + caller @5 :Void; + # Send the return message back to the caller (the usual). + + yourself @6 :Void; + # **(level 1)** + # + # Don't actually return the results to the sender. Instead, hold on to them and await + # instructions from the sender regarding what to do with them. In particular, the sender + # may subsequently send a `Return` for some other call (which the receiver had previously made + # to the sender) with `takeFromOtherQuestion` set. The results from this call are then used + # as the results of the other call. + # + # When `yourself` is used, the receiver must still send a `Return` for the call, but sets the + # field `resultsSentElsewhere` in that `Return` rather than including the results. + # + # This feature can be used to implement tail calls in which a call from Vat A to Vat B ends up + # returning the result of a call from Vat B back to Vat A. + # + # In particular, the most common use case for this feature is when Vat A makes a call to a + # promise in Vat B, and then that promise ends up resolving to a capability back in Vat A. + # Vat B must forward all the queued calls on that promise back to Vat A, but can set `yourself` + # in the calls so that the results need not pass back through Vat B. + # + # For example: + # - Alice, in Vat A, call foo() on Bob in Vat B. + # - Alice makes a pipelined call bar() on the promise returned by foo(). + # - Later on, Bob resolves the promise from foo() to point at Carol, who lives in Vat A (next + # to Alice). + # - Vat B dutifully forwards the bar() call to Carol. Let us call this forwarded call bar'(). + # Notice that bar() and bar'() are travelling in opposite directions on the same network + # link. + # - The `Call` for bar'() has `sendResultsTo` set to `yourself`, with the value being the + # question ID originally assigned to the bar() call. + # - Vat A receives bar'() and delivers it to Carol. + # - When bar'() returns, Vat A immediately takes the results and returns them from bar(). + # - Meanwhile, Vat A sends a `Return` for bar'() to Vat B, with `resultsSentElsewhere` set in + # place of results. + # - Vat A sends a `Finish` for that call to Vat B. + # - Vat B receives the `Return` for bar'() and sends a `Return` for bar(), with + # `receivedFromYourself` set in place of the results. + # - Vat B receives the `Finish` for bar() and sends a `Finish` to bar'(). + + thirdParty @7 :RecipientId; + # **(level 3)** + # + # The call's result should be returned to a different vat. The receiver (the callee) expects + # to receive an `Accept` message from the indicated vat, and should return the call's result + # to it, rather than to the sender of the `Call`. + # + # This operates much like `yourself`, above, except that Carol is in a separate Vat C. `Call` + # messages are sent from Vat A -> Vat B and Vat B -> Vat C. A `Return` message is sent from + # Vat B -> Vat A that contains `acceptFromThirdParty` in place of results. When Vat A sends + # an `Accept` to Vat C, it receives back a `Return` containing the call's actual result. Vat C + # also sends a `Return` to Vat B with `resultsSentElsewhere`. + } +} + +struct Return { + # **(level 0)** + # + # Message type sent from callee to caller indicating that the call has completed. + + answerId @0 :AnswerId; + # Equal to the QuestionId of the corresponding `Call` message. + + releaseParamCaps @1 :Bool = true; + # If true, all capabilities that were in the params should be considered released. The sender + # must not send separate `Release` messages for them. Level 0 implementations in particular + # should always set this true. This defaults true because if level 0 implementations forget to + # set it they'll never notice (just silently leak caps), but if level >=1 implementations forget + # to set it to false they'll quickly get errors. + + union { + results @2 :Payload; + # The result. + # + # For regular method calls, `results.content` points to the result struct. + # + # For a `Return` in response to an `Accept`, `results` contains a single capability (rather + # than a struct), and `results.content` is just a capability pointer with index 0. A `Finish` + # is still required in this case. + + exception @3 :Exception; + # Indicates that the call failed and explains why. + + canceled @4 :Void; + # Indicates that the call was canceled due to the caller sending a Finish message + # before the call had completed. + + resultsSentElsewhere @5 :Void; + # This is set when returning from a `Call` that had `sendResultsTo` set to something other + # than `caller`. + + takeFromOtherQuestion @6 :QuestionId; + # The sender has also sent (before this message) a `Call` with the given question ID and with + # `sendResultsTo.yourself` set, and the results of that other call should be used as the + # results here. + + acceptFromThirdParty @7 :ThirdPartyCapId; + # **(level 3)** + # + # The caller should contact a third-party vat to pick up the results. An `Accept` message + # sent to the vat will return the result. This pairs with `Call.sendResultsTo.thirdParty`. + # It should only be used if the corresponding `Call` had `allowThirdPartyTailCall` set. + } +} + +struct Finish { + # **(level 0)** + # + # Message type sent from the caller to the callee to indicate: + # 1) The questionId will no longer be used in any messages sent by the callee (no further + # pipelined requests). + # 2) If the call has not returned yet, the caller no longer cares about the result. If nothing + # else cares about the result either (e.g. there are no other outstanding calls pipelined on + # the result of this one) then the callee may wish to immediately cancel the operation and + # send back a Return message with "canceled" set. However, implementations are not required + # to support premature cancellation -- instead, the implementation may wait until the call + # actually completes and send a normal `Return` message. + # + # TODO(someday): Should we separate (1) and implicitly releasing result capabilities? It would be + # possible and useful to notify the server that it doesn't need to keep around the response to + # service pipeline requests even though the caller still wants to receive it / hasn't yet + # finished processing it. It could also be useful to notify the server that it need not marshal + # the results because the caller doesn't want them anyway, even if the caller is still sending + # pipelined calls, although this seems less useful (just saving some bytes on the wire). + + questionId @0 :QuestionId; + # ID of the call whose result is to be released. + + releaseResultCaps @1 :Bool = true; + # If true, all capabilities that were in the results should be considered released. The sender + # must not send separate `Release` messages for them. Level 0 implementations in particular + # should always set this true. This defaults true because if level 0 implementations forget to + # set it they'll never notice (just silently leak caps), but if level >=1 implementations forget + # set it false they'll quickly get errors. +} + +# Level 1 message types ---------------------------------------------- + +struct Resolve { + # **(level 1)** + # + # Message type sent to indicate that a previously-sent promise has now been resolved to some other + # object (possibly another promise) -- or broken, or canceled. + # + # Keep in mind that it's possible for a `Resolve` to be sent to a level 0 implementation that + # doesn't implement it. For example, a method call or return might contain a capability in the + # payload. Normally this is fine even if the receiver is level 0, because they will implicitly + # release all such capabilities on return / finish. But if the cap happens to be a promise, then + # a follow-up `Resolve` may be sent regardless of this release. The level 0 receiver will reply + # with an `unimplemented` message, and the sender (of the `Resolve`) can respond to this as if the + # receiver had immediately released any capability to which the promise resolved. + # + # When implementing promise resolution, it's important to understand how embargos work and the + # tricky case of the Tribble 4-way race condition. See the comments for the Disembargo message, + # below. + + promiseId @0 :ExportId; + # The ID of the promise to be resolved. + # + # Unlike all other instances of `ExportId` sent from the exporter, the `Resolve` message does + # _not_ increase the reference count of `promiseId`. In fact, it is expected that the receiver + # will release the export soon after receiving `Resolve`, and the sender will not send this + # `ExportId` again until it has been released and recycled. + # + # When an export ID sent over the wire (e.g. in a `CapDescriptor`) is indicated to be a promise, + # this indicates that the sender will follow up at some point with a `Resolve` message. If the + # same `promiseId` is sent again before `Resolve`, still only one `Resolve` is sent. If the + # same ID is sent again later _after_ a `Resolve`, it can only be because the export's + # reference count hit zero in the meantime and the ID was re-assigned to a new export, therefore + # this later promise does _not_ correspond to the earlier `Resolve`. + # + # If a promise ID's reference count reaches zero before a `Resolve` is sent, the `Resolve` + # message may or may not still be sent (the `Resolve` may have already been in-flight when + # `Release` was sent, but if the `Release` is received before `Resolve` then there is no longer + # any reason to send a `Resolve`). Thus a `Resolve` may be received for a promise of which + # the receiver has no knowledge, because it already released it earlier. In this case, the + # receiver should simply release the capability to which the promise resolved. + + union { + cap @1 :CapDescriptor; + # The object to which the promise resolved. + # + # The sender promises that from this point forth, until `promiseId` is released, it shall + # simply forward all messages to the capability designated by `cap`. This is true even if + # `cap` itself happens to desigate another promise, and that other promise later resolves -- + # messages sent to `promiseId` shall still go to that other promise, not to its resolution. + # This is important in the case that the receiver of the `Resolve` ends up sending a + # `Disembargo` message towards `promiseId` in order to control message ordering -- that + # `Disembargo` really needs to reflect back to exactly the object designated by `cap` even + # if that object is itself a promise. + + exception @2 :Exception; + # Indicates that the promise was broken. + } +} + +struct Release { + # **(level 1)** + # + # Message type sent to indicate that the sender is done with the given capability and the receiver + # can free resources allocated to it. + + id @0 :ImportId; + # What to release. + + referenceCount @1 :UInt32; + # The amount by which to decrement the reference count. The export is only actually released + # when the reference count reaches zero. +} + +struct Disembargo { + # **(level 1)** + # + # Message sent to indicate that an embargo on a recently-resolved promise may now be lifted. + # + # Embargos are used to enforce E-order in the presence of promise resolution. That is, if an + # application makes two calls foo() and bar() on the same capability reference, in that order, + # the calls should be delivered in the order in which they were made. But if foo() is called + # on a promise, and that promise happens to resolve before bar() is called, then the two calls + # may travel different paths over the network, and thus could arrive in the wrong order. In + # this case, the call to `bar()` must be embargoed, and a `Disembargo` message must be sent along + # the same path as `foo()` to ensure that the `Disembargo` arrives after `foo()`. Once the + # `Disembargo` arrives, `bar()` can then be delivered. + # + # There are two particular cases where embargos are important. Consider object Alice, in Vat A, + # who holds a promise P, pointing towards Vat B, that eventually resolves to Carol. The two + # cases are: + # - Carol lives in Vat A, i.e. next to Alice. In this case, Vat A needs to send a `Disembargo` + # message that echos through Vat B and back, to ensure that all pipelined calls on the promise + # have been delivered. + # - Carol lives in a different Vat C. When the promise resolves, a three-party handoff occurs + # (see `Provide` and `Accept`, which constitute level 3 of the protocol). In this case, we + # piggyback on the state that has already been set up to handle the handoff: the `Accept` + # message (from Vat A to Vat C) is embargoed, as are all pipelined messages sent to it, while + # a `Disembargo` message is sent from Vat A through Vat B to Vat C. See `Accept.embargo` for + # an example. + # + # Note that in the case where Carol actually lives in Vat B (i.e., the same vat that the promise + # already pointed at), no embargo is needed, because the pipelined calls are delivered over the + # same path as the later direct calls. + # + # Keep in mind that promise resolution happens both in the form of Resolve messages as well as + # Return messages (which resolve PromisedAnswers). Embargos apply in both cases. + # + # An alternative strategy for enforcing E-order over promise resolution could be for Vat A to + # implement the embargo internally. When Vat A is notified of promise resolution, it could + # send a dummy no-op call to promise P and wait for it to complete. Until that call completes, + # all calls to the capability are queued locally. This strategy works, but is pessimistic: + # in the three-party case, it requires an A -> B -> C -> B -> A round trip before calls can start + # being delivered directly to from Vat A to Vat C. The `Disembargo` message allows latency to be + # reduced. (In the two-party loopback case, the `Disembargo` message is just a more explicit way + # of accomplishing the same thing as a no-op call, but isn't any faster.) + # + # *The Tribble 4-way Race Condition* + # + # Any implementation of promise resolution and embargos must be aware of what we call the + # "Tribble 4-way race condition", after Dean Tribble, who explained the problem in a lively + # Friam meeting. + # + # Embargos are designed to work in the case where a two-hop path is being shortened to one hop. + # But sometimes there are more hops. Imagine that Alice has a reference to a remote promise P1 + # that eventually resolves to _another_ remote promise P2 (in a third vat), which _at the same + # time_ happens to resolve to Bob (in a fourth vat). In this case, we're shortening from a 3-hop + # path (with four parties) to a 1-hop path (Alice -> Bob). + # + # Extending the embargo/disembargo protocol to be able to shorted multiple hops at once seems + # difficult. Instead, we make a rule that prevents this case from coming up: + # + # One a promise P has been resolved to a remove object reference R, then all further messages + # received addressed to P will be forwarded strictly to R. Even if it turns out later that R is + # itself a promise, and has resolved to some other object Q, messages sent to P will still be + # forwarded to R, not directly to Q (R will of course further forward the messages to Q). + # + # This rule does not cause a significant performance burden because once P has resolved to R, it + # is expected that people sending messages to P will shortly start sending them to R instead and + # drop P. P is at end-of-life anyway, so it doesn't matter if it ignores chances to further + # optimize its path. + + target @0 :MessageTarget; + # What is to be disembargoed. + + using EmbargoId = UInt32; + # Used in `senderLoopback` and `receiverLoopback`, below. + + context :union { + senderLoopback @1 :EmbargoId; + # The sender is requesting a disembargo on a promise that is known to resolve back to a + # capability hosted by the sender. As soon as the receiver has echoed back all pipelined calls + # on this promise, it will deliver the Disembargo back to the sender with `receiverLoopback` + # set to the same value as `senderLoopback`. This value is chosen by the sender, and since + # it is also consumed be the sender, the sender can use whatever strategy it wants to make sure + # the value is unambiguous. + # + # The receiver must verify that the target capability actually resolves back to the sender's + # vat. Otherwise, the sender has committed a protocol error and should be disconnected. + + receiverLoopback @2 :EmbargoId; + # The receiver previously sent a `senderLoopback` Disembargo towards a promise resolving to + # this capability, and that Disembargo is now being echoed back. + + accept @3 :Void; + # **(level 3)** + # + # The sender is requesting a disembargo on a promise that is known to resolve to a third-party + # capability that the sender is currently in the process of accepting (using `Accept`). + # The receiver of this `Disembargo` has an outstanding `Provide` on said capability. The + # receiver should now send a `Disembargo` with `provide` set to the question ID of that + # `Provide` message. + # + # See `Accept.embargo` for an example. + + provide @4 :QuestionId; + # **(level 3)** + # + # The sender is requesting a disembargo on a capability currently being provided to a third + # party. The question ID identifies the `Provide` message previously sent by the sender to + # this capability. On receipt, the receiver (the capability host) shall release the embargo + # on the `Accept` message that it has received from the third party. See `Accept.embargo` for + # an example. + } +} + +# Level 2 message types ---------------------------------------------- + +# See persistent.capnp. + +# Level 3 message types ---------------------------------------------- + +struct Provide { + # **(level 3)** + # + # Message type sent to indicate that the sender wishes to make a particular capability implemented + # by the receiver available to a third party for direct access (without the need for the third + # party to proxy through the sender). + # + # (In CapTP, `Provide` and `Accept` are methods of the global `NonceLocator` object exported by + # every vat. In Cap'n Proto, we bake this into the core protocol.) + + questionId @0 :QuestionId; + # Question ID to be held open until the recipient has received the capability. A result will be + # returned once the third party has successfully received the capability. The sender must at some + # point send a `Finish` message as with any other call, and that message can be used to cancel the + # whole operation. + + target @1 :MessageTarget; + # What is to be provided to the third party. + + recipient @2 :RecipientId; + # Identity of the third party that is expected to pick up the capability. +} + +struct Accept { + # **(level 3)** + # + # Message type sent to pick up a capability hosted by the receiving vat and provided by a third + # party. The third party previously designated the capability using `Provide`. + # + # This message is also used to pick up a redirected return -- see `Return.redirect`. + + questionId @0 :QuestionId; + # A new question ID identifying this accept message, which will eventually receive a Return + # message containing the provided capability (or the call result in the case of a redirected + # return). + + provision @1 :ProvisionId; + # Identifies the provided object to be picked up. + + embargo @2 :Bool; + # If true, this accept shall be temporarily embargoed. The resulting `Return` will not be sent, + # and any pipelined calls will not be delivered, until the embargo is released. The receiver + # (the capability host) will expect the provider (the vat that sent the `Provide` message) to + # eventually send a `Disembargo` message with the field `context.provide` set to the question ID + # of the original `Provide` message. At that point, the embargo is released and the queued + # messages are delivered. + # + # For example: + # - Alice, in Vat A, holds a promise P, which currently points toward Vat B. + # - Alice calls foo() on P. The `Call` message is sent to Vat B. + # - The promise P in Vat B ends up resolving to Carol, in Vat C. + # - Vat B sends a `Provide` message to Vat C, identifying Vat A as the recipient. + # - Vat B sends a `Resolve` message to Vat A, indicating that the promise has resolved to a + # `ThirdPartyCapId` identifying Carol in Vat C. + # - Vat A sends an `Accept` message to Vat C to pick up the capability. Since Vat A knows that + # it has an outstanding call to the promise, it sets `embargo` to `true` in the `Accept` + # message. + # - Vat A sends a `Disembargo` message to Vat B on promise P, with `context.accept` set. + # - Alice makes a call bar() to promise P, which is now pointing towards Vat C. Alice doesn't + # know anything about the mechanics of promise resolution happening under the hood, but she + # expects that bar() will be delivered after foo() because that is the order in which she + # initiated the calls. + # - Vat A sends the bar() call to Vat C, as a pipelined call on the result of the `Accept` (which + # hasn't returned yet, due to the embargo). Since calls to the newly-accepted capability + # are embargoed, Vat C does not deliver the call yet. + # - At some point, Vat B forwards the foo() call from the beginning of this example on to Vat C. + # - Vat B forwards the `Disembargo` from Vat A on to vat C. It sets `context.provide` to the + # question ID of the `Provide` message it had sent previously. + # - Vat C receives foo() before `Disembargo`, thus allowing it to correctly deliver foo() + # before delivering bar(). + # - Vat C receives `Disembargo` from Vat B. It can now send a `Return` for the `Accept` from + # Vat A, as well as deliver bar(). +} + +# Level 4 message types ---------------------------------------------- + +struct Join { + # **(level 4)** + # + # Message type sent to implement E.join(), which, given a number of capabilities that are + # expected to be equivalent, finds the underlying object upon which they all agree and forms a + # direct connection to it, skipping any proxies that may have been constructed by other vats + # while transmitting the capability. See: + # http://erights.org/elib/equality/index.html + # + # Note that this should only serve to bypass fully-transparent proxies -- proxies that were + # created merely for convenience, without any intention of hiding the underlying object. + # + # For example, say Bob holds two capabilities hosted by Alice and Carol, but he expects that both + # are simply proxies for a capability hosted elsewhere. He then issues a join request, which + # operates as follows: + # - Bob issues Join requests on both Alice and Carol. Each request contains a different piece + # of the JoinKey. + # - Alice is proxying a capability hosted by Dana, so forwards the request to Dana's cap. + # - Dana receives the first request and sees that the JoinKeyPart is one of two. She notes that + # she doesn't have the other part yet, so she records the request and responds with a + # JoinResult. + # - Alice relays the JoinAswer back to Bob. + # - Carol is also proxying a capability from Dana, and so forwards her Join request to Dana as + # well. + # - Dana receives Carol's request and notes that she now has both parts of a JoinKey. She + # combines them in order to form information needed to form a secure connection to Bob. She + # also responds with another JoinResult. + # - Bob receives the responses from Alice and Carol. He uses the returned JoinResults to + # determine how to connect to Dana and attempts to form the connection. Since Bob and Dana now + # agree on a secret key that neither Alice nor Carol ever saw, this connection can be made + # securely even if Alice or Carol is conspiring against the other. (If Alice and Carol are + # conspiring _together_, they can obviously reproduce the key, but this doesn't matter because + # the whole point of the join is to verify that Alice and Carol agree on what capability they + # are proxying.) + # + # If the two capabilities aren't actually proxies of the same object, then the join requests + # will come back with conflicting `hostId`s and the join will fail before attempting to form any + # connection. + + questionId @0 :QuestionId; + # Question ID used to respond to this Join. (Note that this ID only identifies one part of the + # request for one hop; each part has a different ID and relayed copies of the request have + # (probably) different IDs still.) + # + # The receiver will reply with a `Return` whose `results` is a JoinResult. This `JoinResult` + # is relayed from the joined object's host, possibly with transformation applied as needed + # by the network. + # + # Like any return, the result must be released using a `Finish`. However, this release + # should not occur until the joiner has either successfully connected to the joined object. + # Vats relaying a `Join` message similarly must not release the result they receive until the + # return they relayed back towards the joiner has itself been released. This allows the + # joined object's host to detect when the Join operation is canceled before completing -- if + # it receives a `Finish` for one of the join results before the joiner successfully + # connects. It can then free any resources it had allocated as part of the join. + + target @1 :MessageTarget; + # The capability to join. + + keyPart @2 :JoinKeyPart; + # A part of the join key. These combine to form the complete join key, which is used to establish + # a direct connection. + + # TODO(before implementing): Change this so that multiple parts can be sent in a single Join + # message, so that if multiple join parts are going to cross the same connection they can be sent + # together, so that the receive can potentially optimize its handling of them. In the case where + # all parts are bundled together, should the recipient be expected to simply return a cap, so + # that the caller can immediately start pipelining to it? +} + +# ======================================================================================== +# Common structures used in messages + +struct MessageTarget { + # The target of a `Call` or other messages that target a capability. + + union { + importedCap @0 :ImportId; + # This message is to a capability or promise previously imported by the caller (exported by + # the receiver). + + promisedAnswer @1 :PromisedAnswer; + # This message is to a capability that is expected to be returned by another call that has not + # yet been completed. + # + # At level 0, this is supported only for addressing the result of a previous `Bootstrap`, so + # that initial startup doesn't require a round trip. + } +} + +struct Payload { + # Represents some data structure that might contain capabilities. + + content @0 :AnyPointer; + # Some Cap'n Proto data structure. Capability pointers embedded in this structure index into + # `capTable`. + + capTable @1 :List(CapDescriptor); + # Descriptors corresponding to the cap pointers in `content`. +} + +struct CapDescriptor { + # **(level 1)** + # + # When an application-defined type contains an interface pointer, that pointer contains an index + # into the message's capability table -- i.e. the `capTable` part of the `Payload`. Each + # capability in the table is represented as a `CapDescriptor`. The runtime API should not reveal + # the CapDescriptor directly to the application, but should instead wrap it in some kind of + # callable object with methods corresponding to the interface that the capability implements. + # + # Keep in mind that `ExportIds` in a `CapDescriptor` are subject to reference counting. See the + # description of `ExportId`. + + union { + none @0 :Void; + # There is no capability here. This `CapDescriptor` should not appear in the payload content. + # A `none` CapDescriptor can be generated when an application inserts a capability into a + # message and then later changes its mind and removes it -- rewriting all of the other + # capability pointers may be hard, so instead a tombstone is left, similar to the way a removed + # struct or list instance is zeroed out of the message but the space is not reclaimed. + # Hopefully this is unusual. + + senderHosted @1 :ExportId; + # A capability newly exported by the sender. This is the ID of the new capability in the + # sender's export table (receiver's import table). + + senderPromise @2 :ExportId; + # A promise that the sender will resolve later. The sender will send exactly one Resolve + # message at a future point in time to replace this promise. Note that even if the same + # `senderPromise` is received multiple times, only one `Resolve` is sent to cover all of + # them. If `senderPromise` is released before the `Resolve` is sent, the sender (of this + # `CapDescriptor`) may choose not to send the `Resolve` at all. + + receiverHosted @3 :ImportId; + # A capability (or promise) previously exported by the receiver (imported by the sender). + + receiverAnswer @4 :PromisedAnswer; + # A capability expected to be returned in the results of a currently-outstanding call posed + # by the sender. + + thirdPartyHosted @5 :ThirdPartyCapDescriptor; + # **(level 3)** + # + # A capability that lives in neither the sender's nor the receiver's vat. The sender needs + # to form a direct connection to a third party to pick up the capability. + # + # Level 1 and 2 implementations that receive a `thirdPartyHosted` may simply send calls to its + # `vine` instead. + } +} + +struct PromisedAnswer { + # **(mostly level 1)** + # + # Specifies how to derive a promise from an unanswered question, by specifying the path of fields + # to follow from the root of the eventual result struct to get to the desired capability. Used + # to address method calls to a not-yet-returned capability or to pass such a capability as an + # input to some other method call. + # + # Level 0 implementations must support `PromisedAnswer` only for the case where the answer is + # to a `Bootstrap` message. In this case, `path` is always empty since `Bootstrap` always returns + # a raw capability. + + questionId @0 :QuestionId; + # ID of the question (in the sender's question table / receiver's answer table) whose answer is + # expected to contain the capability. + + transform @1 :List(Op); + # Operations / transformations to apply to the result in order to get the capability actually + # being addressed. E.g. if the result is a struct and you want to call a method on a capability + # pointed to by a field of the struct, you need a `getPointerField` op. + + struct Op { + union { + noop @0 :Void; + # Does nothing. This member is mostly defined so that we can make `Op` a union even + # though (as of this writing) only one real operation is defined. + + getPointerField @1 :UInt16; + # Get a pointer field within a struct. The number is an index into the pointer section, NOT + # a field ordinal, so that the receiver does not need to understand the schema. + + # TODO(someday): We could add: + # - For lists, the ability to address every member of the list, or a slice of the list, the + # result of which would be another list. This is useful for implementing the equivalent of + # a SQL table join (not to be confused with the `Join` message type). + # - Maybe some ability to test a union. + # - Probably not a good idea: the ability to specify an arbitrary script to run on the + # result. We could define a little stack-based language where `Op` specifies one + # "instruction" or transformation to apply. Although this is not a good idea + # (over-engineered), any narrower additions to `Op` should be designed as if this + # were the eventual goal. + } + } +} + +struct ThirdPartyCapDescriptor { + # **(level 3)** + # + # Identifies a capability in a third-party vat that the sender wants the receiver to pick up. + + id @0 :ThirdPartyCapId; + # Identifies the third-party host and the specific capability to accept from it. + + vineId @1 :ExportId; + # A proxy for the third-party object exported by the sender. In CapTP terminology this is called + # a "vine", because it is an indirect reference to the third-party object that snakes through the + # sender vat. This serves two purposes: + # + # * Level 1 and 2 implementations that don't understand how to connect to a third party may + # simply send calls to the vine. Such calls will be forwarded to the third-party by the + # sender. + # + # * Level 3 implementations must release the vine once they have successfully picked up the + # object from the third party. This ensures that the capability is not released by the sender + # prematurely. + # + # The sender will close the `Provide` request that it has sent to the third party as soon as + # it receives either a `Call` or a `Release` message directed at the vine. +} + +struct Exception { + # **(level 0)** + # + # Describes an arbitrary error that prevented an operation (e.g. a call) from completing. + # + # Cap'n Proto exceptions always indicate that something went wrong. In other words, in a fantasy + # world where everything always works as expected, no exceptions would ever be thrown. Clients + # should only ever catch exceptions as a means to implement fault-tolerance, where "fault" can + # mean: + # - Bugs. + # - Invalid input. + # - Configuration errors. + # - Network problems. + # - Insufficient resources. + # - Version skew (unimplemented functionality). + # - Other logistical problems. + # + # Exceptions should NOT be used to flag application-specific conditions that a client is expected + # to handle in an application-specific way. Put another way, in the Cap'n Proto world, + # "checked exceptions" (where an interface explicitly defines the exceptions it throws and + # clients are forced by the type system to handle those exceptions) do NOT make sense. + + reason @0 :Text; + # Human-readable failure description. + + type @3 :Type; + # The type of the error. The purpose of this enum is not to describe the error itself, but + # rather to describe how the client might want to respond to the error. + + enum Type { + failed @0; + # A generic problem occurred, and it is believed that if the operation were repeated without + # any change in the state of the world, the problem would occur again. + # + # A client might respond to this error by logging it for investigation by the developer and/or + # displaying it to the user. + + overloaded @1; + # The request was rejected due to a temporary lack of resources. + # + # Examples include: + # - There's not enough CPU time to keep up with incoming requests, so some are rejected. + # - The server ran out of RAM or disk space during the request. + # - The operation timed out (took significantly longer than it should have). + # + # A client might respond to this error by scheduling to retry the operation much later. The + # client should NOT retry again immediately since this would likely exacerbate the problem. + + disconnected @2; + # The method failed because a connection to some necessary capability was lost. + # + # Examples include: + # - The client introduced the server to a third-party capability, the connection to that third + # party was subsequently lost, and then the client requested that the server use the dead + # capability for something. + # - The client previously requested that the server obtain a capability from some third party. + # The server returned a capability to an object wrapping the third-party capability. Later, + # the server's connection to the third party was lost. + # - The capability has been revoked. Revocation does not necessarily mean that the client is + # no longer authorized to use the capability; it is often used simply as a way to force the + # client to repeat the setup process, perhaps to efficiently move them to a new back-end or + # get them to recognize some other change that has occurred. + # + # A client should normally respond to this error by releasing all capabilities it is currently + # holding related to the one it called and then re-creating them by restoring SturdyRefs and/or + # repeating the method calls used to create them originally. In other words, disconnect and + # start over. This should in turn cause the server to obtain a new copy of the capability that + # it lost, thus making everything work. + # + # If the client receives another `disconnencted` error in the process of rebuilding the + # capability and retrying the call, it should treat this as an `overloaded` error: the network + # is currently unreliable, possibly due to load or other temporary issues. + + unimplemented @3; + # The server doesn't implement the requested method. If there is some other method that the + # client could call (perhaps an older and/or slower interface), it should try that instead. + # Otherwise, this should be treated like `failed`. + } + + obsoleteIsCallersFault @1 :Bool; + # OBSOLETE. Ignore. + + obsoleteDurability @2 :UInt16; + # OBSOLETE. See `type` instead. +} + +# ======================================================================================== +# Network-specific Parameters +# +# Some parts of the Cap'n Proto RPC protocol are not specified here because different vat networks +# may wish to use different approaches to solving them. For example, on the public internet, you +# may want to authenticate vats using public-key cryptography, but on a local intranet with trusted +# infrastructure, you may be happy to authenticate based on network address only, or some other +# lightweight mechanism. +# +# To accommodate this, we specify several "parameter" types. Each type is defined here as an +# alias for `AnyPointer`, but a specific network will want to define a specific set of types to use. +# All vats in a vat network must agree on these parameters in order to be able to communicate. +# Inter-network communication can be accomplished through "gateways" that perform translation +# between the primitives used on each network; these gateways may need to be deeply stateful, +# depending on the translations they perform. +# +# For interaction over the global internet between parties with no other prior arrangement, a +# particular set of bindings for these types is defined elsewhere. (TODO(someday): Specify where +# these common definitions live.) +# +# Another common network type is the two-party network, in which one of the parties typically +# interacts with the outside world entirely through the other party. In such a connection between +# Alice and Bob, all objects that exist on Bob's other networks appear to Alice as if they were +# hosted by Bob himself, and similarly all objects on Alice's network (if she even has one) appear +# to Bob as if they were hosted by Alice. This network type is interesting because from the point +# of view of a simple application that communicates with only one other party via the two-party +# protocol, there are no three-party interactions at all, and joins are unusually simple to +# implement, so implementing at level 4 is barely more complicated than implementing at level 1. +# Moreover, if you pair an app implementing the two-party network with a container that implements +# some other network, the app can then participate on the container's network just as if it +# implemented that network directly. The types used by the two-party network are defined in +# `rpc-twoparty.capnp`. +# +# The things that we need to parameterize are: +# - How to store capabilities long-term without holding a connection open (mostly level 2). +# - How to authenticate vats in three-party introductions (level 3). +# - How to implement `Join` (level 4). +# +# Persistent references +# --------------------- +# +# **(mostly level 2)** +# +# We want to allow some capabilities to be stored long-term, even if a connection is lost and later +# recreated. ExportId is a short-term identifier that is specific to a connection, so it doesn't +# help here. We need a way to specify long-term identifiers, as well as a strategy for +# reconnecting to a referenced capability later. +# +# Three-party interactions +# ------------------------ +# +# **(level 3)** +# +# In cases where more than two vats are interacting, we have situations where VatA holds a +# capability hosted by VatB and wants to send that capability to VatC. This can be accomplished +# by VatA proxying requests on the new capability, but doing so has two big problems: +# - It's inefficient, requiring an extra network hop. +# - If VatC receives another capability to the same object from VatD, it is difficult for VatC to +# detect that the two capabilities are really the same and to implement the E "join" operation, +# which is necessary for certain four-or-more-party interactions, such as the escrow pattern. +# See: http://www.erights.org/elib/equality/grant-matcher/index.html +# +# Instead, we want a way for VatC to form a direct, authenticated connection to VatB. +# +# Join +# ---- +# +# **(level 4)** +# +# The `Join` message type and corresponding operation arranges for a direct connection to be formed +# between the joiner and the host of the joined object, and this connection must be authenticated. +# Thus, the details are network-dependent. + +using SturdyRef = AnyPointer; +# **(level 2)** +# +# Identifies a persisted capability that can be restored in the future. How exactly a SturdyRef +# is restored to a live object is specified along with the SturdyRef definition (i.e. not by +# rpc.capnp). +# +# Generally a SturdyRef needs to specify three things: +# - How to reach the vat that can restore the ref (e.g. a hostname or IP address). +# - How to authenticate the vat after connecting (e.g. a public key fingerprint). +# - The identity of a specific object hosted by the vat. Generally, this is an opaque pointer whose +# format is defined by the specific vat -- the client has no need to inspect the object ID. +# It is important that the objec ID be unguessable if the object is not public (and objects +# should almost never be public). +# +# The above are only suggestions. Some networks might work differently. For example, a private +# network might employ a special restorer service whose sole purpose is to restore SturdyRefs. +# In this case, the entire contents of SturdyRef might be opaque, because they are intended only +# to be forwarded to the restorer service. + +using ProvisionId = AnyPointer; +# **(level 3)** +# +# The information that must be sent in an `Accept` message to identify the object being accepted. +# +# In a network where each vat has a public/private key pair, this could simply be the public key +# fingerprint of the provider vat along with the question ID used in the `Provide` message sent from +# that provider. + +using RecipientId = AnyPointer; +# **(level 3)** +# +# The information that must be sent in a `Provide` message to identify the recipient of the +# capability. +# +# In a network where each vat has a public/private key pair, this could simply be the public key +# fingerprint of the recipient. (CapTP also calls for a nonce to identify the object. In our +# case, the `Provide` message's `questionId` can serve as the nonce.) + +using ThirdPartyCapId = AnyPointer; +# **(level 3)** +# +# The information needed to connect to a third party and accept a capability from it. +# +# In a network where each vat has a public/private key pair, this could be a combination of the +# third party's public key fingerprint, hints on how to connect to the third party (e.g. an IP +# address), and the question ID used in the corresponding `Provide` message sent to that third party +# (used to identify which capability to pick up). + +using JoinKeyPart = AnyPointer; +# **(level 4)** +# +# A piece of a secret key. One piece is sent along each path that is expected to lead to the same +# place. Once the pieces are combined, a direct connection may be formed between the sender and +# the receiver, bypassing any men-in-the-middle along the paths. See the `Join` message type. +# +# The motivation for Joins is discussed under "Supporting Equality" in the "Unibus" protocol +# sketch: http://www.erights.org/elib/distrib/captp/unibus.html +# +# In a network where each vat has a public/private key pair and each vat forms no more than one +# connection to each other vat, Joins will rarely -- perhaps never -- be needed, as objects never +# need to be transparently proxied and references to the same object sent over the same connection +# have the same export ID. Thus, a successful join requires only checking that the two objects +# come from the same connection and have the same ID, and then completes immediately. +# +# However, in networks where two vats may form more than one connection between each other, or +# where proxying of objects occurs, joins are necessary. +# +# Typically, each JoinKeyPart would include a fixed-length data value such that all value parts +# XOR'd together forms a shared secret that can be used to form an encrypted connection between +# the joiner and the joined object's host. Each JoinKeyPart should also include an indication of +# how many parts to expect and a hash of the shared secret (used to match up parts). + +using JoinResult = AnyPointer; +# **(level 4)** +# +# Information returned as the result to a `Join` message, needed by the joiner in order to form a +# direct connection to a joined object. This might simply be the address of the joined object's +# host vat, since the `JoinKey` has already been communicated so the two vats already have a shared +# secret to use to authenticate each other. +# +# The `JoinResult` should also contain information that can be used to detect when the Join +# requests ended up reaching different objects, so that this situation can be detected easily. +# This could be a simple matter of including a sequence number -- if the joiner receives two +# `JoinResult`s with sequence number 0, then they must have come from different objects and the +# whole join is a failure. + +# ======================================================================================== +# Network interface sketch +# +# The interfaces below are meant to be pseudo-code to illustrate how the details of a particular +# vat network might be abstracted away. They are written like Cap'n Proto interfaces, but in +# practice you'd probably define these interfaces manually in the target programming language. A +# Cap'n Proto RPC implementation should be able to use these interfaces without knowing the +# definitions of the various network-specific parameters defined above. + +# interface VatNetwork { +# # Represents a vat network, with the ability to connect to particular vats and receive +# # connections from vats. +# # +# # Note that methods returning a `Connection` may return a pre-existing `Connection`, and the +# # caller is expected to find and share state with existing users of the connection. +# +# # Level 0 features ----------------------------------------------- +# +# connect(vatId :VatId) :Connection; +# # Connect to the given vat. The transport should return a promise that does not +# # resolve until authentication has completed, but allows messages to be pipelined in before +# # that; the transport either queues these messages until authenticated, or sends them encrypted +# # such that only the authentic vat would be able to decrypt them. The latter approach avoids a +# # round trip for authentication. +# +# accept() :Connection; +# # Wait for the next incoming connection and return it. Only connections formed by +# # connect() are returned by this method. +# +# # Level 4 features ----------------------------------------------- +# +# newJoiner(count :UInt32) :NewJoinerResponse; +# # Prepare a new Join operation, which will eventually lead to forming a new direct connection +# # to the host of the joined capability. `count` is the number of capabilities to join. +# +# struct NewJoinerResponse { +# joinKeyParts :List(JoinKeyPart); +# # Key parts to send in Join messages to each capability. +# +# joiner :Joiner; +# # Used to establish the final connection. +# } +# +# interface Joiner { +# addJoinResult(result :JoinResult) :Void; +# # Add a JoinResult received in response to one of the `Join` messages. All `JoinResult`s +# # returned from all paths must be added before trying to connect. +# +# connect() :ConnectionAndProvisionId; +# # Try to form a connection to the joined capability's host, verifying that it has received +# # all of the JoinKeyParts. Once the connection is formed, the caller should send an `Accept` +# # message on it with the specified `ProvisionId` in order to receive the final capability. +# } +# +# acceptConnectionFromJoiner(parts :List(JoinKeyPart), paths :List(VatPath)) +# :ConnectionAndProvisionId; +# # Called on a joined capability's host to receive the connection from the joiner, once all +# # key parts have arrived. The caller should expect to receive an `Accept` message over the +# # connection with the given ProvisionId. +# } +# +# interface Connection { +# # Level 0 features ----------------------------------------------- +# +# send(message :Message) :Void; +# # Send the message. Returns successfully when the message (and all preceding messages) has +# # been acknowledged by the recipient. +# +# receive() :Message; +# # Receive the next message, and acknowledges receipt to the sender. Messages are received in +# # the order in which they are sent. +# +# # Level 3 features ----------------------------------------------- +# +# introduceTo(recipient :Connection) :IntroductionInfo; +# # Call before starting a three-way introduction, assuming a `Provide` message is to be sent on +# # this connection and a `ThirdPartyCapId` is to be sent to `recipient`. +# +# struct IntroductionInfo { +# sendToRecipient :ThirdPartyCapId; +# sendToTarget :RecipientId; +# } +# +# connectToIntroduced(capId :ThirdPartyCapId) :ConnectionAndProvisionId; +# # Given a ThirdPartyCapId received over this connection, connect to the third party. The +# # caller should then send an `Accept` message over the new connection. +# +# acceptIntroducedConnection(recipientId :RecipientId) :Connection; +# # Given a RecipientId received in a `Provide` message on this `Connection`, wait for the +# # recipient to connect, and return the connection formed. Usually, the first message received +# # on the new connection will be an `Accept` message. +# } +# +# struct ConnectionAndProvisionId { +# # **(level 3)** +# +# connection :Connection; +# # Connection on which to issue `Accept` message. +# +# provision :ProvisionId; +# # `ProvisionId` to send in the `Accept` message. +# } diff --git a/capnp-rpc-sync/schema.ml b/capnp-rpc-sync/schema.ml new file mode 100644 index 000000000..9d2d64656 --- /dev/null +++ b/capnp-rpc-sync/schema.ml @@ -0,0 +1,23 @@ +include Rpc_schema.Make(Capnp.BytesMessage) + +module ReaderOps = struct + include Capnp.Runtime.ReaderInc.Make(Capnp.RPC.None(Capnp.BytesMessage)) + + let string_of_pointer = function + | None -> "" + | Some ptr -> + let open Capnp.BytesMessage in + let data = { ptr with Slice.len = 0 } in + let ss = StructStorage.v ~data ~pointers:ptr in + get_text ~default:"" (Some ss) 0 +end + +module BuilderOps = struct + include Capnp.Runtime.BuilderInc.Make(Capnp.RPC.None(Capnp.BytesMessage)) + + let write_string ptr s = + let open Capnp.BytesMessage in + let data = { ptr with Slice.len = 0 } in + let ss = StructStorage.v ~data ~pointers:ptr in + BA_.set_text ss 0 s +end diff --git a/capnp-rpc-sync/service.ml b/capnp-rpc-sync/service.ml new file mode 100644 index 000000000..389e7dcc6 --- /dev/null +++ b/capnp-rpc-sync/service.ml @@ -0,0 +1,91 @@ +open Capnp_core +open Utils + +module Log = Capnp_rpc.Debug.Log + +module Response = Response +module RO_array = Capnp_rpc.RO_array + +type abstract_response_promise = Core_types.struct_ref + +type abstract + +type abstract_method_t = + abstract Schema.reader_t -> (unit -> unit) -> abstract_response_promise + +type 'a response_promise = abstract_response_promise +type ('a, 'b) method_t = 'a -> (unit -> unit) -> Core_types.struct_ref + +let pp_method = Capnp.RPC.Registry.pp_method + +class type generic = object + method dispatch : interface_id:Stdint.Uint64.t -> method_id:int -> abstract_method_t + method release : unit + method pp : Format.formatter -> unit +end + +let local (s:#generic) = + object (_ : Core_types.cap) + inherit Core_types.service as super + + method! pp f = Fmt.fprintf f "%t(%t)" s#pp super#pp_refcount + + method! private release = + super#release; + s#release + + method call results msg = + let open Schema.Reader in + let call = Msg.Request.readable msg in + let interface_id = Call.interface_id_get call in + let method_id = Call.method_id_get call in + Log.info (fun f -> f "Invoking local method %a" pp_method (interface_id, method_id)); + let p = Call.params_get call in + let m : abstract_method_t = s#dispatch ~interface_id ~method_id in + let release_params () = Core_types.Request_payload.release msg in + let contents : abstract Schema.reader_t = + Payload.content_get p |> Schema.ReaderOps.deref_opt_struct_pointer |> Schema.ReaderOps.cast_struct in + match m contents release_params with + | r -> results#resolve r + | exception ex -> + release_params (); + Log.warn (fun f -> f "Uncaught exception handling %a: %a" pp_method (interface_id, method_id) Fmt.exn ex); + Core_types.resolve_payload results + (Error (Capnp_rpc.Error.exn "Internal error from %a" pp_method (interface_id, method_id))) + end + +(* The simple case for returning a message (rather than another value). *) +let return resp = + Core_types.return @@ Response.finish resp + +let return_empty () = + return @@ Response.create_empty () + + +(* A convenient way to implement a simple blocking local function, where + pipelining is not supported (further messages will be queued up at this + host until it returns). *) +let return_fut fn : _ = + let sync = SyncPoint.create() in + let result, resolver = Local_struct_promise.make () in + (* call [fn] in parallel *) + ThreadPool.run + (fun () -> + try + begin match Fut.get @@ fn () with + | Ok resp -> + Core_types.resolve_ok resolver @@ Response.finish resp; + SyncPoint.signal sync; + | Error (`Capnp e) -> + Core_types.resolve_payload resolver (Error e); + SyncPoint.signal sync; + end + with ex -> + Log.warn (fun f -> f "Uncaught exception: %a" Fmt.exn ex); + Core_types.resolve_exn resolver @@ Capnp_rpc.Exception.v "Internal error"; + SyncPoint.signal sync; + ); + SyncPoint.wait sync; + result + +let fail = Core_types.fail diff --git a/capnp-rpc-sync/sturdy_ref.ml b/capnp-rpc-sync/sturdy_ref.ml new file mode 100644 index 000000000..c9b09a06a --- /dev/null +++ b/capnp-rpc-sync/sturdy_ref.ml @@ -0,0 +1,22 @@ +open Utils + +class type [+'a] t = Capnp_core.sturdy_ref + +let connect t = + Fut.make + (fun () -> t#connect) + +let connect_exn t = + Fut.make + (fun () -> + match t#connect with + | Ok x -> x + | Error e -> failwith (Fmt.to_string Capnp_rpc.Exception.pp e)) + +let reader fn s = + fn s |> Schema.ReaderOps.string_of_pointer |> Uri.of_string + +let builder fn (s : 'a Capnp.BytesMessage.StructStorage.builder_t) (sr : 'a t) = + sr#to_uri_with_secrets |> Uri.to_string |> Schema.BuilderOps.write_string (fn s) + +let cast t = t diff --git a/capnp-rpc-sync/utils.ml b/capnp-rpc-sync/utils.ml new file mode 100644 index 000000000..97d24dde3 --- /dev/null +++ b/capnp-rpc-sync/utils.ml @@ -0,0 +1,62 @@ +module Fmt = struct + include CCFormat + let exn = of_to_string Printexc.to_string +end + +(** Thread pool for managing concurrency *) +module ThreadPool = CCPool.Make(struct + let max_size = 16 + end) + +module Fut = ThreadPool.Fut + +module SyncPoint : sig + type t + val create : unit -> t + val wait : t -> unit + val signal : t -> unit +end = struct + type t = { + mutex: Mutex.t; + condition: Condition.t; + } + let create() = { + mutex=Mutex.create(); + condition=Condition.create(); + } + + let with_lock_ self f = + Mutex.lock self.mutex; + CCFun.finally1 f self ~h:(fun () -> Mutex.unlock self.mutex) + + let wait self = + with_lock_ self (fun self -> Condition.wait self.condition self.mutex) + + let signal self = + with_lock_ self (fun self -> Condition.broadcast self.condition) +end + +module MVar : sig + type 'a t + val create : unit -> 'a t * ('a -> unit) + val wait : 'a t -> 'a +end = struct + type 'a t = { + mutable x: 'a option; + sync: SyncPoint.t; + } + let rec wait self = match self.x with + | Some v -> v + | None -> + SyncPoint.wait self.sync; + wait self + let create() = + let self = { x=None; sync=SyncPoint.create() } in + self, (fun v -> + match self.x with + | None -> + self.x <- Some v; + SyncPoint.signal self.sync + | Some _ -> invalid_arg "MVar: already resolved" + ) +end diff --git a/capnp-rpc-sync/xform.ml b/capnp-rpc-sync/xform.ml new file mode 100644 index 000000000..1b87aa049 --- /dev/null +++ b/capnp-rpc-sync/xform.ml @@ -0,0 +1,22 @@ +type t = + | Field of int + +let pp f = function + | Field i -> Fmt.pf f "field-%d" i + +let to_cap_index = function + | None -> None + | Some i -> Some (Stdint.Uint32.to_int i) + +(* [walk ss x xs] is the interface cap index at path [x :: xs] within struct storage [ss]. *) +let rec walk ss x = function + | Field x2 :: xs -> walk (Schema.ReaderOps.get_struct ss x) x2 xs + | [] -> Schema.ReaderOps.get_interface ss x |> to_cap_index + +let resolve payload path = + let open Schema.Reader in + match path with + | [] -> Payload.content_get_interface payload |> to_cap_index (* Bootstrap only *) + | Field x :: xs -> + let ss = Payload.content_get payload |> Schema.ReaderOps.deref_opt_struct_pointer in + walk ss x xs diff --git a/capnp-rpc-sync/xform.mli b/capnp-rpc-sync/xform.mli new file mode 100644 index 000000000..58dc18a23 --- /dev/null +++ b/capnp-rpc-sync/xform.mli @@ -0,0 +1,8 @@ +type t = + | Field of int + +val pp : t Fmt.t + +val resolve : Schema.Reader.Payload.t -> t list -> int option +(** [resolve payload path] is the index in the payload's cap descriptor table + of the interface at [path] within the payload's content. *)