Rusoto is an AWS SDK for Rust.

Rusoto consists of one core crate, containing common functionality shared across services, and then a crate for each supported service.

Services are generated from the botocore project's API definitions.

Rusoto also provides a credential crate. The credential crate provides the necessary functionality for properly loading and handling AWS credentials.

If you are experiencing problems with rusoto, or would like clarification regarding something, please don't hesitate to contact us. You can reach us by opening an issue on the GitHub page for the project with the relevant information (code snippets and error messages are very helpful!). Alternatively, you can join us on the #rusoto channel on irc.freenode.net.

Rusoto provides a crate for each AWS service it supports, containing a client and all of the associated types for that service. A full list of these services can be found on the Supported AWS Services page.

It also provides a core crate called rusoto_core, containing all shared functionality across services, such as the list of regions, signed request senders, and credential loading.

Consult the rustdoc documentatation by running cargo doc or visiting the online API documentation for the latest crates.io release.

An example of using Rusoto's DynamoDB API to list the names of all the tables in a database:

Cargo.toml:

[package]
name = "my-crate"
version = "0.1.0"
authors = ["My Name <my@email.com>"]

[dependencies]
rusoto_core = "0.35"
rusoto_dynamodb = "0.35"

Rust code:

extern crate rusoto_core;
extern crate rusoto_dynamodb;

use std::default::Default;

use rusoto_core::Region;
use rusoto_dynamodb::{DynamoDb, DynamoDbClient, ListTablesInput};

fn main() {
  let client = DynamoDbClient::new(Region::UsEast1);
  let list_tables_input: ListTablesInput = Default::default();

  match client.list_tables(list_tables_input).sync() {
    Ok(output) => {
      match output.table_names {
        Some(table_name_list) => {
          println!("Tables in database:");

          for table_name in table_name_list {
            println!("{}", table_name);
          }
        }
        None => println!("No tables in database!"),
      }
    }
    Err(error) => {
      println!("Error: {:?}", error);
    }
  }
}

Rusoto's current focus is to support all AWS services. This means higher level functionality present in other AWS SDKs are not currently available in Rusoto. See https://github.com/rusoto/rusoto/issues/1098 for more information on where Rusoto efforts are currently focused.

While Rusoto doesn't support various higher level functionality or better ergonomics, there are third party crates available that use Rusoto and provide this behavior.

A non-exhaustive list of projects that build on Rusoto to make it more ergonomic or provide higher level functionality:

1. dynomite: make your rust types fit dynamodb and visa versa
2. envy-store: deserialize AWS Parameter Store values into typesafe structs
3. S4: Simpler Simple Storage Service for Rust

If you'd like to add an example to this list, please open an issue or pull request on the rusoto.org repo.

Rusoto uses the log logging facade. For tests, Rusoto uses env_logger.

In order to see logging output (e.g. the actual requests made to AWS), env_logger needs to be initialized:

extern crate rusoto_core;
extern crate rusoto_s3;
extern crate env_logger;

use std::default::Default;

use rusoto_core::Region;
use rusoto_s3::{S3, S3Client, ListObjectsRequest};

fn main() {
    let _ = env_logger::try_init(); // This initializes the `env_logger`

    let bare_s3 = S3Client::new(Region::UsWest2);

    let mut list_request = ListObjectsRequest::default();
    list_request.bucket = "rusototester".to_string();
    let result = bare_s3.list_objects(list_request).sync().unwrap();
    println!("result is {:?}", result);
}

To see the output of logging from integration tests, the command needs to be run as follows:

RUST_LOG=rusoto,hyper=debug cargo test --features all

To get the logging output as well as the output of any println! statements, run:

RUST_LOG=rusoto,hyper=debug cargo test --features all -- --nocapture

If more debugging is required, all debug info including details from the compiler can be seen by setting RUST_LOG to debug. This will be noisy but will give a lot of debug information. For example:

RUST_LOG=debug cargo test --features all

Currently, performance isn't benchmarked.

To get the best runtime performance in a project using Rusoto, compile with the --release flag.

For example: cargo build --release

As of Rusoto 0.36.0, we expose the http1_read_buf_exact_size setting in the hyper HTTP client. This can greatly improve performance dealing with payloads greater than 100MB. See https://github.com/rusoto/rusoto/pull/1227 for more information.

Example of increasing the buffer size from the default of 8KB to 2MB:

extern crate rusoto_core;
extern crate rusoto_ecs;

use rusoto_ecs::{Ecs, EcsClient, ListClustersRequest};
use rusoto_core::{Region, DefaultCredentialsProvider};
use rusoto_core::request::{HttpClient, HttpConfig};

