docs: more intro and docs outline (#22)

Signed-off-by: Matt Klein <[email protected]>

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 <intro>`: This section covers a general overview of what Envoy Mobile is, an
+  architecture overview, how it is typically deployed, etc.
+* :ref:`Getting Started <start>`: Quickly get started with Envoy Mobile.

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

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 <https://chromium.googlesource.com/chromium/src/+/master/components/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 <https://github.com/facebook/proxygen>`_ and `mvfst <https://github.com/facebookincubator/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 <https://www.grpc.io/>`_
+------------------------------
+
+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
+<https://www.envoyproxy.io/docs/envoy/latest/intro/arch_overview/dynamic_configuration>`_. 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.

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 <https://github.com/lyft/envoy-mobile/milestones>`_.
+
+* 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.

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 <https://github.com/lyft/envoy-mobile#contact>`_.

docs/root/intro/intro.rst

@@ -0,0 +1,13 @@
+.. _intro:
+
+Introduction
+============
+
+.. toctree::
+  :maxdepth: 2
+
+  what_is_envoy
+  comparison
+  currently_supported
+  getting_help
+  version_history

docs/root/intro/version_history.rst

@@ -0,0 +1,7 @@
+Version history
+---------------
+
+0.1.0 (pending)
+===============
+
+Initial open source release.

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 <https://www.envoyproxy.io/>`_ as its core.
+
+Envoy's `project goals <https://www.envoyproxy.io/docs/envoy/latest/intro/what_is_envoy>`_ 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 <https://developers.google.com/protocol-buffers/>`_, Envoy Mobile will standardize
+and abstract how mobile developers interact with IDL exposed endpoints. Via `intelligent protobuf
+code generation <https://github.com/lyft/protoc-gen-star>`_ 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
+<https://github.com/grpc/grpc/blob/master/doc/server-reflection.md>`_ 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
+<https://www.envoyproxy.io/docs/envoy/latest/intro/arch_overview/dynamic_configuration>`_. 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.

docs/root/start/android/android.rst

@@ -0,0 +1,4 @@
+Android
+=======
+
+TBD

docs/root/start/ios/ios.rst

@@ -0,0 +1,4 @@
+iOS
+===
+
+TBD

docs/root/start/start.rst

@@ -0,0 +1,10 @@
+.. _start:
+
+Getting Started
+===============
+
+.. toctree::
+  :maxdepth: 2
+
+  android/android
+  ios/ios