Code Reference

This section provides detailed documentation for the NuNet Device Management Service codebase.

Project Structure

device-management-service/
├── actor/                 # Actor system implementation
├── api/                   # REST API handlers
├── client/                # Client libraries and SDKs
├── cmd/                   # Command-line interfaces
├── dms/                   # Core DMS components
├── executor/              # Job execution engines
├── network/               # Network layer implementation
├── storage/               # Storage management
├── types/                 # Type definitions
└── utils/                 # Utility functions

Core Components

Actor System (actor/)

The actor system provides a concurrent, message-passing architecture for the DMS.

Key Files:

• actor.go: Core actor implementation
• registry.go: Actor registry and management
• dispatch.go: Message dispatching
• security.go: Security and authentication

Example Usage:

// Create a new actor
actor := actor.NewActor("my-actor", handler)

// Register with the registry
registry.Register(actor)

// Send a message
registry.Send("my-actor", &MyMessage{Data: "hello"})

API Layer (api/)

REST API handlers for external communication.

Key Files:

• api.go: Main API server
• actor.go: Actor-related endpoints
• docs/: API documentation

Endpoints:

// Device management
GET    /api/v1/device/status
PUT    /api/v1/device/config

// Job management
POST   /api/v1/jobs
GET    /api/v1/jobs/{id}
DELETE /api/v1/jobs/{id}

// Resource management
GET    /api/v1/resources/usage
POST   /api/v1/allocations

Device Management Service (dms/)

Core DMS functionality including job orchestration and resource management.

Key Components:

• orchestrator/: Job orchestration logic
• jobs/: Job management and execution
• resources/: Resource allocation and monitoring
• node/: Node management and discovery

Job Lifecycle:

// Job states
const (
    JobStatePending   = "pending"
    JobStateRunning   = "running"
    JobStateCompleted = "completed"
    JobStateFailed    = "failed"
)

// Job management
type JobManager struct {
    jobs      map[string]*Job
    scheduler *Scheduler
    executor  *Executor
}

Executor (executor/)

Job execution engines for different runtime environments.

Supported Executors:

• Docker: Container-based execution
• Null: Testing executor
• Custom: Pluggable executor interface

Docker Executor Example:

type DockerExecutor struct {
    client *docker.Client
    config *DockerConfig
}

func (e *DockerExecutor) Execute(job *Job) error {
    // Pull image
    err := e.client.ImagePull(job.Image)
    if err != nil {
        return err
    }
    
    // Create container
    container, err := e.client.ContainerCreate(job.Spec)
    if err != nil {
        return err
    }
    
    // Start container
    return e.client.ContainerStart(container.ID)
}

Network Layer (network/)

Peer-to-peer networking and communication.

Key Components:

• libp2p/: LibP2P integration
• vnet.go: Virtual network management
• utils/: Network utilities

Network Configuration:

type NetworkConfig struct {
    ListenAddresses []string
    BootstrapPeers  []string
    ProtocolID      string
    EnableMDNS      bool
}

Type Definitions (types/)

Core data structures and interfaces.

Job Types

type Job struct {
    ID          string            `json:"id"`
    Name        string            `json:"name"`
    Image       string            `json:"image"`
    Command     []string          `json:"command"`
    Resources   ResourceSpec      `json:"resources"`
    Environment map[string]string `json:"environment"`
    Status      JobStatus         `json:"status"`
    CreatedAt   time.Time         `json:"created_at"`
    UpdatedAt   time.Time         `json:"updated_at"`
}

type ResourceSpec struct {
    CPU    CPUSpec    `json:"cpu"`
    Memory MemorySpec `json:"memory"`
    Storage StorageSpec `json:"storage"`
    GPU    GPUSpec    `json:"gpu,omitempty"`
}

Device Types

type Device struct {
    ID          string            `json:"id"`
    Name        string            `json:"name"`
    Status      DeviceStatus      `json:"status"`
    Resources   ResourceCapacity  `json:"resources"`
    Location    Location          `json:"location"`
    LastSeen    time.Time         `json:"last_seen"`
}

type ResourceCapacity struct {
    CPU    CPUCapacity    `json:"cpu"`
    Memory MemoryCapacity `json:"memory"`
    Storage StorageCapacity `json:"storage"`
    GPU    GPUCapacity    `json:"gpu,omitempty"`
}

Configuration

Configuration Structure

