SmartForge API Documentation

Welcome to the SmartForge Memory Appliance API documentation!

SmartForge provides two complementary APIs for managing memory appliances:

🚀 gRPC API

High-performance bidirectional streaming API using Protocol Buffers.

• Port: 50051
• Protocol: gRPC
• Features: Real-time streaming, efficient binary protocol

Learn more →

🌐 Redfish API

Industry-standard RESTful API implementing DMTF Redfish v1.19.0.

• Port: 8080
• Protocol: HTTP/REST
• Features: Standard compliance, wide tool support

Learn more →

Quick Start

Choose your preferred API and explore the interactive documentation!

API Overview

SmartForge provides comprehensive management capabilities through two complementary APIs.

Architecture

Both APIs operate concurrently and share the same underlying data model, ensuring consistency across protocols.

graph TB
    Client1[gRPC Client] -->|Port 50051| GrpcServer[gRPC Server]
    Client2[Redfish Client] -->|Port 8080| RedfishServer[Redfish Server]
    GrpcServer --> Model[Shared Data Model]
    RedfishServer --> Model
    Model --> Chassis[Chassis Management]
    Model --> Memory[Memory Management]
    Model --> Tasks[Task Management]

When to Use Each API

Use gRPC When:

• You need real-time bidirectional streaming
• Performance is critical
• You’re building custom applications
• You want efficient binary protocol

Use Redfish When:

• You need industry-standard compliance
• You’re using existing Redfish tools
• You prefer REST/HTTP
• You need broad ecosystem support

Architecture

System Components

graph LR
    A[Clients] --> B[SmartForge Service]
    B --> C[gRPC Interface]
    B --> D[Redfish Interface]
    C --> E[Business Logic]
    D --> E
    E --> F[Data Store]
    E --> G[Hardware]

Data Flow

gRPC Bidirectional Streaming

sequenceDiagram
    participant Client
    participant Server
    Client->>Server: Connect (SendCommand stream)
    Server->>Client: Connected
    Client->>Server: GetTasks command
    Server->>Client: TaskCollection response
    Client->>Server: Heartbeat
    Server->>Client: Heartbeat ack
    Note over Client,Server: Stream remains open for real-time updates

Redfish REST Operations

sequenceDiagram
    participant Client
    participant Redfish API
    participant Model
    Client->>Redfish API: GET /redfish/v1/Systems/1
    Redfish API->>Model: Query system
    Model-->>Redfish API: System data
    Redfish API-->>Client: 200 OK (JSON)

Getting Started

Installation

# Build SmartForge
cargo build --release

# Run the server
cargo run --bin smartforge

# Run the gRPC client
cargo run --bin grpc_client

Testing the APIs

gRPC Quick Test

# Using the included client
cargo run --bin grpc_client

# Using grpcurl
grpcurl -plaintext localhost:50051 list

Redfish Quick Test

# Get service root
curl http://localhost:8080/redfish/v1/

# Get systems collection
curl http://localhost:8080/redfish/v1/Systems

Next Steps

• Explore gRPC API Documentation
• Explore Redfish API Documentation
• Configure TLS
• Set up Authentication

gRPC API

The SmartForge gRPC API provides high-performance bidirectional streaming for real-time memory appliance management.

Features

• Bidirectional Streaming: Send commands and receive responses in real-time
• Protocol Buffers: Efficient binary protocol
• Type Safety: Strongly typed messages
• Code Generation: Client libraries for multiple languages

Service Overview

service MemoryApplianceService {
  rpc SendCommand (stream SendCommandRequest) returns (stream CommandResponse);
  rpc GetChassis (google.protobuf.Empty) returns (Chassis);
}

Quick Example

use smartforge::generated::memory_appliance::*;

#[tokio::main]
async fn main() -> Result<(), Box<dyn std::error::Error>> {
    // Connect to server
    let mut client = MemoryApplianceServiceClient::connect(
        "http://127.0.0.1:50051"
    ).await?;
    
    // Get chassis info
    let chassis = client.get_chassis(()).await?;
    println!("Chassis: {:?}", chassis);
    
    Ok(())
}