fn main() {
    // EcsClient configuration demonstrates setting the hyper read_buf_size option
    // to 2MB:
    let cred_provider =  DefaultCredentialsProvider::new().unwrap();
    let mut http_config_with_bigger_buffer = HttpConfig::new();
    http_config_with_bigger_buffer.read_buf_size(1024 * 1024 * 2);
    let http_provider = HttpClient::new_with_config(http_config_with_bigger_buffer).unwrap();

    let ecs = EcsClient::new_with(http_provider, cred_provider, Region::UsEast1);

    match ecs.list_clusters(ListClustersRequest::default()).sync() {
        Ok(clusters) => {
            for arn in clusters.cluster_arns.unwrap_or(vec![]) {
                println!("arn -> {:?}", arn);
            }
        }
        Err(err) => {
            panic!("Error listing container instances {:#?}", err);
        }
    }
}

• Improve XML parsing

With async support, the easiest migration is to use the new simple() constructor on clients and add .sync() to the function calls.

Rusoto 0.31.0:

extern crate rusoto_core;
extern crate rusoto_polly;

use rusoto_polly::{Polly, PollyClient, DescribeVoicesInput};
use rusoto_core::{DefaultCredentialsProvider, Region, default_tls_client};

...
let credentials = DefaultCredentialsProvider::new().unwrap();
let client = PollyClient::new(default_tls_client().unwrap(), credentials, Region::UsEast1);
let request = DescribeVoicesInput::default();

println!("{:?}", client.describe_voices(&request).unwrap());

Rusoto 0.32.0 with async:

extern crate rusoto_core;
extern crate rusoto_polly;

use rusoto_polly::{Polly, PollyClient, DescribeVoicesInput};
use rusoto_core::Region;

...
let client = PollyClient::simple(Region::UsEast1);
let request = DescribeVoicesInput::default();

println!("{:?}", client.describe_voices(&request).sync().unwrap());

Note:

• DefaultCredentialsProvider isn't required with the ::simple() constructor
• default_tls_client isn't required with the ::simple() constructor
• .sync() is called on the result from describe_voices. This blocks until the call is finished.

As of Rusoto 0.25.0, the Rusoto crate is now deprecated. This decision was made because the single crate implementing all AWS services was too large to compile, especially on TravisCI and Appveyor. The new main crate is rusoto_core and all services now have their own crate.

To continue implementing new services and reducing compilation times, we've extracted a few core crates and every AWS service we support now has its own crate.

rusoto_core now contains the core functionality of Rusoto: AWS signature handling, regions, requests to services and XML helpers.

rusoto_mock was also extracted. Crate users shouldn't need this: it's for developing on Rusoto itself.

rusoto_credential remains its own crate, providing AWS credential sourcing. If you're working on something that uses AWS and Rusoto doesn't support it, you can use that crate instead of rolling your own AWS credential providers.

The new service crates depend on rusoto_core.

Previously, to bring in a Rusoto implementation of an AWS service, you'd specify something like this in your Cargo.toml file:

rusoto = {version = "0.24", features = ["rds"]}

Now, you'd bring in services like this:

rusoto_core = {version = "0.25.0"}
rusoto_rds = {version = "0.25.0"}

Once the new crates have been brought in, use the new crates in your code. A sample before:

extern crate rusoto;

use rusoto::rds::{RdsClient, CreateDBInstanceMessage, DescribeDBInstancesMessage};
use rusoto::{DefaultCredentialsProvider, Region, default_tls_client};

And after:

extern crate rusoto_core;
extern crate rusoto_rds;
use rusoto_rds::{Rds, RdsClient, CreateDBInstanceMessage, DescribeDBInstancesMessage};
use rusoto_core::{DefaultCredentialsProvider, Region, default_tls_client};

Note there are now two crates required: rusoto_core as well as the RDS crate, rusoto_rds. There's also a new trait for each service. In this case it's Rds and we bring that in. This is used to make calls to services easier to test and improve ergonomics of using Rusoto clients.

If AWS credentials aren't found locally, Rusoto attempts to query the ECS container role provider, then the EC2 Instance Profile provider. When running locally, such as in a command line tool, timing out waiting for those services can take 30 seconds or more.

To improve responsiveness of credential sourcing, timeouts can be provided to the credential provider. This example uses a 200ms timeout:

extern crate rusoto_core;
extern crate rusoto_s3;

use rusoto_core::credential::ChainProvider;
use rusoto_core::request::HttpClient;
use rusoto_core::Region;
use rusoto_s3::{S3, S3Client};
use std::time::{Duration, Instant};

fn main() {
    let mut chain = ChainProvider::new();
    chain.set_timeout(Duration::from_millis(200));
    let s3client = S3Client::new_with(
        HttpClient::new().expect("failed to create request dispatcher"),
        chain,
        Region::UsEast1,
    );

    let start = Instant::now();
    println!("Starting up at {:?}", start);

    match s3client.list_buckets().sync() {
        Err(e) => println!("Error listing buckets: {}", e),
        Ok(buckets) => println!("Buckets found: {:?}", buckets),
    };
    println!("Took {:?}", Instant::now().duration_since(start));
}

Now, if Rusoto can't find any credentials within 200ms, it will return an error like this:

Error listing buckets: Couldn't find AWS credentials in environment, credentials file, or IAM role.

Last updated for Rusoto 0.34.0 with rusoto_credential 0.13.0.