Skip to content

API Reference

Complete API reference for Substation's packages: OSClient, SwiftTUI, and CrossPlatformTimer.

Quick Reference

Package Overview

Package Purpose When to Use
OSClient OpenStack API client Interacting with OpenStack services
SwiftTUI Terminal UI framework Building terminal UIs
CrossPlatformTimer Timer utilities Periodic tasks, animations

Quick Start

import OSClient
import SwiftTUI
import CrossPlatformTimer

// Connect to OpenStack
let client = try await OpenStackClient.connect(
    config: OpenStackConfig(authUrl: "https://keystone.example.com:5000/v3"),
    credentials: OpenStackCredentials(
        username: "admin",
        password: "secret",
        projectName: "admin"
    )
)

// Initialize terminal UI
let screen = SwiftTUI.initializeScreen()
defer { SwiftTUI.cleanup(screen) }

// Create auto-refresh timer
let timer = createCompatibleTimer(interval: 5.0, repeats: true) {
    Task {
        await refreshData()
    }
}

Detailed Documentation

OSClient - OpenStack API Library

What's in it:

  • OpenStackClient initialization and configuration
  • Service clients (Nova, Neutron, Cinder, Glance, etc.)
  • Data models (Server, Network, Volume, etc.)
  • Cache management
  • Error handling and recovery
  • Data managers for complex operations
  • Performance monitoring

Read this when you need to:

  • Connect to OpenStack
  • Manage OpenStack resources
  • Configure caching behavior
  • Handle OpenStack errors
  • Monitor API performance

SwiftTUI - Terminal UI Framework

What's in it:

  • Core rendering components
  • UI components (Text, List, Table, Form)
  • Color system
  • Layout system
  • Event handling
  • Performance optimization
  • Cross-platform considerations

Read this when you need to:

  • Build terminal UIs
  • Render lists and tables
  • Handle keyboard input
  • Create forms
  • Optimize rendering performance

Integration Guide

What's in it:

  • CrossPlatformTimer API
  • Complete application examples
  • Common integration patterns
  • Best practices
  • Testing strategies
  • Troubleshooting

Read this when you need to:

  • Build complete applications
  • Integrate OSClient with SwiftTUI
  • Implement auto-refresh
  • Create multi-view applications
  • Handle timers and periodic tasks

Common Operations Quick Reference

OpenStack Operations

// List servers
let servers = try await client.nova.servers.list()

// Create server
let server = try await client.nova.servers.create(
    name: "my-server",
    flavorRef: flavorId,
    imageRef: imageId
)

// Delete server
try await client.nova.servers.delete(serverId)

// Get cache statistics
let stats = await client.cacheManager.statistics()
print("Cache hit rate: \(stats.hitRate * 100)%")

Terminal UI Operations

// Render text
await SwiftTUI.render(
    Text("Hello, World!").bold().color(.blue),
    on: surface,
    in: bounds
)

// Render list
let list = List(items: items)
    .selectedIndex(0)
    .scrollable(true)
await SwiftTUI.render(list, on: surface, in: bounds)

// Handle input
let key = SwiftTUI.getInput(screen)
switch key {
case KEY_UP: moveUp()
case KEY_DOWN: moveDown()
case KEY_ENTER: select()
default: break
}

// Refresh screen
SwiftTUI.refresh(screen)

Timer Operations

// Create repeating timer
let timer = createCompatibleTimer(interval: 5.0, repeats: true) {
    print("Timer fired!")
}

// Create one-shot timer
let oneShot = createCompatibleTimer(interval: 5.0, repeats: false) {
    print("One-time action")
}

// Clean up
timer.invalidate()

API Design Principles

1. Type Safety

All APIs use Swift's strong type system for compile-time safety:

// Compile-time type checking
let server: Server = try await client.nova.servers.get(id)
let status: ServerStatus = server.status  // Enum, not string

// Invalid: Won't compile
// let status: String = server.status

2. Actor-Based Concurrency

All service clients are actors for thread safety:

public actor OpenStackClient { }
public actor NovaService { }
public actor ServerManager { }

// Safe concurrent access
Task {
    let servers1 = try await client.nova.servers.list()
}
Task {
    let servers2 = try await client.nova.servers.list()
}

3. Async/Await Throughout

All I/O operations use async/await:

// All async
let servers = try await client.nova.servers.list()
let networks = try await client.neutron.networks.list()