See the full API reference for complete details.

gRPC API Reference

Package: memory_appliance

Services

MemoryApplianceService

Service definition for the Memory Appliance.

RPCs

SendCommand

Request: SendCommandRequest (streamed)

Response: CommandResponse (streamed)

GetChassis

Request: (google.protobuf.Empty

Response: (Chassis

Message Types

SendCommandRequest

API to send a command to the memory appliance

Fields:

• header (optional MessageHeader)
• connect (ConnectStream)
• heartbeat (KeepAliveHeartbeat)
• reset_intrusion_sensor (ResetIntrusionSensorRequest)
• set_chassis_properties (SetChassisProperties)
• identify_chassis (IdentifyChassis)
• decommission_host (DecommissionHost)
• set_host_properties (SetComputerSystemProperties)
• get_tasks (GetTasks)
• clear_telemetry_metrics (ClearMetricReports)
• clear_telemetry_data (ClearTelemetryData)
• collect_telemetry_data (CollectTelemetryData)
• submit_metric_report (SubmitTestMetricReport)
• identify_omm (IdentifyOMM)
• restart_omm (RestartOMM)
• take_omm_offline (OfflineOMM)
• initialize_omm (InitializeOMM)
• set_virtual_pool_properties (SetVirtualPoolProperties)
• get_capacity_hints (GetCapacityHints)
• destroy_virtual_pool (DestroyVirtualPool)
• change_virtual_pool_capacity_or_bandwidth (ChangeVirtualPoolCapacityOrBandwidth)
• create_virtual_pool (CreateVirtualPool)
• get_memory_region_list (GetMemoryRegionList)
• create_maximum_capacity_virtual_pool (CreateMaximumCapacityVirtualPool)
• set_port_properties (SetPortProperties)
• enable_lane (EnableLane)
• disable_lane (DisableLane)
• train_lane (TrainLane)
• set_connection_properties (SetConnectionProperties)
• identify_memory (IdentifyMemory)
• enable_or_disable_memory (EnableOrDisableMemory)
• configure_photonic_adapter (ConfigurePhotonicAdapter)
• identify_photonic_adapter (IdentifyPhotonicAdapter)
• identify_fan (IdentifyFan)
• reset_sensor_metrics (ResetSensorMetrics)
• reset_power_supply (ResetPowerSupply)
• identify_power_supply (IdentifyPowerSupply)
• reset_manager_ethernet (ResetManagerEthernet)
• reset_manager_ethernet_to_factory_defaults (ResetManagerEthernetToFactoryDefaults)

ConnectStream

Fields:

• empty_payload (google.protobuf.Empty)

CommandResponse

The main response message for the SendCommand bidirectional stream.

Fields:

• message_header (optional ApplianceMessageHeader)
• heartbeat (KeepAliveHeartbeat)
• success (SendCommandSuccess)
• failure (SendCommandFailure)
• task_update (Task)
• tasks (TaskCollection)

SendCommandSuccess

Represents a successful outcome of a SendCommand operation.

Fields:

• update (ApplianceState)
• chassis_update (Chassis)
• software_update_progress (SimpleUpdateProgress)
• new_ssh_key (NewSSHIdentityPublicKey)
• omm_update (OpticalMemoryModule)
• virtual_pool_update (VirtualPool)
• memory_region_update (MemoryRegion)
• port_update (Port)
• photonic_lanes_update (PhotonicLanes)
• connection_update (Connection)
• memory (Memory)
• photonic_adapter (PhotonicAdapter)
• fan (Fan)
• sensor (Sensor)
• power_supply (PowerSupply)
• ethernet_interface (EthernetInterface)

TaskCollection

Fields:

• task (repeated Task)

SendCommandFailure

Represents a failed outcome of a SendCommand operation.

Fields:

• reason (FailureReason)
• error_code (uint32)

Example Usage

#![allow(unused)]
fn main() {
use smartforge::generated::memory_appliance::*;

let mut client = MemoryApplianceServiceClient::connect("http://127.0.0.1:50051").await?;
}

For complete examples, see the grpc_client binary in src/bin/grpc_client.rs.

gRPC Examples

Establishing a Connection

#![allow(unused)]
fn main() {
use smartforge::generated::memory_appliance::*;

let mut client = MemoryApplianceServiceClient::connect(
    "http://127.0.0.1:50051"
).await?;
}

Getting Chassis Information

#![allow(unused)]
fn main() {
let chassis = client.get_chassis(()).await?;
println!("Serial: {:?}", chassis.serial_number);
println!("Model: {:?}", chassis.model);
}

Bidirectional Streaming

#![allow(unused)]
fn main() {
let (tx, rx) = tokio::sync::mpsc::channel(32);
let stream = tokio_stream::wrappers::ReceiverStream::new(rx);
let response = client.send_command(stream).await?;
let mut inbound = response.into_inner();

// Send a command
tx.send(SendCommandRequest {
    header: Some(MessageHeader {
        sequence_number: Some(1),
        correlation_id: Some("req-1".to_string()),
        sent_timestamp: Some(100),
        sender: Some("client".to_string()),
    }),
    command_type: Some(send_command_request::CommandType::GetTasks(
        GetTasks { empty_payload: None }
    )),
}).await?;

// Receive responses
while let Some(response) = inbound.message().await? {
    println!("Response: {:?}", response);
}
}

Error Handling

#![allow(unused)]
fn main() {
match client.get_chassis(()).await {
    Ok(chassis) => println!("Success: {:?}", chassis),
    Err(e) => eprintln!("Error: {}", e),
}
}

gRPC Sequence Diagrams

Connection Establishment

sequenceDiagram
    participant C as Client
    participant S as Server
    C->>S: Connect to :50051
    S-->>C: Connection established
    C->>S: GetChassis()
    S-->>C: Chassis data
    Note over C,S: Connection ready for streaming

Bidirectional Streaming Flow

sequenceDiagram
    participant C as Client
    participant S as Server
    C->>S: Open SendCommand stream
    S-->>C: Stream ready
    C->>S: SendCommandRequest (Connect)
    S-->>C: CommandResponse (Success)
    C->>S: SendCommandRequest (GetTasks)
    S-->>C: CommandResponse (TaskCollection)
    C->>S: SendCommandRequest (Heartbeat)
    S-->>C: CommandResponse (Heartbeat)
    Note over C,S: Stream remains open
    C->>S: Close stream
    S-->>C: Stream closed

Command Processing

flowchart TD
    A[Client Sends Command] --> B{Validate Request}
    B -->|Valid| C[Process Command]
    B -->|Invalid| D[Return Failure]
    C --> E{Command Type}
    E -->|GetTasks| F[Retrieve Tasks]
    E -->|SetProperties| G[Update Properties]
    E -->|Heartbeat| H[Acknowledge]
    F --> I[Return Success]
    G --> I
    H --> I
    I --> J[Send Response to Client]
    D --> J

Error Handling Flow

flowchart TD
    A[Receive Command] --> B{Authentication}
    B -->|Fail| C[Return PERMISSION_DENIED]
    B -->|Pass| D{Parse Command}
    D -->|Fail| E[Return INVALID_REQUEST]
    D -->|Pass| F{Execute}
    F -->|Error| G[Return INTERNAL_ERROR]
    F -->|Timeout| H[Return TIMEOUT]
    F -->|Success| I[Return SUCCESS]

Redfish API

SmartForge implements the DMTF Redfish specification v1.19.0 for industry-standard RESTful manageability.

Features

• DMTF Standard: Full Redfish compliance
• RESTful: Standard HTTP methods
• JSON: Human-readable responses
• Tool Support: Works with existing Redfish tools

Base URL

http://localhost:8080/redfish/v1

Quick Example

# Get service root
curl http://localhost:8080/redfish/v1/

# Get system information
curl http://localhost:8080/redfish/v1/Systems/1

# Power on system
curl -X POST http://localhost:8080/redfish/v1/Systems/1/Actions/ComputerSystem.Reset \
  -H "Content-Type: application/json" \
  -d '{"ResetType": "On"}'

See the full API reference for complete details.

Redfish API Reference

Overview

SmartForge implements the DMTF Redfish specification v1.19.0 for industry-standard RESTful manageability.

Base URL

http://localhost:8080/redfish/v1

Interactive API Documentation

Available Resources

• ServiceRoot: /redfish/v1
• Systems: /redfish/v1/Systems/{id}
• Chassis: /redfish/v1/Chassis/{id}
• Managers: /redfish/v1/Managers/{id}
• Sessions: /redfish/v1/SessionService
• Accounts: /redfish/v1/AccountService
• Tasks: /redfish/v1/TaskService
• Events: /redfish/v1/EventService
• Updates: /redfish/v1/UpdateService

Quick Examples

Get Service Root

curl http://localhost:8080/redfish/v1/

Get System Information

curl http://localhost:8080/redfish/v1/Systems/1

Power On System

curl -X POST http://localhost:8080/redfish/v1/Systems/1/Actions/ComputerSystem.Reset \
  -H "Content-Type: application/json" \
  -d '{"ResetType": "On"}'

Redfish Resources

ServiceRoot

Path: /redfish/v1

The entry point for all Redfish operations.

{
  "@odata.type": "#ServiceRoot.v1_0_0.ServiceRoot",
  "Id": "RootService",
  "Name": "SmartForge Service Root",
  "RedfishVersion": "1.19.0",
  "UUID": "...",
  "Systems": { "@odata.id": "/redfish/v1/Systems" },
  "Chassis": { "@odata.id": "/redfish/v1/Chassis" }
}

Systems

Path: /redfish/v1/Systems/{id}

Computer system resources.

Operations:

• GET - Retrieve system information
• PATCH - Update system properties

Actions:

• ComputerSystem.Reset - Power control

Chassis

Path: /redfish/v1/Chassis/{id}

Physical chassis resources.

Operations:

• GET - Retrieve chassis information
• PATCH - Update chassis properties

Managers

Path: /redfish/v1/Managers/{id}

Management controller resources.

Sessions

Path: /redfish/v1/SessionService

Session management for authentication.

Tasks

Path: /redfish/v1/TaskService

Asynchronous operation tracking.

Redfish Examples

Basic Operations

Get Service Root

curl http://localhost:8080/redfish/v1/

List Systems

curl http://localhost:8080/redfish/v1/Systems

Get System Details

curl http://localhost:8080/redfish/v1/Systems/1

Power Control

Power On

curl -X POST http://localhost:8080/redfish/v1/Systems/1/Actions/ComputerSystem.Reset \
  -H "Content-Type: application/json" \
  -d '{"ResetType": "On"}'

Power Off

curl -X POST http://localhost:8080/redfish/v1/Systems/1/Actions/ComputerSystem.Reset \
  -H "Content-Type: application/json" \
  -d '{"ResetType": "GracefulShutdown"}'

Force Restart

curl -X POST http://localhost:8080/redfish/v1/Systems/1/Actions/ComputerSystem.Reset \
  -H "Content-Type: application/json" \
  -d '{"ResetType": "ForceRestart"}'

PATCH Operations

Update System Name

curl -X PATCH http://localhost:8080/redfish/v1/Systems/1 \
  -H "Content-Type: application/json" \
  -d '{"Name": "My Server"}'

Using Python

import requests

# Get service root
response = requests.get('http://localhost:8080/redfish/v1/')
print(response.json())

# Power on system
response = requests.post(
    'http://localhost:8080/redfish/v1/Systems/1/Actions/ComputerSystem.Reset',
    json={'ResetType': 'On'}
)
print(response.status_code)

Using PowerShell

# Get service root
Invoke-RestMethod -Uri 'http://localhost:8080/redfish/v1/'

# Power on system
$body = @{ ResetType = "On" } | ConvertTo-Json
Invoke-RestMethod -Method Post `
  -Uri 'http://localhost:8080/redfish/v1/Systems/1/Actions/ComputerSystem.Reset' `
  -Body $body `
  -ContentType 'application/json'

TLS Configuration

Enabling TLS

SmartForge supports TLS for both gRPC and Redfish APIs.

Generate Certificates

# Generate development certificates
cargo run --bin gen_certs

# Or use the provided script
./scripts/generate-dev-certs.sh

Configure TLS in config.json

{
  "features": {
    "disable_tls": false
  },
  "tls": {
    "cert_path": "/etc/smartforge/certs/server.crt",
    "key_path": "/etc/smartforge/certs/server.key",
    "ca_cert_path": "/etc/smartforge/certs/ca.crt"
  }
}

Client Configuration

gRPC with TLS

#![allow(unused)]
fn main() {
use tonic::transport::{Channel, ClientTlsConfig};

let tls = ClientTlsConfig::new()
    .ca_certificate(Certificate::from_pem(ca_cert))
    .domain_name("localhost");

let channel = Channel::from_static("https://localhost:50051")
    .tls_config(tls)?
    .connect()
    .await?;
}

Redfish with TLS

curl --cacert certs/ca.crt https://localhost:8080/redfish/v1/

Certificate Management

See CERTS.md for complete certificate management documentation.

Authentication

PAM Authentication (Linux)

SmartForge supports PAM (Pluggable Authentication Modules) for Redfish API authentication on Linux systems.

Configuration

{
  "features": {
    "disable_auth": false
  },
  "auth": {
    "pam_service": "smartforge"
  }
}

PAM Configuration File

Create /etc/pam.d/smartforge:

auth    required    pam_unix.so
account required    pam_unix.so

Using Authentication

# Create session
curl -X POST http://localhost:8080/redfish/v1/SessionService/Sessions \
  -H "Content-Type: application/json" \
  -d '{"UserName": "admin", "Password": "password"}'

# Use session token
curl http://localhost:8080/redfish/v1/Systems \
  -H "X-Auth-Token: your-session-token"

gRPC Authentication

For gRPC, authentication is typically handled at the TLS layer using client certificates or custom metadata.

See PAM_AUTHENTICATION.md for complete authentication documentation.

Customization Guide

mdBook Theme Customization

Custom CSS

Edit docs/theme/custom.css to customize the appearance:

:root {
    --sidebar-bg: #1a1a2e;
    --page-bg: #16213e;
    --fg: #e8e8e8;
    --links: #4fc3f7;
}

Custom JavaScript

Add custom behavior in docs/theme/custom.js.

Adding Mermaid Diagrams

\```mermaid
graph TD
    A[Start] --> B[Process]
    B --> C[End]
\```

Extending the Documentation

1. Add new pages to docs/src/
2. Update SUMMARY.md to include them
3. Rebuild: mdbook build docs

Preprocessors

Installing mdbook-mermaid

cargo install mdbook-mermaid

Installing mdbook-toc

cargo install mdbook-toc

Building Locally

# Install mdbook
cargo install mdbook

# Build documentation
mdbook build docs

# Serve with live reload
mdbook serve docs

Glossary

API Terms

gRPC: Google Remote Procedure Call - High-performance RPC framework

Redfish: DMTF standard for RESTful hardware management

Protocol Buffers: Language-neutral data serialization format

Bidirectional Streaming: Communication pattern where both client and server send messages simultaneously

OpenAPI: Specification for describing REST APIs

Redfish Terms

ServiceRoot: Entry point for the Redfish API

OData: Open Data Protocol used by Redfish

Collection: Group of related resources

Action: Operation that can be performed on a resource

SmartForge Terms

Memory Appliance: Managed memory device

Chassis: Physical enclosure

OMM: Optical Memory Module

Virtual Pool: Virtualized memory allocation

Contributing

Documentation Contributions

We welcome contributions to improve the documentation!

Building the Docs

cargo build  # Automatically generates docs
mdbook serve docs  # View locally

Adding New Pages

1. Create a new .md file in docs/src/
2. Add it to docs/src/SUMMARY.md
3. Include diagrams using Mermaid
4. Test locally before submitting

Style Guide

• Use clear, concise language
• Include code examples
• Add diagrams for complex concepts
• Test all code examples

Submitting Changes

1. Fork the repository
2. Make your changes
3. Test the documentation builds
4. Submit a pull request

Questions?

Contact: eng@penguinsolutions.com