Docs: HTTP Client Tutorial

.github/workflows/doc.yml

@@ -10,8 +10,8 @@ jobs:
   build:
     timeout-minutes: 20
 
-    name: 'Generate & upload documentation'
-    runs-on: 'ubuntu-latest'
+    name: "Generate & upload documentation"
+    runs-on: "ubuntu-latest"
     continue-on-error: true
     steps:
       - name: Checkout
@@ -24,14 +24,15 @@ jobs:
 
       - name: Install mdBook and preprocessors
         run: |
-          cargo binstall mdbook@0.4.36 \
+          cargo binstall mdbook@0.4.51 \
             mdbook-toc@0.14.1 \
             mdbook-open-on-gh@2.4.1 \
-            mdbook-admonish@1.14.0
+            mdbook-admonish@1.14.0 \
+            mdbook-shiftinclude@0.1.0
 
       - uses: jiro4989/setup-nim-action@v1
         with:
-          nim-version: '1.6.20'
+          nim-version: "1.6.20"
 
       - name: Generate doc
         run: |

chronos.nimble

@@ -47,6 +47,12 @@ proc run(args, path: string) =
   build args, path
   exec "build/" & path.splitPath[1]
 
+proc tryExec(cmd: string) =
+  try:
+    exec cmd
+  except Exception as e:
+    echo e.msg
+
 task examples, "Build examples":
   # Build book examples
   for file in listFiles("docs/examples"):
@@ -82,4 +88,9 @@ task test_libbacktrace, "test with libbacktrace":
 
 task docs, "Generate API documentation":
   exec "mdbook build docs"
-  exec nimc & " doc " & "--git.url:https://github.com/status-im/nim-chronos --git.commit:master --outdir:docs/book/api --project chronos"
+  tryExec nimc & " doc " & "--git.url:https://github.com/status-im/nim-chronos --git.commit:master --outdir:docs/book/api --project chronos"
+
+  # Build the docs for modules that aren't part of the main module.
+  for item in walkDir("chronos/apps/http"):
+    if item.kind == pcFile and item.path.splitFile().ext == ".nim":
+      tryExec nimc & " doc " & "--git.url:https://github.com/status-im/nim-chronos --git.commit:master --outdir:docs/book/api/chronos/apps/http " & item.path

docs/book.toml

@@ -1,5 +1,5 @@
 [book]
-authors = ["Jacek Sieka"]
+authors = ["Jacek Sieka", "Constantine Molchanov"]
 language = "en"
 multilingual = false
 src = "src"
@@ -13,8 +13,14 @@ max-level = 2
 [preprocessor.open-on-gh]
 command = "mdbook-open-on-gh"
 renderer = ["html"]
+git-branch = "master"
+
+[preprocessor.admonish]
+command = "mdbook-admonish"
+assets_version = "3.1.0"    # do not edit: managed by `mdbook-admonish install`
+
+[preprocessor.shiftinclude]
 
 [output.html]
 git-repository-url = "https://github.com/status-im/nim-chronos/"
-git-branch = "master"
-additional-css = ["open-in.css"]
+additional-css = ["open-in.css", "mdbook-admonish.css"]

docs/examples/uptimemon/chapter1.nim

@@ -0,0 +1,19 @@
+import chronos/apps/http/httpclient
+
+proc check(uri: string) {.async.} =
+  let session = HttpSessionRef.new()
+
+  try:
+    let response = await session.fetch(parseUri(uri))
+
+    if response.status == 200:
+      echo "[OK] " & uri
+    else:
+      echo "[NOK] " & uri & ": " & $response.status
+  except CatchableError:
+    echo "[ERR] " & uri & ": " & getCurrentExceptionMsg()
+  finally:
+    await noCancel(session.closeWait())
+
+when isMainModule:
+  waitFor check("https://google.com")

docs/examples/uptimemon/chapter2.nim

@@ -0,0 +1,29 @@
+import chronos/apps/http/httpclient
+
+const uris = @[
+  "https://duckduckgo.com/?q=chronos", "https://mock.codes/403", "http://123.456.78.90"
+]
+
+proc check(session: HttpSessionRef, uri: string) {.async.} =
+  try:
+    let response = await session.fetch(parseUri(uri))
+
+    if response.status == 200:
+      echo "[OK] " & uri
+    else:
+      echo "[NOK] " & uri & ": " & $response.status
+  except CatchableError:
+    echo "[ERR] " & uri & ": " & getCurrentExceptionMsg()
+
+proc check(uris: seq[string]) {.async.} =
+  let session = HttpSessionRef.new()
+  var futures: seq[Future[void]]
+
+  for uri in uris:
+    futures.add(session.check(uri))
+
+  await allFutures(futures)
+  await noCancel(session.closeWait())
+
+when isMainModule:
+  waitFor check(uris)

docs/examples/uptimemon/chapter3.nim

@@ -0,0 +1,35 @@
+import chronos/apps/http/httpclient
+
+const uris = @[
+  "https://duckduckgo.com/?q=chronos", "https://mock.codes/403", "http://123.456.78.90",
+  "http://10.255.255.1",
+]
+
+proc check(session: HttpSessionRef, uri: string) {.async.} =
+  try:
+    let responseFuture = session.fetch(parseUri(uri))
+
+    if await responseFuture.withTimeout(5.seconds):
+      let response = responseFuture.read()
+
+      if response.status == 200:
+        echo "[OK] " & uri
+      else:
+        echo "[NOK] " & uri & ": " & $response.status
+    else:
+      raise newException(AsyncTimeoutError, "Connection timed out")
+  except CatchableError:
+    echo "[ERR] " & uri & ": " & getCurrentExceptionMsg()
+
+proc check(uris: seq[string]) {.async.} =
+  let session = HttpSessionRef.new()
+  var futures: seq[Future[void]]
+
+  for uri in uris:
+    futures.add(session.check(uri))
+
+  await allFutures(futures)
+  await noCancel(session.closeWait())
+
+when isMainModule:
+  waitFor check(uris)

