From dc22ba63f5ba02decd601745fccd82d7b22e8077 Mon Sep 17 00:00:00 2001 From: Michael Rebello Date: Mon, 21 Oct 2019 13:30:49 -0700 Subject: [PATCH] docs: minor cleanup (#528) - Remove `about_docs.rst` - Fix file name - Fix table of contents title of `What is Envoy Mobile?` - Fix capitalization Signed-off-by: Michael Rebello Signed-off-by: JP Simard --- mobile/docs/root/index.rst | 3 +- mobile/docs/root/intro/intro.rst | 13 +++ .../docs/root/intro/what_is_envoy_mobile.rst | 79 +++++++++++++++++++ 3 files changed, 93 insertions(+), 2 deletions(-) create mode 100644 mobile/docs/root/intro/intro.rst create mode 100644 mobile/docs/root/intro/what_is_envoy_mobile.rst diff --git a/mobile/docs/root/index.rst b/mobile/docs/root/index.rst index 72d72d4887a7..cbaa0befcb76 100644 --- a/mobile/docs/root/index.rst +++ b/mobile/docs/root/index.rst @@ -1,4 +1,4 @@ -Envoy Mobile documentation +Envoy Mobile Documentation ========================== .. ifconfig:: release_level in ('pre-release') @@ -12,7 +12,6 @@ Envoy Mobile documentation .. toctree:: :maxdepth: 2 - about_docs intro/intro start/start development/development diff --git a/mobile/docs/root/intro/intro.rst b/mobile/docs/root/intro/intro.rst new file mode 100644 index 000000000000..1bb95cf2211f --- /dev/null +++ b/mobile/docs/root/intro/intro.rst @@ -0,0 +1,13 @@ +.. _intro: + +Introduction +============ + +.. toctree:: + :maxdepth: 2 + + what_is_envoy_mobile + comparison + currently_supported + getting_help + version_history diff --git a/mobile/docs/root/intro/what_is_envoy_mobile.rst b/mobile/docs/root/intro/what_is_envoy_mobile.rst new file mode 100644 index 000000000000..81a03813a50a --- /dev/null +++ b/mobile/docs/root/intro/what_is_envoy_mobile.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.