// No callbacks or completion handlers

4. Comprehensive Error Handling

Typed errors with recovery strategies:

do {
    let server = try await client.nova.servers.create(...)
} catch OpenStackError.quotaExceeded(let message) {
    // Handle quota error
} catch OpenStackError.conflict(let message) {
    // Handle conflict
} catch {
    // Handle other errors
}

5. Performance by Default

Intelligent caching enabled by default:

// First call: API request
let servers1 = try await client.nova.servers.list()  // 2 seconds

// Second call: Cache hit
let servers2 = try await client.nova.servers.list()  // < 1ms

Architecture Overview

graph TB
    subgraph "Public API"
        Client[OpenStackClient]
        Services[Service Clients]
        Models[Data Models]
    end

    subgraph "Infrastructure"
        Core[ClientCore]
        Cache[CacheManager]
        Auth[AuthManager]
    end

    subgraph "Extensions"
        DataManagers[Data Managers]
        Performance[Performance]
        Telemetry[Telemetry]
    end

    Client --> Services
    Services --> Models
    Client --> Core
    Core --> Cache
    Core --> Auth
    Services --> DataManagers
    DataManagers --> Performance
    DataManagers --> Telemetry

Key Concepts

Caching

Intelligent multi-level caching for 60-80% API call reduction:

  • L1 Cache: In-memory, fastest (< 1ms)
  • L2 Cache: Session-persistent
  • L3 Cache: Disk-backed, survives restarts

See: Caching Concepts

Resource-Specific TTLs

Different cache lifetimes for different resource types:

Resource TTL Why
Auth tokens 1 hour Keystone token lifetime
Flavors, Images 15 minutes Rarely change
Networks 5 minutes Moderately dynamic
Servers, Volumes 2 minutes Highly dynamic

See: Performance Tuning

Error Recovery

Automatic retry with exponential backoff:

  • Attempt 1: Immediate
  • Attempt 2: 1 second delay
  • Attempt 3: 2 seconds delay
  • Attempt 4: 4 seconds delay

See: Error Handling

Source Code Locations

API implementation is organized across multiple packages:

  • /Sources/OSClient/ - OpenStack client library
  • /Sources/SwiftTUI/ - Terminal UI framework
  • /Sources/CrossPlatformTimer/ - Timer utilities
  • /Sources/MemoryKit/ - Multi-level caching
  • /Sources/Substation/ - Substation application

Migration Guides

From Python OpenStack SDK

Python:

from openstack import connection
conn = connection.Connection(auth_url="...", username="...", password="...")
servers = conn.compute.servers()

Swift:

import OSClient
let client = try await OpenStackClient.connect(config: ..., credentials: ...)
let servers = try await client.nova.servers.list()

From NCurses

C (NCurses):

initscr();
printw("Hello, World!");
refresh();
endwin();

Swift (SwiftTUI):

let screen = SwiftTUI.initializeScreen()
defer { SwiftTUI.cleanup(screen) }
await SwiftTUI.render(Text("Hello, World!"), on: surface, in: bounds)
SwiftTUI.refresh(screen)

Best Practices

1. Use Async/Await

// Good: Using async/await
let servers = try await client.nova.servers.list()

// Avoid: Blocking calls (don't exist in this API)

2. Handle Errors Properly

do {
    let server = try await client.nova.servers.create(...)
} catch OpenStackError.quotaExceeded(let message) {
    // Handle quota error specifically
} catch {
    // Handle other errors
}

3. Use Data Managers for Complex Operations

// Use data manager for detailed info (single call)
let details = try await client.serverDataManager.getDetailed(serverId)

// Instead of multiple calls
// let server = try await client.nova.servers.get(serverId)
// let volumes = try await client.cinder.volumes.list(...)

4. Configure Caching Appropriately

// Configure for your environment
await client.cacheManager.configure(
    maxSize: 100_000_000,  // 100MB
    defaultTTL: 300,       // 5 minutes
    resourceTTLs: [
        .servers: 60,
        .networks: 300,
        .images: 3600
    ]
)

5. Clean Up Resources

// Always use defer for cleanup
let screen = SwiftTUI.initializeScreen()
defer { SwiftTUI.cleanup(screen) }

let timer = createCompatibleTimer(...)
defer { timer.invalidate() }

Note: All APIs are documented with real-world usage examples. See individual pages for detailed documentation and code samples.