Moved QLDB code examples into qldb directory; added create-ledger cod…

…e example (#485)

* Moved QLDB code examples into qldb directory; added create-ledger code example

* Removed some leftover qldb files

* Renamed QLDB helloword.rs as qldb-helloworld.rs

* Updated create-ledger code example based on feedback

* Added readme with descriptions of all three QLDB code examples; slightly modified the description of the ledger in the hello world code example

* Update QLDB readme

Small language tweak suggesting the high level driver

Co-authored-by: Russell Cohen <rcoh@amazon.com>

aws/sdk/examples/qldbsession-helloworld/Cargo.toml → aws/sdk/examples/qldb/Cargo.toml

@@ -1,18 +1,23 @@
 [package]
-name = "qldbsession-helloworld"
+name = "qldb-code-examples"
 version = "0.1.0"
-authors = ["Russell Cohen <rcoh@amazon.com>"]
+authors = ["Russell Cohen <rcoh@amazon.com>", "Doug Schwartz <dougsch@amazon.com>"]
 edition = "2018"
 
 # See more keys and their definitions at https://doc.rust-lang.org/cargo/reference/manifest.html
 
 [dependencies]
+qldb = { package = "aws-sdk-qldb", path = "../../build/aws-sdk/qldb" }
 qldbsession = { package = "aws-sdk-qldbsession", path = "../../build/aws-sdk/qldbsession" }
-### To use native TLS:
-# qldbsession = { package = "aws-sdk-qldbsession", path = "../../build/aws-sdk/qldbsession", default-features = false, features = ["native-tls"] }
+aws-types = { path = "../../build/aws-sdk/aws-types" }
 
 tokio = { version = "1", features = ["full"] }
 
+# For command-line arguments
+structopt = { version = "0.3", default-features = false }
+
+tracing-subscriber = { version = "0.2.16", features = ["fmt"] }
+
 # used only for static endpoint configuration:
 http = "0.2.3"
 

aws/sdk/examples/qldb/README.md

@@ -0,0 +1,54 @@
+# AWS SDK for Rust code examples for Amazon QLDB
+
+Amazon Quantum Ledger Database (Amazon QLDB) is a fully managed ledger database that provides a transparent, immutable, and cryptographically verifiable transaction log owned by a central trusted authority.
+
+## create-ledger
+
+This code example creates an Amazon QLDB ledger.
+
+### Usage
+
+```cargo run --bin create-ledger -l LEDGER [-r REGION] [-v]```
+
+where:
+
+- _LEDGER_ is the name of the ledger to create.
+- _REGION_ is the region in which the client is created.
+  If not supplied, uses the value of the **AWS_DEFAULT_REGION** environment variable.
+  If the environment variable is not set, defaults to **us-west-2**.
+- __-v__ enables displaying additional information.
+
+## list-ledgers
+
+This code example lists your Amazon QLDB ledgers.
+
+### Usage
+
+```cargo run --bin list-ledgers [-r REGION] [-v]```
+
+where:
+
+- _REGION_ is the region in which the client is created.
+  If not supplied, uses the value of the **AWS_DEFAULT_REGION** environment variable.
+  If the environment variable is not set, defaults to **us-west-2**.
+- __-v__ enables displaying additional information.
+
+## qldb-helloworld
+
+This code example creates a low-level Amazon QLDB session against a ledger.
+
+The QldbSession API is not intended to be used directly. Instead, we recommend using a higher-level driver, such as the Amazon QLDB Driver for Rust.
+
+### Usage
+
+cargo run --bin qldb-helloworld -l LEDGER [-r REGION] [-v]
+
+where:
+
+- _LEDGER_ is the name of the ledger to create the session against.
+- _REGION_ is the region in which the client is created.
+  If not supplied, uses the value of the **AWS_DEFAULT_REGION** environment variable.
+  If the environment variable is not set, defaults to **us-west-2**.
+- __-v__ enables displaying additional information.
+
+## 

aws/sdk/examples/qldb/src/bin/create-ledger.rs

@@ -0,0 +1,75 @@
+/*
+ * Copyright Amazon.com, Inc. or its affiliates. All Rights Reserved.
+ * SPDX-License-Identifier: Apache-2.0.
+ */
+
+use aws_types::region::ProvideRegion;
+
+use qldb::model::PermissionsMode;
+use qldb::{Client, Config, Error, Region};
+
+use structopt::StructOpt;
+use tracing_subscriber::fmt::format::FmtSpan;
+use tracing_subscriber::fmt::SubscriberBuilder;
+
+#[derive(Debug, StructOpt)]
+struct Opt {
+    /// The region. Overrides environment variable AWS_DEFAULT_REGION.
+    #[structopt(short, long)]
+    default_region: Option<String>,
+
+    /// The name of the ledger.
+    #[structopt(short, long)]
+    ledger: String,
+
+    /// Whether to display additional runtime information
+    #[structopt(short, long)]
+    verbose: bool,
+}
+
+/// Creates an Amazon QLDB ledger.
+/// # Arguments
+///
+/// * `-l LEDGER` - The name of the ledger.
+/// * `[-d DEFAULT-REGION]` - The region in which the client is created.
+///    If not supplied, uses the value of the **AWS_DEFAULT_REGION** environment variable.
+///    If the environment variable is not set, defaults to **us-west-2**.
+/// * `[-v]` - Whether to display additional information.
+#[tokio::main]
+async fn main() -> Result<(), Error> {
+    let Opt {
+        default_region,
+        ledger,
+        verbose,
+    } = Opt::from_args();
+
+    let region = default_region
+        .as_ref()
+        .map(|region| Region::new(region.clone()))
+        .or_else(|| aws_types::region::default_provider().region())
+        .unwrap_or_else(|| Region::new("us-west-2"));
+
+    if verbose {
+        println!("QLDB client version: {}\n", qldb::PKG_VERSION);
+        println!("Region:              {:?}", &region);
+
+        SubscriberBuilder::default()
+            .with_env_filter("info")
+            .with_span_events(FmtSpan::CLOSE)
+            .init();
+    }
+
+    let conf = Config::builder().region(region).build();
+    let client = Client::from_conf(conf);
+
+    let result = client
+        .create_ledger()
+        .name(ledger)
+        .permissions_mode(PermissionsMode::AllowAll)
+        .send()
+        .await?;
+
+    println!("ARN: {}", result.arn.unwrap());
+
+    Ok(())
+}

aws/sdk/examples/qldb/src/bin/list-ledgers.rs

@@ -0,0 +1,72 @@
+/*
+ * Copyright Amazon.com, Inc. or its affiliates. All Rights Reserved.
+ * SPDX-License-Identifier: Apache-2.0.
+ */
+
+use aws_types::region::ProvideRegion;
+
+//use qldbsession::model::StartSessionRequest;
+use qldb::{Client, Config, Error, Region};
+
+use structopt::StructOpt;
+use tracing_subscriber::fmt::format::FmtSpan;
+use tracing_subscriber::fmt::SubscriberBuilder;
+
+#[derive(Debug, StructOpt)]
+struct Opt {
+    /// The region. Overrides environment variable AWS_DEFAULT_REGION.
+    #[structopt(short, long)]
+    default_region: Option<String>,
+
+    /// Whether to display additional runtime information
+    #[structopt(short, long)]
+    verbose: bool,
+}
+
+/// Lists your Amazon QLDB ledgers.
+/// # Arguments
+///
+/// * `[-d DEFAULT-REGION]` - The region in which the client is created.
+///    If not supplied, uses the value of the **AWS_DEFAULT_REGION** environment variable.
+///    If the environment variable is not set, defaults to **us-west-2**.
+/// * `[-v]` - Whether to display additional information.
+#[tokio::main]
+async fn main() -> Result<(), Error> {
+    let Opt {
+        default_region,
+        verbose,
+    } = Opt::from_args();
+
+    let region = default_region
+        .as_ref()
+        .map(|region| Region::new(region.clone()))
+        .or_else(|| aws_types::region::default_provider().region())
+        .unwrap_or_else(|| Region::new("us-west-2"));
+
+    if verbose {
+        println!("OLDB client version: {}\n", qldb::PKG_VERSION);
+        println!("Region:              {:?}", &region);
+
+        SubscriberBuilder::default()
+            .with_env_filter("info")
+            .with_span_events(FmtSpan::CLOSE)
+            .init();
+    }
+
+    let conf = Config::builder().region(region).build();
+    let client = Client::from_conf(conf);
+
+    let result = client.list_ledgers().send().await?;
+
+    if let Some(ledgers) = result.ledgers {
+        for ledger in ledgers {
+            println!("* {:?}", ledger);
+        }
+
+        if result.next_token.is_some() {
+            todo!("pagination is not yet demonstrated")
+        }
+    }
+
+    Ok(())
+}

aws/sdk/examples/qldb/src/bin/qldb-helloworld.rs

@@ -0,0 +1,79 @@
+/*
+ * Copyright Amazon.com, Inc. or its affiliates. All Rights Reserved.
+ * SPDX-License-Identifier: Apache-2.0.
+ */
+
+use aws_types::region::ProvideRegion;
+
+use qldbsession::model::StartSessionRequest;
+use qldbsession::{Client, Config, Error, Region};
+
+use structopt::StructOpt;
+use tracing_subscriber::fmt::format::FmtSpan;
+use tracing_subscriber::fmt::SubscriberBuilder;
+
+#[derive(Debug, StructOpt)]
+struct Opt {
+    /// The region. Overrides environment variable AWS_DEFAULT_REGION.
+    #[structopt(short, long)]
+    default_region: Option<String>,
+
+    /// Specifies the ledger
+    #[structopt(short, long)]
+    ledger: String,
+
+    /// Whether to display additional runtime information
+    #[structopt(short, long)]
+    verbose: bool,
+}
+
+/// Creates a low-level Amazon QLDB session against a ledger.
+/// # Arguments
+///
+/// * `-l LEDGER` - The name of the ledger to start a new session against.
+/// * `[-d DEFAULT-REGION]` - The region in which the client is created.
+///    If not supplied, uses the value of the **AWS_DEFAULT_REGION** environment variable.
+///    If the environment variable is not set, defaults to **us-west-2**.
+/// * `[-v]` - Whether to display additional information.
+#[tokio::main]
+async fn main() -> Result<(), Error> {
+    let Opt {
+        ledger,
+        default_region,
+        verbose,
+    } = Opt::from_args();
+
+    let region = default_region
+        .as_ref()
+        .map(|region| Region::new(region.clone()))
+        .or_else(|| aws_types::region::default_provider().region())
+        .unwrap_or_else(|| Region::new("us-west-2"));
+
+    if verbose {
+        println!("OLDB client version: {}\n", qldb::PKG_VERSION);
+        println!("Region:              {:?}", &region);
+        println!("Ledger:              {}", ledger);
+
+        SubscriberBuilder::default()
+            .with_env_filter("info")
+            .with_span_events(FmtSpan::CLOSE)
+            .init();
+    }
+
+    let conf = Config::builder().region(region).build();
+    let client = Client::from_conf(conf);
+    let result = client
+        .send_command()
+        .start_session(StartSessionRequest::builder().ledger_name(ledger).build())
+        .send()
+        .await?;
+
+    match result.start_session {
+        Some(s) => {
+            println!("Your session id: {:?}", s.session_token);
+        }
+        None => unreachable!("a start session will result in an Err or a start session result"),
+    }
+
+    Ok(())
+}