Add a pinging example using axios

templates/docs/javascript.html

@@ -1,11 +1,45 @@
 <h1>Javascript</h1>
-<p>Below is an example of making an HTTP request to SITE_NAME from Node.js.</p>
+<p>Below is a minimal example of making an HTTP request to SITE_NAME from Node.js.</p>
 <div class="highlight"><pre><span></span><code><span class="kd">var</span> <span class="nx">https</span> <span class="o">=</span> <span class="nx">require</span><span class="p">(</span><span class="s1">&#39;https&#39;</span><span class="p">);</span>
 <span class="nx">https</span><span class="p">.</span><span class="nx">get</span><span class="p">(</span><span class="s1">&#39;PING_URL&#39;</span><span class="p">).</span><span class="nx">on</span><span class="p">(</span><span class="s1">&#39;error&#39;</span><span class="p">,</span> <span class="p">(</span><span class="nx">err</span><span class="p">)</span> <span class="p">=&gt;</span> <span class="p">{</span>
     <span class="nx">console</span><span class="p">.</span><span class="nx">log</span><span class="p">(</span><span class="s1">&#39;Ping failed: &#39;</span> <span class="o">+</span> <span class="nx">err</span><span class="p">)</span>
 <span class="p">});</span>
 </code></pre></div>
 
+<p>Note: the "https" library executes requests asynchronously. If you send both "start"
+and "success" signals, you can encounter a race condition where the "success" signal
+arrives before the "start" signal. Avoid the the race condition by using callbacks,
+promises or the async/await feature. Here is an example that uses async/await and the
+<a href="https://axios-http.com/">axios</a> library:</p>
+<div class="highlight"><pre><span></span><code><span class="kd">const</span> <span class="nx">axios</span> <span class="o">=</span> <span class="nx">require</span><span class="p">(</span><span class="s2">&quot;axios&quot;</span><span class="p">);</span>
+
+<span class="k">async</span> <span class="kd">function</span> <span class="nx">ping</span><span class="p">(</span><span class="nx">url</span><span class="p">)</span> <span class="p">{</span>
+    <span class="k">try</span> <span class="p">{</span>
+        <span class="k">await</span> <span class="nx">axios</span><span class="p">.</span><span class="nx">get</span><span class="p">(</span><span class="nx">url</span><span class="p">,</span> <span class="p">{</span><span class="nx">timeout</span><span class="o">:</span> <span class="mf">5000</span><span class="p">});</span>
+    <span class="p">}</span> <span class="k">catch</span><span class="p">(</span><span class="nx">error</span><span class="p">)</span> <span class="p">{</span>
+        <span class="c1">// Log the error and continue. A ping failure should</span>
+        <span class="c1">// not prevent the job from running.</span>
+        <span class="nx">console</span><span class="p">.</span><span class="nx">error</span><span class="p">(</span><span class="s2">&quot;Ping failed: &quot;</span> <span class="o">+</span> <span class="nx">error</span><span class="p">);</span>
+    <span class="p">}</span>
+<span class="p">}</span>
+
+<span class="k">async</span> <span class="kd">function</span> <span class="nx">runJob</span><span class="p">()</span> <span class="p">{</span>
+    <span class="kd">var</span> <span class="nx">pingUrl</span> <span class="o">=</span> <span class="s2">&quot;PING_URL&quot;</span><span class="p">;</span>
+
+    <span class="k">await</span> <span class="nx">ping</span><span class="p">(</span><span class="nx">pingUrl</span> <span class="o">+</span> <span class="s2">&quot;/start&quot;</span><span class="p">);</span>
+    <span class="k">try</span> <span class="p">{</span>
+        <span class="nx">console</span><span class="p">.</span><span class="nx">log</span><span class="p">(</span><span class="s2">&quot;TODO: run the job here&quot;</span><span class="p">);</span>
+
+        <span class="k">await</span> <span class="nx">ping</span><span class="p">(</span><span class="nx">pingUrl</span><span class="p">);</span> <span class="c1">// success</span>
+    <span class="p">}</span> <span class="k">catch</span><span class="p">(</span><span class="nx">error</span><span class="p">)</span> <span class="p">{</span>
+        <span class="k">await</span> <span class="nx">ping</span><span class="p">(</span><span class="nx">pingUrl</span> <span class="o">+</span> <span class="s2">&quot;/fail&quot;</span><span class="p">);</span>
+    <span class="p">}</span>
+<span class="p">}</span>
+
+<span class="nx">runJob</span><span class="p">();</span>
+</code></pre></div>
+
+<h2>Browser</h2>
 <p>You can also send pings from a browser environment. SITE_NAME sets the
 <code>Access-Control-Allow-Origin:*</code> CORS header, so cross-domain AJAX requests work.</p>
 <div class="highlight"><pre><span></span><code><span class="kd">var</span> <span class="nx">xhr</span> <span class="o">=</span> <span class="k">new</span> <span class="nx">XMLHttpRequest</span><span class="p">();</span>

templates/docs/javascript.md

@@ -1,6 +1,6 @@
 # Javascript
 
-Below is an example of making an HTTP request to SITE_NAME from Node.js.
+Below is a minimal example of making an HTTP request to SITE_NAME from Node.js.
 
 ```js
 var https = require('https');
@@ -9,6 +9,43 @@ https.get('PING_URL').on('error', (err) => {
 });
 ```
 
+Note: the "https" library executes requests asynchronously. If you send both "start"
+and "success" signals, you can encounter a race condition where the "success" signal
+arrives before the "start" signal. Avoid the the race condition by using callbacks,
+promises or the async/await feature. Here is an example that uses async/await and the
+[axios](https://axios-http.com/) library:
+
+```js
+const axios = require("axios");
+
+async function ping(url) {
+    try {
+        await axios.get(url, {timeout: 5000});
+    } catch(error) {
+        // Log the error and continue. A ping failure should
+        // not prevent the job from running.
+        console.error("Ping failed: " + error);
+    }
+}
+
+async function runJob() {
+    var pingUrl = "PING_URL";
+
+    await ping(pingUrl + "/start");
+    try {
+        console.log("TODO: run the job here");
+
+        await ping(pingUrl); // success
+    } catch(error) {
+        await ping(pingUrl + "/fail");
+    }
+}
+
+runJob();
+```
+
+## Browser
+
 You can also send pings from a browser environment. SITE_NAME sets the
 `Access-Control-Allow-Origin:*` CORS header, so cross-domain AJAX requests work.