comments: inline clarifications (#77)

Signed-off-by: Jose Nino <jnino@lyft.com>

Description: inline comment pass prior to release. This is my pass at #37.
Signed-off-by: JP Simard <jp@jpsim.com>

mobile/.bazelrc

@@ -14,6 +14,10 @@ build \
  --xcode_version=10.2.1 \
  --incompatible_bzl_disallow_load_after_statement=false
 
+# Manual Stamping is necessary in order to get versioning information in the ios
+# static framework.
+# More information on stamping can be found here:
+# https://github.com/envoyproxy/envoy/tree/master/bazel#enabling-optional-features
 build:ios --define=manual_stamp=manual_stamp
 
 build:android --fat_apk_cpu=x86,x86_64,armeabi-v7a,arm64-v8a

mobile/dist/BUILD

@@ -7,6 +7,8 @@ envoy_package()
 
 # NOTE: You must first build the top-level targets //:ios_dist and //:android_dist to use the
 # artifacts referenced here.
+# You can also download the distributables referenced here from envoy-mobile's releases page:
+# https://github.com/lyft/envoy-mobile/releases
 
 aar_import(
  name = "envoy_mobile_android",

mobile/examples/common/config.yaml

@@ -1,3 +1,6 @@
+# Envoy config used by the example applications.
+# More information about Envoy's config can be found at:
+# https://www.envoyproxy.io/docs/envoy/latest/configuration/configuration
 static_resources:
  listeners:
  - address:

mobile/examples/java/hello_world/AndroidManifest.xml

@@ -3,6 +3,8 @@
  android:versionCode="1"
  android:versionName="0.1">
  <uses-permission android:name="android.permission.INTERNET"/>
+ <!-- This permission is needed in order to allow the application
+ to initiate DNS resolution via c-ares. -->
  <uses-permission android:name="android.permission.ACCESS_NETWORK_STATE"/>
 
  <uses-sdk

mobile/examples/java/hello_world/MainActivity.java

@@ -38,6 +38,7 @@ protected void onCreate(Bundle savedInstanceState) {
  super.onCreate(savedInstanceState);
  setContentView(R.layout.activity_main);
 
+ // Load an envoy config, and run envoy on a separate thread.
  Envoy envoy = new Envoy();
  envoy.load();
  String config = null;
@@ -59,6 +60,7 @@ protected void onCreate(Bundle savedInstanceState) {
  recyclerView.addItemDecoration(dividerItemDecoration);
  thread.start();
 
+ // Run a request loop until the application exits.
  final Handler handler = new Handler(thread.getLooper());
  handler.postDelayed(new Runnable() {
  @Override
@@ -83,6 +85,7 @@ protected void onDestroy() {
 
  private Response makeRequest() throws IOException {
  URL url = new URL(ENDPOINT);
+ // Open connection to the envoy thread listening locally on port 9001.
  HttpURLConnection connection = (HttpURLConnection)url.openConnection();
  int status = connection.getResponseCode();
  if (status != 200) {

mobile/examples/java/hello_world/Response.java

@@ -1,5 +1,6 @@
 package io.envoyproxy.envoymobile.helloenvoy;
 
+// Response is a class to handle HTTP responses.
 public class Response {
  public final String title;
  public final String header;

mobile/examples/kotlin/hello_world/MainActivity.kt

@@ -30,6 +30,7 @@ class MainActivity : Activity() {
  super.onCreate(savedInstanceState)
  setContentView(R.layout.activity_main)
 
+ // Load an envoy config, and run envoy on a separate thread.
  val envoy = Envoy()
  envoy.load()
  envoy.run(baseContext, loadEnvoyConfig(baseContext, R.raw.config))
@@ -44,6 +45,7 @@ class MainActivity : Activity() {
  thread.start()
  val handler = Handler(thread.looper)
 
+ // Run a request loop until the application exits.
  handler.postDelayed(object : Runnable {
  override fun run() {
  try {
@@ -66,6 +68,7 @@ class MainActivity : Activity() {
 
  private fun makeRequest(): Response {
  val url = URL(ENDPOINT)
+ // Open connection to the envoy thread listening locally on port 9001
  val connection = url.openConnection() as HttpURLConnection
  val status = connection.responseCode
  if (status != 200) {

mobile/examples/kotlin/hello_world/Response.kt

@@ -1,3 +1,4 @@
 package io.envoyproxy.envoymobile.helloenvoykotlin
 
+// Response is a class to handle HTTP responses.
 class Response(val title: String, val header: String)

mobile/examples/objective-c/hello_world/ViewController.mm

@@ -59,6 +59,7 @@ - (void)startRequests {
 
 - (void)performRequest {
  NSURLSession* session = [NSURLSession sharedSession];
+ // Note that the request is sent to the envoy thread listening locally on port 9001.
  NSURL* url = [NSURL URLWithString:_ENDPOINT];
  NSURLRequest* request = [NSURLRequest requestWithURL:url];
  NSLog(@"Starting request to '%@'", url.path);

mobile/examples/swift/hello_world/ViewController.swift

@@ -27,6 +27,7 @@ final class ViewController: UITableViewController {
  }
 
  private func performRequest() {
+ // Note that the request is sent to the envoy thread listening locally on port 9001.
  let request = URLRequest(url: kURL)
  NSLog("Starting request to '\(kURL.path)")
  let task = URLSession.shared.dataTask(with: request) { [weak self] data, response, error in

mobile/library/common/jni_interface.cc

@@ -13,6 +13,9 @@ JNIEXPORT jint JNICALL JNI_OnLoad(JavaVM* vm, void* reserved) {
  return -1;
  }
 
+ // c-ares jvm init is necessary in order to let c-ares perform DNS resolution in Envoy.
+ // More information can be found at:
+ // https://c-ares.haxx.se/ares_library_init_android.html
  ares_library_init_jvm(vm);
  return JNI_VERSION_1_6;
 }
@@ -27,6 +30,7 @@ extern "C" JNIEXPORT jint JNICALL
 Java_io_envoyproxy_envoymobile_Envoy_initialize(JNIEnv* env,
  jobject, // this
  jobject connectivity_manager) {
+ // See note above about c-ares.
  return ares_library_init_android(connectivity_manager);
 }
 

mobile/library/common/main_interface.cc

@@ -20,6 +20,12 @@ extern "C" int run_envoy(const char* config) {
  char* envoy_argv[] = {strdup("envoy"), strdup("--config-yaml"), strdup(config), nullptr};
 
  // Ensure static factory registration occurs on time.
+ // Envoy's static factory registration happens when main is run.
+ // However, when compiled as a library, there is no guarantee that such registration will happen
+ // before the names are needed.
+ // The following calls ensure that registration happens before the entities are needed.
+ // Note that as more registrations are needed, explicit initialization calls will need to be added
+ // here.
  Envoy::Extensions::HttpFilters::RouterFilter::forceRegisterRouterFilterConfig();
  Envoy::Extensions::NetworkFilters::HttpConnectionManager::
  forceRegisterHttpConnectionManagerFilterConfigFactory();
@@ -31,6 +37,9 @@ extern "C" int run_envoy(const char* config) {
  // Initialize the server's main context under a try/catch loop and simply
  // return EXIT_FAILURE as needed. Whatever code in the initialization path
  // that fails is expected to log an error message so the user can diagnose.
+ // Note that in the Android examples logging will not be seen.
+ // This is a known problem, and will be addressed by:
+ // https://github.com/lyft/envoy-mobile/issues/34
  try {
  main_common = std::make_unique<Envoy::MainCommon>(3, envoy_argv);
  } catch (const Envoy::NoServingException& e) {

mobile/library/java/io/envoyproxy/envoymobile/Envoy.java

@@ -6,6 +6,7 @@
 
 import java.io.*;
 
+// Wrapper class that allows for easy calling of Envoy's JNI interface in native Java.
 public class Envoy {
 
  public void load() { System.loadLibrary("envoy_jni"); }