cannam@134: // Copyright (c) 2013-2014 Sandstorm Development Group, Inc. and contributors
cannam@134: // Licensed under the MIT License:
cannam@134: //
cannam@134: // Permission is hereby granted, free of charge, to any person obtaining a copy
cannam@134: // of this software and associated documentation files (the "Software"), to deal
cannam@134: // in the Software without restriction, including without limitation the rights
cannam@134: // to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
cannam@134: // copies of the Software, and to permit persons to whom the Software is
cannam@134: // furnished to do so, subject to the following conditions:
cannam@134: //
cannam@134: // The above copyright notice and this permission notice shall be included in
cannam@134: // all copies or substantial portions of the Software.
cannam@134: //
cannam@134: // THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
cannam@134: // IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
cannam@134: // FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
cannam@134: // AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
cannam@134: // LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
cannam@134: // OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
cannam@134: // THE SOFTWARE.
cannam@134: 
cannam@134: #ifndef CAPNP_EZ_RPC_H_
cannam@134: #define CAPNP_EZ_RPC_H_
cannam@134: 
cannam@134: #if defined(__GNUC__) && !defined(CAPNP_HEADER_WARNINGS)
cannam@134: #pragma GCC system_header
cannam@134: #endif
cannam@134: 
cannam@134: #include "rpc.h"
cannam@134: #include "message.h"
cannam@134: 
cannam@134: struct sockaddr;
cannam@134: 
cannam@134: namespace kj { class AsyncIoProvider; class LowLevelAsyncIoProvider; }
cannam@134: 
cannam@134: namespace capnp {
cannam@134: 
cannam@134: class EzRpcContext;
cannam@134: 
cannam@134: class EzRpcClient {
cannam@134:   // Super-simple interface for setting up a Cap'n Proto RPC client.  Example:
cannam@134:   //
cannam@134:   //     # Cap'n Proto schema
cannam@134:   //     interface Adder {
cannam@134:   //       add @0 (left :Int32, right :Int32) -> (value :Int32);
cannam@134:   //     }
cannam@134:   //
cannam@134:   //     // C++ client
cannam@134:   //     int main() {
cannam@134:   //       capnp::EzRpcClient client("localhost:3456");
cannam@134:   //       Adder::Client adder = client.getMain<Adder>();
cannam@134:   //       auto request = adder.addRequest();
cannam@134:   //       request.setLeft(12);
cannam@134:   //       request.setRight(34);
cannam@134:   //       auto response = request.send().wait(client.getWaitScope());
cannam@134:   //       assert(response.getValue() == 46);
cannam@134:   //       return 0;
cannam@134:   //     }
cannam@134:   //
cannam@134:   //     // C++ server
cannam@134:   //     class AdderImpl final: public Adder::Server {
cannam@134:   //     public:
cannam@134:   //       kj::Promise<void> add(AddContext context) override {
cannam@134:   //         auto params = context.getParams();
cannam@134:   //         context.getResults().setValue(params.getLeft() + params.getRight());
cannam@134:   //         return kj::READY_NOW;
cannam@134:   //       }
cannam@134:   //     };
cannam@134:   //
cannam@134:   //     int main() {
cannam@134:   //       capnp::EzRpcServer server(kj::heap<AdderImpl>(), "*:3456");
cannam@134:   //       kj::NEVER_DONE.wait(server.getWaitScope());
cannam@134:   //     }
cannam@134:   //
cannam@134:   // This interface is easy, but it hides a lot of useful features available from the lower-level
cannam@134:   // classes:
cannam@134:   // - The server can only export a small set of public, singleton capabilities under well-known
cannam@134:   //   string names.  This is fine for transient services where no state needs to be kept between
cannam@134:   //   connections, but hides the power of Cap'n Proto when it comes to long-lived resources.
cannam@134:   // - EzRpcClient/EzRpcServer automatically set up a `kj::EventLoop` and make it current for the
cannam@134:   //   thread.  Only one `kj::EventLoop` can exist per thread, so you cannot use these interfaces
cannam@134:   //   if you wish to set up your own event loop.  (However, you can safely create multiple
cannam@134:   //   EzRpcClient / EzRpcServer objects in a single thread; they will make sure to make no more
cannam@134:   //   than one EventLoop.)
cannam@134:   // - These classes only support simple two-party connections, not multilateral VatNetworks.
cannam@134:   // - These classes only support communication over a raw, unencrypted socket.  If you want to
cannam@134:   //   build on an abstract stream (perhaps one which supports encryption), you must use the
cannam@134:   //   lower-level interfaces.
cannam@134:   //
cannam@134:   // Some of these restrictions will probably be lifted in future versions, but some things will
cannam@134:   // always require using the low-level interfaces directly.  If you are interested in working
cannam@134:   // at a lower level, start by looking at these interfaces:
cannam@134:   // - `kj::setupAsyncIo()` in `kj/async-io.h`.
cannam@134:   // - `RpcSystem` in `capnp/rpc.h`.
cannam@134:   // - `TwoPartyVatNetwork` in `capnp/rpc-twoparty.h`.
cannam@134: 
cannam@134: public:
cannam@134:   explicit EzRpcClient(kj::StringPtr serverAddress, uint defaultPort = 0,
cannam@134:                        ReaderOptions readerOpts = ReaderOptions());
cannam@134:   // Construct a new EzRpcClient and connect to the given address.  The connection is formed in
cannam@134:   // the background -- if it fails, calls to capabilities returned by importCap() will fail with an
cannam@134:   // appropriate exception.
cannam@134:   //
cannam@134:   // `defaultPort` is the IP port number to use if `serverAddress` does not include it explicitly.
cannam@134:   // If unspecified, the port is required in `serverAddress`.
cannam@134:   //
cannam@134:   // The address is parsed by `kj::Network` in `kj/async-io.h`.  See that interface for more info
cannam@134:   // on the address format, but basically it's what you'd expect.
cannam@134:   //
cannam@134:   // `readerOpts` is the ReaderOptions structure used to read each incoming message on the
cannam@134:   // connection. Setting this may be necessary if you need to receive very large individual
cannam@134:   // messages or messages. However, it is recommended that you instead think about how to change
cannam@134:   // your protocol to send large data blobs in multiple small chunks -- this is much better for
cannam@134:   // both security and performance. See `ReaderOptions` in `message.h` for more details.
cannam@134: 
cannam@134:   EzRpcClient(const struct sockaddr* serverAddress, uint addrSize,
cannam@134:               ReaderOptions readerOpts = ReaderOptions());
cannam@134:   // Like the above constructor, but connects to an already-resolved socket address.  Any address
cannam@134:   // format supported by `kj::Network` in `kj/async-io.h` is accepted.
cannam@134: 
cannam@134:   explicit EzRpcClient(int socketFd, ReaderOptions readerOpts = ReaderOptions());
cannam@134:   // Create a client on top of an already-connected socket.
cannam@134:   // `readerOpts` acts as in the first constructor.
cannam@134: 
cannam@134:   ~EzRpcClient() noexcept(false);
cannam@134: 
cannam@134:   template <typename Type>
cannam@134:   typename Type::Client getMain();
cannam@134:   Capability::Client getMain();
cannam@134:   // Get the server's main (aka "bootstrap") interface.
cannam@134: 
cannam@134:   template <typename Type>
cannam@134:   typename Type::Client importCap(kj::StringPtr name)
cannam@134:       KJ_DEPRECATED("Change your server to export a main interface, then use getMain() instead.");
cannam@134:   Capability::Client importCap(kj::StringPtr name)
cannam@134:       KJ_DEPRECATED("Change your server to export a main interface, then use getMain() instead.");
cannam@134:   // ** DEPRECATED **
cannam@134:   //
cannam@134:   // Ask the sever for the capability with the given name.  You may specify a type to automatically
cannam@134:   // down-cast to that type.  It is up to you to specify the correct expected type.
cannam@134:   //
cannam@134:   // Named interfaces are deprecated. The new preferred usage pattern is for the server to export
cannam@134:   // a "main" interface which itself has methods for getting any other interfaces.
cannam@134: 
cannam@134:   kj::WaitScope& getWaitScope();
cannam@134:   // Get the `WaitScope` for the client's `EventLoop`, which allows you to synchronously wait on
cannam@134:   // promises.
cannam@134: 
cannam@134:   kj::AsyncIoProvider& getIoProvider();
cannam@134:   // Get the underlying AsyncIoProvider set up by the RPC system.  This is useful if you want
cannam@134:   // to do some non-RPC I/O in asynchronous fashion.
cannam@134: 
cannam@134:   kj::LowLevelAsyncIoProvider& getLowLevelIoProvider();
cannam@134:   // Get the underlying LowLevelAsyncIoProvider set up by the RPC system.  This is useful if you
cannam@134:   // want to do some non-RPC I/O in asynchronous fashion.
cannam@134: 
cannam@134: private:
cannam@134:   struct Impl;
cannam@134:   kj::Own<Impl> impl;
cannam@134: };
cannam@134: 
cannam@134: class EzRpcServer {
cannam@134:   // The server counterpart to `EzRpcClient`.  See `EzRpcClient` for an example.
cannam@134: 
cannam@134: public:
cannam@134:   explicit EzRpcServer(Capability::Client mainInterface, kj::StringPtr bindAddress,
cannam@134:                        uint defaultPort = 0, ReaderOptions readerOpts = ReaderOptions());
cannam@134:   // Construct a new `EzRpcServer` that binds to the given address.  An address of "*" means to
cannam@134:   // bind to all local addresses.
cannam@134:   //
cannam@134:   // `defaultPort` is the IP port number to use if `serverAddress` does not include it explicitly.
cannam@134:   // If unspecified, a port is chosen automatically, and you must call getPort() to find out what
cannam@134:   // it is.
cannam@134:   //
cannam@134:   // The address is parsed by `kj::Network` in `kj/async-io.h`.  See that interface for more info
cannam@134:   // on the address format, but basically it's what you'd expect.
cannam@134:   //
cannam@134:   // The server might not begin listening immediately, especially if `bindAddress` needs to be
cannam@134:   // resolved.  If you need to wait until the server is definitely up, wait on the promise returned
cannam@134:   // by `getPort()`.
cannam@134:   //
cannam@134:   // `readerOpts` is the ReaderOptions structure used to read each incoming message on the
cannam@134:   // connection. Setting this may be necessary if you need to receive very large individual
cannam@134:   // messages or messages. However, it is recommended that you instead think about how to change
cannam@134:   // your protocol to send large data blobs in multiple small chunks -- this is much better for
cannam@134:   // both security and performance. See `ReaderOptions` in `message.h` for more details.
cannam@134: 
cannam@134:   EzRpcServer(Capability::Client mainInterface, struct sockaddr* bindAddress, uint addrSize,
cannam@134:               ReaderOptions readerOpts = ReaderOptions());
cannam@134:   // Like the above constructor, but binds to an already-resolved socket address.  Any address
cannam@134:   // format supported by `kj::Network` in `kj/async-io.h` is accepted.
cannam@134: 
cannam@134:   EzRpcServer(Capability::Client mainInterface, int socketFd, uint port,
cannam@134:               ReaderOptions readerOpts = ReaderOptions());
cannam@134:   // Create a server on top of an already-listening socket (i.e. one on which accept() may be
cannam@134:   // called).  `port` is returned by `getPort()` -- it serves no other purpose.
cannam@134:   // `readerOpts` acts as in the other two above constructors.
cannam@134: 
cannam@134:   explicit EzRpcServer(kj::StringPtr bindAddress, uint defaultPort = 0,
cannam@134:                        ReaderOptions readerOpts = ReaderOptions())
cannam@134:       KJ_DEPRECATED("Please specify a main interface for your server.");
cannam@134:   EzRpcServer(struct sockaddr* bindAddress, uint addrSize,
cannam@134:               ReaderOptions readerOpts = ReaderOptions())
cannam@134:       KJ_DEPRECATED("Please specify a main interface for your server.");
cannam@134:   EzRpcServer(int socketFd, uint port, ReaderOptions readerOpts = ReaderOptions())
cannam@134:       KJ_DEPRECATED("Please specify a main interface for your server.");
cannam@134: 
cannam@134:   ~EzRpcServer() noexcept(false);
cannam@134: 
cannam@134:   void exportCap(kj::StringPtr name, Capability::Client cap);
cannam@134:   // Export a capability publicly under the given name, so that clients can import it.
cannam@134:   //
cannam@134:   // Keep in mind that you can implicitly convert `kj::Own<MyType::Server>&&` to
cannam@134:   // `Capability::Client`, so it's typical to pass something like
cannam@134:   // `kj::heap<MyImplementation>(<constructor params>)` as the second parameter.
cannam@134: 
cannam@134:   kj::Promise<uint> getPort();
cannam@134:   // Get the IP port number on which this server is listening.  This promise won't resolve until
cannam@134:   // the server is actually listening.  If the address was not an IP address (e.g. it was a Unix
cannam@134:   // domain socket) then getPort() resolves to zero.
cannam@134: 
cannam@134:   kj::WaitScope& getWaitScope();
cannam@134:   // Get the `WaitScope` for the client's `EventLoop`, which allows you to synchronously wait on
cannam@134:   // promises.
cannam@134: 
cannam@134:   kj::AsyncIoProvider& getIoProvider();
cannam@134:   // Get the underlying AsyncIoProvider set up by the RPC system.  This is useful if you want
cannam@134:   // to do some non-RPC I/O in asynchronous fashion.
cannam@134: 
cannam@134:   kj::LowLevelAsyncIoProvider& getLowLevelIoProvider();
cannam@134:   // Get the underlying LowLevelAsyncIoProvider set up by the RPC system.  This is useful if you
cannam@134:   // want to do some non-RPC I/O in asynchronous fashion.
cannam@134: 
cannam@134: private:
cannam@134:   struct Impl;
cannam@134:   kj::Own<Impl> impl;
cannam@134: };
cannam@134: 
cannam@134: // =======================================================================================
cannam@134: // inline implementation details
cannam@134: 
cannam@134: template <typename Type>
cannam@134: inline typename Type::Client EzRpcClient::getMain() {
cannam@134:   return getMain().castAs<Type>();
cannam@134: }
cannam@134: 
cannam@134: template <typename Type>
cannam@134: inline typename Type::Client EzRpcClient::importCap(kj::StringPtr name) {
cannam@134:   return importCap(name).castAs<Type>();
cannam@134: }
cannam@134: 
cannam@134: }  // namespace capnp
cannam@134: 
cannam@134: #endif  // CAPNP_EZ_RPC_H_