diff --git a/docs/root/about_docs.rst b/docs/root/about_docs.rst new file mode 100644 index 0000000000..fcc0c856b1 --- /dev/null +++ b/docs/root/about_docs.rst @@ -0,0 +1,8 @@ +About the documentation +======================= + +The Envoy Mobile documentation is composed of a few major sections: + +* :ref:`Introduction `: This section covers a general overview of what Envoy Mobile is, an + architecture overview, how it is typically deployed, etc. +* :ref:`Getting Started `: Quickly get started with Envoy Mobile. diff --git a/docs/root/index.rst b/docs/root/index.rst index 917978ffb2..10db2942ab 100644 --- a/docs/root/index.rst +++ b/docs/root/index.rst @@ -8,3 +8,10 @@ Envoy Mobile documentation This is pre-release documentation. There is risk of it not being consistent with what is currently implemented in Envoy Mobile, though we try to make things consistent as quickly as possible. + + .. toctree:: + :maxdepth: 2 + + about_docs + intro/intro + start/start diff --git a/docs/root/intro/comparison.rst b/docs/root/intro/comparison.rst new file mode 100644 index 0000000000..002b182859 --- /dev/null +++ b/docs/root/intro/comparison.rst @@ -0,0 +1,45 @@ +Comparison to similar systems +============================= + +The Envoy Mobile proposed roadmap has similarities to several existing systems. They are compared +below. + +.. attention:: + + The projects below are under active development. Thus some of the information may become out of + date. If that is the case please let us know and we will fix it. + +`Cronet `_ +-------------------------------------------------------------------------------------- + +Cronet is Google's cross-platform client networking library that is used by all of its mobile +applications and several other companies including Snap. In terms of goals, Cronet is a subset of +Envoy Mobile targeted at advanced client networking protocols, with the caveat that it already +supports QUIC. Envoy Mobile's goals are larger and include extensibility, observability, IDL +integration, etc. With that said, there is a lot to learn from Cronet in terms of how it handles +QUIC in a robust and production ready way. + +`proxygen `_ and `mvfst `_ +------------------------------------------------------------------------------------------------------------ + +proxygen is Facebook's high performance HTTP proxy library, written on top of a Finagle like +C++ library called wangle. mvst is Facebook's recently open sourced QUIC implementation. Both +libraries are used by Facebook in their mobile applications, but none of the mobile integration +code has been open sourced. Like Cronet, Envoy Mobile's goals are a superset of what proxygen and +mvfst provide. + +`gRPC `_ +------------------------------ + +gRPC is a multi-platform message passing system out of Google. It uses an IDL to describe an RPC +library and then implements application specific runtimes for a variety of different languages. The +underlying transport is HTTP/2. gRPC does have mobile client libraries, though the production +readiness is not equivalent to the server-side libraries. In terms of goals and feature set, gRPC is +closer to Envoy Mobile than Cronet or proxygen/mvfst, and in fact gRPC is currently in the process +of migrating its look-aside load balancing APIs to `xDS +`_. It is +possible that in the future gRPC's mobile clients will continue to converge with Envoy Mobile, but +in the near term we feel that Envoy Mobile can deliver a production ready iOS/Android feature set +that includes xDS, QUIC, etc. in a shorter time frame. Note that Envoy Mobile will likely continue +to use gRPC framing for calling IDL based unary and streaming APIs, making it wire compatible with +gRPC on the server. diff --git a/docs/root/intro/currently_supported.rst b/docs/root/intro/currently_supported.rst new file mode 100644 index 0000000000..6036448e34 --- /dev/null +++ b/docs/root/intro/currently_supported.rst @@ -0,0 +1,14 @@ +Currently supported features +============================ + +.. attention:: + + Envoy Mobile is currently in a very early stage of development. This page will be updated as + new features are added, and eventually split out into proper documentation. Our initial milestones + can be `viewed in GitHub `_. + +* Ability to compile Envoy on both Android and iOS. +* Ability to run Envoy on a thread within an application, utilizing it effectively as an in-process + proxy server. +* Swift/Obj-C/Kotlin demo applications that utilize exposed Swift/Obj-C/Kotlin "raw" APIs to + interact with Envoy and make network calls. diff --git a/docs/root/intro/getting_help.rst b/docs/root/intro/getting_help.rst new file mode 100644 index 0000000000..aa73634a3e --- /dev/null +++ b/docs/root/intro/getting_help.rst @@ -0,0 +1,9 @@ +.. _getting_help: + +Getting help +============ + +We are very interested in building a community around Envoy Mobile. Please reach out to us if you +are interested in using it and need help or want to contribute. + +Please see `contact info `_. diff --git a/docs/root/intro/intro.rst b/docs/root/intro/intro.rst new file mode 100644 index 0000000000..600d8addec --- /dev/null +++ b/docs/root/intro/intro.rst @@ -0,0 +1,13 @@ +.. _intro: + +Introduction +============ + +.. toctree:: + :maxdepth: 2 + + what_is_envoy + comparison + currently_supported + getting_help + version_history diff --git a/docs/root/intro/version_history.rst b/docs/root/intro/version_history.rst new file mode 100644 index 0000000000..ce79a5d9cc --- /dev/null +++ b/docs/root/intro/version_history.rst @@ -0,0 +1,7 @@ +Version history +--------------- + +0.1.0 (pending) +=============== + +Initial open source release. diff --git a/docs/root/intro/what_is_envoy.rst b/docs/root/intro/what_is_envoy.rst new file mode 100644 index 0000000000..3d45b9d538 --- /dev/null +++ b/docs/root/intro/what_is_envoy.rst @@ -0,0 +1,79 @@ +What is Envoy Mobile +==================== + +.. attention:: + + Envoy Mobile is currently in a very early stage of development. This page should be read as a set + of aspirational project goals. + +Envoy Mobile is an iOS and Android client networking library built using +`Envoy `_ as its core. + +Envoy's `project goals `_ are +simply stated as: + + *The network should be transparent to applications. When network and application problems do occur + it should be easy to determine the source of the problem.* + +As fundamental as Envoy has become in scaling many organizations’ distributed architectures, the +reality is that three 9s at the server-side edge is meaningless if the user of a mobile application +is only able to complete the desired product flows a fraction of the time. This may be due to a +combination of network and application errors. Thus, in order to fully achieve the Envoy project’s +goal of making the network transparent to applications, the service mesh and its inherent benefits +(observability, consistency, etc.) must expand beyond the edge all the way to the mobile +applications that are so critical to the end user’s experience. Envoy Mobile in conjunction with +Envoy in the data center will provide the ability to reason about the entire distributed system +network, not just the server-side portion. + +Whereas server-side Envoy proxy is a self-contained process that is meant to be deployed alongside a +polyglot architecture, Envoy Mobile is distributed as a library meant to be compiled directly into +client mobile applications. The library approach is required due to the practicalities of how +applications are written and distributed on both the iOS and Android platforms. The high level goals +of the library are discussed in the following subsections. + +Ubiquitous API and abstraction for networking +--------------------------------------------- + +With the industry progressively moving towards specifying APIs via a strongly typed IDL such as +`protocol buffers `_, Envoy Mobile will standardize +and abstract how mobile developers interact with IDL exposed endpoints. Via `intelligent protobuf +code generation `_ and an abstract transport, both iOS and +Android can provide similar interfaces and ergonomics for consuming APIs. Initially we are planning +on focusing our efforts on Swift APIs for iOS and Kotlin APIs for Android, but depending on +community interest we will consider adding support for additional languages in the future. Our +ultimate goal is to make the low-level Envoy common C++ code an implementation detail that the +average mobile developer does not need to be aware of. Instead, mobile developers will interact with +high-level language specific APIs that encapsulate common concerns such as making API calls, +analytics, tracing, etc. + +Simple and explicit system for supporting advanced networking features +---------------------------------------------------------------------- + +With protocol buffer’s powerful annotation/extension system, Envoy Mobile can add sophisticated +cross-platform functionality in a simple and explicit way when using strongly typed IDL APIs. +Examples of annotations that are planned on our roadmap include marking an API as offline/deferred +capable, caching, priority, streaming, marking fields for exclusion both on the request and response +in poor network conditions, as well as general Envoy policies such as retry and timeout +specifications. + +Much like Envoy’s use in a server-side service mesh, the goal is to push as much functionality as +possible into the common core so as to avoid reimplementing it in every mobile application language. + +Our long-term plans include evolving the `gRPC Server Reflection Protocol +`_ into a streaming reflection +service API. This API will allow both Envoy and Envoy Mobile to fetch generic protobuf definitions +from a central IDL service, which can then be used to implement annotation driven networking via +reflection. This model means that Envoy Mobile will not necessarily need to have prior knowledge of +an organization’s APIs in order to provide enhanced cross-platform networking functionality. + +xDS driven mobile client policy +------------------------------- + +One of the reasons that Envoy has become so popular as a platform is its rich configuration +discovery APIs which are collectively known as `xDS +`_. These +APIs allow a distributed set of Envoys to be managed by an eventually consistent control plane. One +of the long term goals of Envoy Mobile is to bring xDS configuration all the way to mobile clients, +in the form of routing, authentication, failover, load balancing, and other policies driven by a +global load balancing system. This will be an extremely powerful mechanism for bringing layer 7 / +application networking concepts all the way to the mobile client. diff --git a/docs/root/start/android/android.rst b/docs/root/start/android/android.rst new file mode 100644 index 0000000000..6b5f69e9b0 --- /dev/null +++ b/docs/root/start/android/android.rst @@ -0,0 +1,4 @@ +Android +======= + +TBD diff --git a/docs/root/start/ios/ios.rst b/docs/root/start/ios/ios.rst new file mode 100644 index 0000000000..d1caaf8c5f --- /dev/null +++ b/docs/root/start/ios/ios.rst @@ -0,0 +1,4 @@ +iOS +=== + +TBD diff --git a/docs/root/start/start.rst b/docs/root/start/start.rst new file mode 100644 index 0000000000..b1b80a393e --- /dev/null +++ b/docs/root/start/start.rst @@ -0,0 +1,10 @@ +.. _start: + +Getting Started +=============== + +.. toctree:: + :maxdepth: 2 + + android/android + ios/ios diff --git a/envoy b/envoy index 0e109cb3ba..98bce8c0f5 160000 --- a/envoy +++ b/envoy @@ -1 +1 @@ -Subproject commit 0e109cb3ba3be0823bdb696eacb02a827989efa1 +Subproject commit 98bce8c0f5e0f37cd140aff9c9b35c8f46a0840a