From baff765c907957244e218903bc349dfbf3db8c19 Mon Sep 17 00:00:00 2001
From: Kikuo Emoto <kemoto@codemonger.io>
Date: Mon, 25 Mar 2024 10:34:18 +0900
Subject: [PATCH] docs: update READMEs
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Introduces a new subsection "Infallible client and context" to
`README.md`, which explains how to use the `IntoInfallibleClient` and
`IntoInfallibleContext` traits.

Replaces `Client` → `DaemonClient` in the code examples.
---
 README.md                   | 69 +++++++++++++++++++++++++++----------
 xray-lite-aws-sdk/README.md |  4 +--
 2 files changed, 52 insertions(+), 21 deletions(-)

diff --git a/README.md b/README.md
index e9626c5..09cfea1 100644
--- a/README.md
+++ b/README.md
@@ -20,15 +20,15 @@ xray-lite = { git = "https://github.com/codemonger-io/xray-lite.git", tag = "v0.
 Here is an example to record a subsegment of an AWS service operation within a Lambda function invocation instrumented with AWS X-Ray:
 
 ```rust
-use xray_lite::{AwsNamespace, Client, Context, SubsegmentContext};
+use xray_lite::{AwsNamespace, Context, DaemonClient, SubsegmentContext};
 
 fn main() {
-   // reads AWS_XRAY_DAEMON_ADDRESS
-   let client = Client::from_lambda_env().unwrap();
-   // reads _X_AMZN_TRACE_ID
-   let context = SubsegmentContext::from_lambda_env(client).unwrap();
+    // reads AWS_XRAY_DAEMON_ADDRESS
+    let client = DaemonClient::from_lambda_env().unwrap();
+    // reads _X_AMZN_TRACE_ID
+    let context = SubsegmentContext::from_lambda_env(client).unwrap();
 
-   do_s3_get_object(&context);
+    do_s3_get_object(&context);
 }
 
 fn do_s3_get_object(context: &impl Context) {
@@ -55,15 +55,15 @@ fn do_s3_get_object(context: &impl Context) {
 Here is an example to record a subsegment of a remote service call within a Lambda function invocation instrumented with AWS X-Ray:
 
 ```rust
-use xray_lite::{Client, Context, RemoteNamespace, SubsegmentContext};
+use xray_lite::{Context, DaemonClient, RemoteNamespace, SubsegmentContext};
 
 fn main() {
-   // reads AWS_XRAY_DAEMON_ADDRESS
-   let client = Client::from_lambda_env().unwrap();
-   // reads _X_AMZN_TRACE_ID
-   let context = SubsegmentContext::from_lambda_env(client).unwrap();
+    // reads AWS_XRAY_DAEMON_ADDRESS
+    let client = DaemonClient::from_lambda_env().unwrap();
+    // reads _X_AMZN_TRACE_ID
+    let context = SubsegmentContext::from_lambda_env(client).unwrap();
 
-   do_some_request(&context);
+    do_some_request(&context);
 }
 
 fn do_some_request(context: &impl Context) {
@@ -86,16 +86,16 @@ fn do_some_request(context: &impl Context) {
 Here is an example to record a custom subsegment within a Lambda function invocation instrumented with AWS X-Ray:
 
 ```rust
-use xray_lite::{Client, Context, CustomNamespace, SubsegmentContext};
+use xray_lite::{Context, DaemonClient, CustomNamespace, SubsegmentContext};
 
 fn main() {
-   // reads AWS_XRAY_DAEMON_ADDRESS
-   let client = Client::from_lambda_env().unwrap();
-   // reads _X_AMZN_TRACE_ID
-   let context = SubsegmentContext::from_lambda_env(client).unwrap()
-       .with_name_prefix("readme_example.");
+    // reads AWS_XRAY_DAEMON_ADDRESS
+    let client = DaemonClient::from_lambda_env().unwrap();
+    // reads _X_AMZN_TRACE_ID
+    let context = SubsegmentContext::from_lambda_env(client).unwrap()
+        .with_name_prefix("readme_example.");
 
-   do_something(&context);
+    do_something(&context);
 }
 
 fn do_something(context: &impl Context) {
@@ -108,6 +108,37 @@ fn do_something(context: &impl Context) {
 }
 ```
 
+### Infallible client and context
+
+As X-Ray tracing is likely a subsidiary feature of your Lambda function, you may want to ignore any error that might occur during the initialization of the client and the context.
+By using the helper traits `IntoInfallibleClient` and `IntoInfallibleContext`, you can ignore such errors without affecting the rest of your code:
+
+```rust
+use xray_lite::{
+    AwsNamespace,
+    Context,
+    DaemonClient,
+    IntoInfallibleClient as _,
+    IntoInfallibleContext as _,
+    SubsegmentContext,
+};
+
+fn main() {
+    // Client creation error is ignored; e.g., AWS_XRAY_DAEMON_ADDRESS is not set
+    let client = DaemonClient::from_lambda_env().into_infallible();
+    // Context creation error is ignored; e.g., _X_AMZN_TRACE_ID is not set
+    let context = SubsegmentContext::from_lambda_env(client).into_infallible();
+
+    do_s3_get_object(&context);
+}
+
+fn do_s3_get_object(context: &impl Context) {
+    let subsegment = context.enter_subsegment(AwsNamespace::new("S3", "GetObject"));
+
+    // call S3 GetObject ...
+}
+```
+
 ## Extensions
 
 - [`xray-lite-aws-sdk`](./xray-lite-aws-sdk/): extension for [AWS SDK for Rust](https://aws.amazon.com/sdk-for-rust/)
diff --git a/xray-lite-aws-sdk/README.md b/xray-lite-aws-sdk/README.md
index 9bec96e..cffa7fa 100644
--- a/xray-lite-aws-sdk/README.md
+++ b/xray-lite-aws-sdk/README.md
@@ -23,11 +23,11 @@ The following example shows how to report a subsegment for each attempt of the S
 
 ```rust
 use aws_config::BehaviorVersion;
-use xray_lite::{Client, SubsegmentContext};
+use xray_lite::{DaemonClient, SubsegmentContext};
 use xray_lite_aws_sdk::ContextExt as _;
 
 async fn get_object_from_s3() {
-    let xray_client = Client::from_lambda_env().unwrap();
+    let xray_client = DaemonClient::from_lambda_env().unwrap();
     let xray_context = SubsegmentContext::from_lambda_env(xray_client).unwrap();
 
     let config = aws_config::load_defaults(BehaviorVersion::latest()).await;