docs/examples/uptimemon/chapter4.nim

@@ -0,0 +1,62 @@
+import chronos/apps/http/httpclient
+
+const uris = @[
+  "https://duckduckgo.com/?q=chronos", "https://mock.codes/403", "http://123.456.78.90",
+  "http://10.255.255.1", "https://html.spec.whatwg.org/", "https://mock.codes/200",
+]
+
+proc findMarker(response: HttpClientResponseRef): Future[bool] {.async.} =
+  let bodyReader = response.getBodyReader()
+
+  var
+    buffer = newSeq[byte](1024)
+    fetchedBytes: seq[byte]
+
+  while not result and len(fetchedBytes) <= 10 * 1024:
+    let bytesRead = await bodyReader.readOnce(addr(buffer[0]), len(buffer))
+
+    if bytesRead == 0:
+      break
+
+    fetchedBytes &= buffer
+
+    result = "<html" in bytesToString(fetchedBytes)
+
+proc check(session: HttpSessionRef, uri: string) {.async.} =
+  try:
+    let request = HttpClientRequestRef.new(session, uri)
+
+    if request.isErr:
+      raise newException(HttpRequestError, request.error)
+
+    let responseFuture = request.value.send()
+
+    if await responseFuture.withTimeout(5.seconds):
+      let response = responseFuture.read()
+
+      if response.status == 200:
+        let markerFound = await findMarker(response)
+
+        if markerFound:
+          echo "[OK] " & uri
+        else:
+          echo "[NOK] " & uri & ": Not valid HTML"
+      else:
+        echo "[NOK] " & uri & ": " & $response.status
+    else:
+      raise newException(AsyncTimeoutError, "Connection timed out")
+  except CatchableError:
+    echo "[ERR] " & uri & ": " & getCurrentExceptionMsg()
+
+proc check(uris: seq[string]) {.async.} =
+  let session = HttpSessionRef.new()
+  var futures: seq[Future[void]]
+
+  for uri in uris:
+    futures.add(session.check(uri))
+
+  await allFutures(futures)
+  await noCancel(session.closeWait())
+
+when isMainModule:
+  waitFor check(uris)

docs/examples/uptimemon/chapter5.nim

@@ -0,0 +1,92 @@
+import chronos/apps/http/httpclient
+
+const
+  ntfyTopic = "X3JIaLZSrFqBJXfJ"
+  uris = @[
+    "https://duckduckgo.com/?q=chronos", "https://mock.codes/403",
+    "http://123.456.78.90", "http://10.255.255.1", "https://html.spec.whatwg.org/",
+    "https://mock.codes/200",
+  ]
+
+proc sendAlert(
+    session: HttpSessionRef, message: string, priority = 3
+) {.async.} =
+  let
+    headers = {"Title": "Chronos Uptime Monitor", "Priority": $priority}
+    body = message.stringToBytes()
+    request = HttpClientRequestRef.new(
+      session,
+      "https://ntfy.sh/" & ntfyTopic,
+      meth = MethodPost,
+      headers = headers,
+      body = body,
+    )
+
+  if request.isOk:
+    try:
+      let response = await request.get.send()
+      await response.closeWait()
+    except CatchableError:
+      echo "[WRN] Failed to send alert: " & getCurrentExceptionMsg()
+
+proc findMarker(response: HttpClientResponseRef): Future[bool] {.async.} =
+  let bodyReader = response.getBodyReader()
+
+  var
+    buffer = newSeq[byte](1024)
+    fetchedBytes: seq[byte]
+
+  while not result and len(fetchedBytes) <= 10 * 1024:
+    let bytesRead = await bodyReader.readOnce(addr(buffer[0]), len(buffer))
+
+    if bytesRead == 0:
+      break
+
+    fetchedBytes &= buffer
+
+    result = "<html" in bytesToString(fetchedBytes)
+
+proc check(session: HttpSessionRef, uri: string) {.async.} =
+  try:
+    let request = HttpClientRequestRef.new(session, uri)
+
+    if request.isErr:
+      raise newException(HttpRequestError, request.error)
+
+    let responseFuture = request.get.send()
+
+    if await responseFuture.withTimeout(5.seconds):
+      let response = responseFuture.read()
+
+      if response.status == 200:
+        let markerFound = await findMarker(response)
+
+        if markerFound:
+          echo "[OK] " & uri
+        else:
+          let message = "[NOK] " & uri & ": Not valid HTML"
+          echo message
+          await session.sendAlert(message)
+      else:
+        let message = "[NOK] " & uri & ": " & $response.status
+        echo message
+        await session.sendAlert(message)
+    else:
+      raise newException(AsyncTimeoutError, "Connection timed out")
+  except CatchableError:
+    let message = "[ERR] " & uri & ": " & getCurrentExceptionMsg()
+    echo message
+    await session.sendAlert(message, 4)
+
+proc check(uris: seq[string]) {.async.} =
+  let session = HttpSessionRef.new()
+  var futures: seq[Future[void]]
+
+  for uri in uris:
+    futures.add(session.check(uri))
+
+  await allFutures(futures)
+  await noCancel(session.closeWait())
+
+when isMainModule:
+  waitFor check(uris)