Tapis Rust SDK

A comprehensive Rust SDK for the Tapis Framework, providing type-safe, async clients for Tapis v3 services.

About Tapis

Tapis is a distributed web-based API framework for science and engineering research and education. It provides authentication, authorization, and a wide range of digital research infrastructure services across multiple institutional and data center resources.

Overview

The Tapis Rust SDK is structured as a workspace containing multiple service-specific crates. You can either use the umbrella tapis-sdk crate for convenience or depend on individual service crates as needed.

Available Crates

Crate	Description	Documentation
tapis-sdk	Parent crate re-exporting all Tapis services
tapis-authenticator	Authentication and OAuth2 token management
tapis-pods	Pods-as-a-Service (PaaS) for Docker containers

Installation

Add to your Cargo.toml:

[dependencies]
tapis-sdk = "0.1"
tokio = { version = "1", features = ["full"] }

Or use individual crates:

[dependencies]
tapis-authenticator = "0.1"
tapis-pods = "0.1"
tokio = { version = "1", features = ["full"] }

Quick Start

Authentication

Create a JWT token using username and password:

use tapis_sdk::authenticator::{TapisAuthenticator, models::NewToken};

#[tokio::main]
async fn main() -> Result<(), Box<dyn std::error::Error>> {
    // Initialize the authenticator client
    let client = TapisAuthenticator::new(
        "https://tacc.tapis.io",
        None, // No token needed for creating tokens
    )?;

    // Create a new JWT token
    let new_token = NewToken {
        username: Some("your_username".to_string()),
        password: Some("your_password".to_string()),
        grant_type: Some("password".to_string()),
        ..Default::default()
    };

    let response = client.tokens.create_token(new_token).await?;
    
    if let Some(result) = response.result {
        if let Some(access_token) = result.access_token.access_token {
            println!("Access Token: {}", access_token);
        }
    }

    Ok(())
}

List Pods

Retrieve all pods using the Pods service:

use tapis_sdk::pods::TapisPods;

#[tokio::main]
async fn main() -> Result<(), Box<dyn std::error::Error>> {
    // Initialize the Pods client with your JWT token
    let client = TapisPods::new(
        "https://tacc.tapis.io/v3",
        "your_jwt_token_here"
    )?;

    // List all pods
    let response = client.pods.list_pods().await?;
    
    println!("Found {} pods", response.result.len());
    for pod in response.result {
        println!("Pod ID: {}", pod.pod_id);
        if let Some(status) = pod.status {
            println!("  Status: {}", status);
        }
    }

    Ok(())
}

Create a Pod

Deploy a new pod from a Docker image:

use tapis_sdk::pods::{TapisPods, models::NewPod};

#[tokio::main]
async fn main() -> Result<(), Box<dyn std::error::Error>> {
    let client = TapisPods::new(
        "https://tacc.tapis.io/v3",
        "your_jwt_token_here"
    )?;

    // Create a new pod
    let new_pod = NewPod {
        pod_id: Some("my-nginx-pod".to_string()),
        pod_template: Some("template-nginx".to_string()),
        description: Some("My NGINX web server".to_string()),
        ..Default::default()
    };

    let response = client.pods.create_pod(new_pod).await?;
    
    println!("Pod created: {:?}", response.result);

    Ok(())
}

Get Pod Details

use tapis_sdk::pods::TapisPods;

#[tokio::main]
async fn main() -> Result<(), Box<dyn std::error::Error>> {
    let client = TapisPods::new(
        "https://tacc.tapis.io/v3",
        "your_jwt_token_here"
    )?;

    // Get specific pod details
    let pod_id = "my-nginx-pod";
    let response = client.pods.get_pod(pod_id).await?;
    
    if let Some(pod) = response.result {
        println!("Pod: {}", pod.pod_id);
        println!("Status: {:?}", pod.status);
        println!("URL: {:?}", pod.url);
    }

    Ok(())
}

Module Organization

When using the umbrella tapis-sdk crate, services are organized under namespaced modules:

use tapis_sdk::authenticator::TapisAuthenticator;
use tapis_sdk::pods::TapisPods;

// Access models
use tapis_sdk::authenticator::models::NewToken;
use tapis_sdk::pods::models::NewPod;

Features

TLS Configuration

Both service crates support native TLS and rustls:

[dependencies]
tapis-sdk = { version = "0.1", default-features = false, features = ["rustls-tls"] }

Available features:

native-tls (default): Uses system native TLS
rustls-tls: Uses pure Rust TLS implementation

Examples

Check out the examples/ directory in each crate for more comprehensive examples:

Run examples with:

# Authenticator example
export TAPIS_USERNAME=your_username
export TAPIS_PASSWORD=your_password
cargo run --example authenticator_example

# Pods example
export TAPIS_TOKEN=your_jwt_token
cargo run --example tapis_token_example

API Documentation

Each service provides comprehensive API documentation:

Authenticator: OAuth2, token management, client management, profiles
Pods: Pod management, templates, volumes, snapshots, images, permissions

Full API documentation is available at docs.rs/tapis-sdk.

Development

Building from Source

git clone https://github.com/tapis-project/tapis-rust-sdk.git
cd tapis-rust-sdk
cargo build --release

Running Tests

cargo test --all

Publishing

The crates are published separately to crates.io:

Publish service crates first:

cd tapis-authenticator && cargo publish
cd ../tapis-pods && cargo publish

Then publish the parent crate:
```
cargo publish
```

Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

License

This project is licensed under the BSD-3-Clause License - see the LICENSE file for details.

Resources

Support

For support, please contact: cicsupport@tacc.utexas.edu

Acknowledgments

This SDK is developed and maintained by the Texas Advanced Computing Center (TACC).

tapis-sdk 0.1.1