type Config struct {
    Server   ServerConfig   `yaml:"server"`
    Database DatabaseConfig `yaml:"database"`
    Network  NetworkConfig `yaml:"network"`
    Storage  StorageConfig `yaml:"storage"`
    Security SecurityConfig `yaml:"security"`
}

type ServerConfig struct {
    Host string `yaml:"host"`
    Port int    `yaml:"port"`
    TLS  TLSConfig `yaml:"tls"`
}

Environment Variables

# Server configuration
DMS_HOST=0.0.0.0
DMS_PORT=8080
DMS_TLS_ENABLED=true
DMS_TLS_CERT_FILE=/path/to/cert.pem
DMS_TLS_KEY_FILE=/path/to/key.pem

# Database configuration
DMS_DB_TYPE=clover
DMS_DB_PATH=/var/lib/dms/database

# Network configuration
DMS_NETWORK_LISTEN_ADDRESSES=/ip4/0.0.0.0/tcp/4001
DMS_NETWORK_BOOTSTRAP_PEERS=/ip4/1.2.3.4/tcp/4001/p2p/QmPeerID

# Security configuration
DMS_JWT_SECRET=your-secret-key
DMS_API_KEY_ENABLED=true

Command Line Interface (cmd/)

Main Commands

# Device management
nunet-dms init                    # Initialize device
nunet-dms start                   # Start DMS service
nunet-dms stop                    # Stop DMS service
nunet-dms status                  # Show device status

# Job management
nunet-dms jobs list              # List jobs
nunet-dms jobs submit <spec>     # Submit job
nunet-dms jobs status <id>       # Show job status
nunet-dms jobs logs <id>         # Show job logs

# Resource management
nunet-dms resources show         # Show resource usage
nunet-dms allocations list      # List allocations
nunet-dms allocations create    # Create allocation

# Configuration
nunet-dms config get <key>       # Get config value
nunet-dms config set <key> <val> # Set config value
nunet-dms config list            # List all config

Command Structure

type RootCmd struct {
    cmd *cobra.Command
}

func NewRootCmd() *RootCmd {
    cmd := &cobra.Command{
        Use:   "nunet-dms",
        Short: "NuNet Device Management Service",
        Long:  "A decentralized compute platform for everyone, everywhere",
    }
    
    cmd.AddCommand(NewStartCmd())
    cmd.AddCommand(NewJobCmd())
    cmd.AddCommand(NewResourceCmd())
    cmd.AddCommand(NewConfigCmd())
    
    return &RootCmd{cmd: cmd}
}

Testing

Unit Tests

# Run all tests
go test ./...

# Run tests with coverage
go test -cover ./...

# Run specific package tests
go test ./actor/...

Integration Tests

# Run integration tests
go test -tags=integration ./tests/integration/...

# Run E2E tests
go test -tags=e2e ./tests/e2e/...

Test Structure

func TestJobExecution(t *testing.T) {
    // Setup
    executor := NewDockerExecutor()
    job := &Job{
        Image: "nginx:latest",
        Resources: ResourceSpec{
            CPU: CPUSpec{Cores: 1},
            Memory: MemorySpec{GB: 1},
        },
    }
    
    // Execute
    err := executor.Execute(job)
    
    // Assert
    assert.NoError(t, err)
    assert.Equal(t, JobStateRunning, job.Status)
}

Performance Considerations

Resource Management

• Use connection pooling for database connections
• Implement proper resource cleanup
• Monitor memory usage and garbage collection

Concurrency

• Use worker pools for job execution
• Implement proper synchronization
• Avoid blocking operations in hot paths

Caching

• Cache frequently accessed data
• Use appropriate cache eviction policies
• Monitor cache hit rates

Security

Authentication

• JWT token validation
• API key authentication
• Role-based access control

Authorization

• Resource-level permissions
• Job execution limits
• Network access controls

Data Protection

• Encrypt sensitive data at rest
• Use TLS for network communication
• Implement proper input validation

Monitoring and Observability

Metrics

• Job execution metrics
• Resource utilization
• Network performance
• Error rates

Logging

• Structured logging with JSON format
• Configurable log levels
• Request tracing

Health Checks

• Service health endpoints
• Dependency health checks
• Resource availability monitoring

Contributing

Code Style

• Follow Go conventions
• Use gofmt for formatting
• Write comprehensive tests

Documentation

• Document all public APIs
• Include usage examples
• Keep documentation up to date

Pull Requests

• Include tests for new features
• Update documentation
• Follow the contribution guidelines

Next Steps

• API Overview
• Getting Started
• Tutorials