Memory Appliance API Documentation

Version: 0.0.0

Welcome to the Memory Appliance API documentation!

The Memory Appliance 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

🌐 Redfish API

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

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

Quick Start

Choose your preferred API and explore the interactive documentation!

API Overview

The Memory Appliance 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[Memory Appliance 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 the Memory Appliance
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 Memory Appliance 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 Model Reference

This section provides detailed documentation for the Protocol Buffer messages used in the gRPC API.

Sub-pages

• Message Headers - MessageHeader and ApplianceMessageHeader definitions
• Chassis Messages - Chassis and SetChassisProperties messages
• Enums - All enumeration types used in the API

Message Headers

This page documents the message headers used for client-server communication.

MessageHeader

Used for requests from the client to the server. The sequence number tracks the number of messages sent on this connection since it was established.

MessageHeader

Message header definition

Fields:

ApplianceMessageHeader

Used for responses from the server to the client. The sequence number tracks the number of messages sent since midnight UTC.

ApplianceMessageHeader

Message header definition

Fields:

Chassis Messages

This page documents the Chassis-related Protocol Buffer messages.

Chassis

Fields:

SetChassisProperties

Fields:

Enumerations

This page documents all enumeration types used in the gRPC API.

Health (enum)

Values:

State (enum)

Values:

Status (enum)

Values:

IdentifyLEDState (enum)

Values:

PowerState (enum)

Values:

PowerSupplyType (enum)

Values:

PhaseWiringType (enum)

Values:

NominalVoltageType (enum)

Values:

PlugType (enum)

Values:

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 Models

This section provides detailed documentation for the Redfish JSON schema models used in the API.

Contents

• AccountsService - Account service management
• Certificate - Certificate management
• Chassis - Physical chassis information
• ComputerSystem - Computer system representation
• Connection - Connection management
• CXLLogicalDevice - CXL logical device
• Endpoint - Endpoint management
• EthernetInterface - Ethernet interface configuration
• Event - Event service
• FabricAdapter - Fabric adapter information
• Fan - Fan monitoring
• Manager - Management controller
• ManagerAccount - Manager account
• Memory - Memory module information
• MemoryChunks - Memory chunk management
• MemoryDomain - Memory domain configuration
• OutboundConnection - Outbound connection management
• PCIeDevice - PCIe device information
• Port - Port management
• PowerSubsystem - Power subsystem monitoring
• PowerSupply - Power supply information
• Processor - Processor information
• Sensor - Sensor monitoring
• ServiceRoot - Redfish service root
• Session - Session management
• Task - Task management
• TaskService - Task service
• TelemetryService - Telemetry service
• ThermalSubsystem - Thermal subsystem monitoring
• UpdateService - Firmware update service

AccountsService

Description

This resource shall represent an account service for a Redfish implementation. The properties are common to, and enable management of, all user accounts. The properties include the password requirements and control features, such as account lockout. Properties and actions in this service specify general behavior that should be followed for typical accounts, however implementations may override these behaviors for special accounts or situations to avoid denial of service or other deadlock situations.

Fields

Certificate

Description

This resource shall represent a certificate for a Redfish implementation.

Fields

Chassis

Description

This resource shall represent a chassis or other physical enclosure for a Redfish implementation. It also represent a location, such as a slot, socket, or bay, where a unit may be installed.

Fields

ComputerSystem

Description

This resource shall represent a computer system in the Redfish Specification. A computer system represents a machine (physical or virtual) and the local resources, such as memory, CPU, and other devices that can be accessed from that machine.

Fields

Connection

Description

This resource shall represent information about a connection in the Redfish Specification.

Fields

CXLLogicalDevice

Description

This resource shall represent a CXL logical device that is a part of a PCIe device.

Fields

Endpoint

Description

This resource contains a fabric endpoint for a Redfish implementation.

Fields

EthernetInterface

Description

This resource contains NIC resources as part of the Redfish Specification.

Fields

Event

Description

This resource contains an event for a Redfish implementation.

Fields

FabricAdapter

Description

This resource shall represent a physical fabric adapter capable of connecting to an interconnect fabric.

Fields

Fan

Description

This resource shall represent a cooling fan for a Redfish implementation. It may also represent a location, such as a slot, socket, or bay, where a unit may be installed, but the State property within the Status property contains Absent.

Fields

Manager

Description

This resource shall represent a management subsystem for a Redfish implementation.

Fields

ManagerAccount

Description

This resource shall represent a user account for the manager in a Redfish implementation. The account shall indicate the allowed access to one of more services in the manager.

Fields

Memory

Description

This resource shall represent a memory device in a Redfish implementation. It may also represent a location, such as a slot, socket, or bay, where a unit may be installed, but the State property within the Status property contains Absent.

Fields

MemoryChunks

Description

This resource shall represent memory chunks and interleave sets in a Redfish implementation.

Fields

MemoryDomain

Description

This resource shall represent memory domains in a Redfish implementation.

Fields

OutboundConnection

Description

This resource shall represent the connection configuration necessary to connect to a remote client. Services shall initiate the outbound connection over a WebSocket defined in the ‘Outbound connections’ clause of the Redfish Specification.

Fields

PCIeDevice

Description

This resource shall represent a PCIe device in a Redfish implementation. It may also represent a location, such as a slot, socket, or bay, where a unit may be installed, but the State property within the Status property contains Absent.

Fields

Port

Description

This resource contains a simple port for a Redfish implementation.

Fields

PowerSubsystem

Description

This resource shall represent a power subsystem for a Redfish implementation.

Fields

PowerSupply

Description

This resource shall represent a power supply unit for a Redfish implementation. It may also represent a location, such as a slot, socket, or bay, where a unit may be installed, but the State property within the Status property contains Absent.

Fields

Processor

Description

This resource shall represent a single processor that a system contains. A processor includes both performance characteristics, clock speed, architecture, core count, and so on, and compatibility, such as the CPU ID instruction results. It may also represent a location, such as a slot, socket, or bay, where a unit may be installed, but the State property within the Status property contains Absent.

Fields

Sensor

Description

This resource shall represent a sensor for a Redfish implementation.

Fields

ServiceRoot

Description

This resource shall represent the root of the Redfish service.

Fields

Session

Description

This resource shall represent a session for a Redfish implementation.

Fields

task

Description

This resource contains a task for a Redfish implementation.

Fields

TaskService

Description

This resource contains a task service for a Redfish implementation.

Fields

TelemetryService

Description

This resource contains a telemetry service for a Redfish implementation.

Fields

ThermalSubsystem

Description

This resource shall represent a thermal subsystem for a Redfish implementation.

Fields

UpdateService

Description

This resource shall represent an update service and the properties that affect the service itself for a Redfish implementation.

Fields

Redfish Resources

ServiceRoot

Path: /redfish/v1

The entry point for all Redfish operations.

{
  "@odata.type": "#ServiceRoot.v1_0_0.ServiceRoot",
  "Id": "RootService",
  "Name": "Memory Appliance 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

The Memory Appliance 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)

The Memory Appliance 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.

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

Memory Appliance Terms

Memory Appliance: Managed memory device

Chassis: Physical enclosure

OMM: Optical Memory Module

Virtual Pool: Virtualized memory allocation