Port SDK (Rust)

Rust crate for interacting with the Port REST APIs. The SDK aims to wrap the Swagger definition at https://api.port.io/swagger/json with type-safe request/response models, predictable error handling, and ergonomics that match the Rust ecosystem.

Status

Actively under construction. See TODO.md for the current implementation plan.

Getting Started

1. Install Rust toolchain
   Use rustup to install the latest stable toolchain.
2. Clone the repo

   git clone https://github.com/port-experimental/port-sdk-rs.git
   cd port-sdk-rs
   

3. Verify the code compiles

   cargo check
   

Usage Guide

use port_sdk::{PortClient, PortConfig, auth::AuthStrategy};

# #[tokio::main]
# async fn main() -> Result<(), port_sdk::error::PortError> {
// Load from environment variables (`PORT_CLIENT_ID`, `PORT_CLIENT_SECRET`, etc.).
let client = PortClient::from_env()?;

// Or configure explicitly.
/*
let config = PortConfig::builder()
    .auth(AuthStrategy::StaticToken("my-api-token".into()))
    .build()?;
let client = PortClient::from_config(config)?;
*/

// Call resource helpers. Responses deserialize into typed structs or serde_json::Value.
let blueprints: serde_json::Value = client.get("/blueprints").await?;
println!("known blueprints: {blueprints}");
# Ok(())
# }

• Authentication helpers live under port_sdk::auth.
• High-level flows are available in port_sdk::apis (e.g., apis::blueprints::list).
• See docs/usage.md for end-to-end walkthroughs and troubleshooting tips.

Crate Layout

• src/lib.rs – crate root re-exporting the public API surface.
• src/client.rs – HTTP client that wraps reqwest and applies authentication.
• src/error.rs – error types surfaced to SDK consumers.
• src/types.rs – placeholder for structs generated from the Swagger schema (to be implemented).
• src/apis.rs – placeholder for higher-level endpoint wrappers (to be implemented).
• docs/ – developer-facing documentation (architecture, build, testing, release).
• TODO.md – detailed roadmap for completing the SDK.

Development Workflow

1. Follow the tasks in TODO.md sequentially. Each task explains why it exists so newcomers can learn the rationale.
2. Keep the documentation under docs/ updated when adding new functionality.
3. Run the standard cargo commands:

   cargo fmt
   cargo clippy --all-targets --all-features
   cargo test --all-features
   

4. When adding network calls, prefer dependency injection or test doubles for unit tests to avoid flaky integration runs.

Configuration & Authentication

• Load configuration from a .env file or shell environment variables. Call PortClient::from_env() or PortConfig::from_env() to bootstrap defaults.
• Provide OAuth client credentials via PORT_CLIENT_ID and PORT_CLIENT_SECRET (optionally PORT_TOKEN_URL). The SDK automatically exchanges them for access tokens.
• Supply a pre-issued access token with PORT_ACCESS_TOKEN (or legacy PORT_API_TOKEN) if you manage tokens externally.
• Control the target region using PORT_REGION (eu default, us supported) or override with PORT_BASE_URL. Base URL defaults to the EU endpoint when not specified.
• Configure outbound proxies with PORT_PROXY_URL (falls back to HTTP_PROXY / HTTPS_PROXY) and optional PROXY_AUTH_USERNAME / PROXY_AUTH_PASSWORD.
• Tune request behaviour with PORT_TIMEOUT (milliseconds) and PORT_MAX_RETRIES. Disable retries by setting PORT_RETRY_DISABLED=1.
• Enable request tracing by setting PORT_TRACING_ENABLED=1 when the crate is built with the telemetry feature.

Testing with .env

1. Copy the skeleton file and fill in credentials:

   cp .env.example .env
   $EDITOR .env
   

2. Provide either PORT_CLIENT_ID/PORT_CLIENT_SECRET (plus overrides such as PORT_TOKEN_URL) or a pre-issued token via PORT_ACCESS_TOKEN.
3. Run cargo test to ensure the SDK can authenticate using the supplied values—end-to-end tests read from the environment at runtime.
4. For manual experiments, run snippets from the examples/ directory (cargo run --example ...) or the code in docs/usage.md; the runtime automatically loads .env via dotenvy.

Documentation

Additional context lives in:

• docs/architecture.md – module responsibilities, data flow, and security guidelines.
• docs/build_and_release.md – end-to-end instructions for building, testing, and publishing the crate.
• docs/testing_strategy.md – recommended testing layers, including unit, integration, and contract testing.
• CHANGELOG.md – history of notable changes and release notes.
• docs/feature_flags.md – overview of optional crate features and how to enable them.
• docs/logging.md – tracing integration and safe logging practices.
• docs/examples.md – guide to the walkthroughs in the examples/ directory.

Releasing

High-level release checklist:

1. Ensure cargo fmt, cargo clippy, and cargo test pass on the main branch.
2. Update CHANGELOG.md (to be added) with notable changes.
3. Bump the crate version in Cargo.toml.
4. Follow docs/build_and_release.md for cargo publish preparation steps (audit, dry run, tagging).

Contributing

Issues and pull requests are welcome. Please include tests and documentation updates for any new feature to keep the SDK reliable and easy to understand.

Quick Links

• Architecture
• Usage Guide
• Testing Strategy
• Examples
• Publishing Checklist
• Parity with port-js