​

Highway Service (hway)

​

Overview

• Asynq for reliable job queue management with Redis
• Proto.Actor for actor-based concurrency
• WebAssembly enclaves for secure cryptographic operations
• IPFS integration for decentralized storage

​

Quick Start

​

Prerequisites

• Redis server running on 127.0.0.1:6379
• Go 1.24.4 or later

​

Installation

# Build and install the Highway service
make install

# Or build directly
cd cmd/hway
go build -o hway .

​

Running the Service

# Start the Highway service
./hway

• Concurrency: 10 workers
• Queue Priorities:
  • critical: 6 workers
  • default: 3 workers
  • low: 1 worker

​

Architecture

   Task Queue          Highway Service       Vault Actor
   (Redis)              (Asynq)             (Proto.Actor)




                                                 WASM Enclave
                                                  (Extism)

​

Core Components

1. Task Processing Layer (main.go)
   • Asynq server configuration
   • Task routing and worker management
   • Redis connection handling
2. Actor System (internal/vault/plugin/actor.go)
   • Proto.Actor based concurrency
   • Behavioral state management
   • Lifecycle management for WASM plugins
3. Plugin Interface (internal/vault/plugin/plugin.go)
   • WebAssembly plugin abstraction
   • Secure cryptographic operations
   • Type-safe method calls
4. Task Definitions (internal/vault/tasks/)
   • Task type definitions
   • Payload serialization
   • Task processing logic

​

Supported Operations

​

Key Generation

// Generate a new cryptographic key pair
type GenerateRequest struct {
    ID string `json:"id"`
}

type GenerateResponse struct {
    Data      *mpc.EnclaveData `json:"data"`
    PublicKey []byte           `json:"public_key"`
}

​

Digital Signatures

// Sign a message
type SignRequest struct {
    Message []byte           `json:"message"`
    Enclave *mpc.EnclaveData `json:"enclave"`
}

type SignResponse struct {
    Signature []byte `json:"signature"`
}

​

Signature Verification

// Verify a signature
type VerifyRequest struct {
    PublicKey []byte `json:"public_key"`
    Message   []byte `json:"message"`
    Signature []byte `json:"signature"`
}

type VerifyResponse struct {
    Valid bool `json:"valid"`
}

​

Vault Management

​

Export to IPFS

type ExportRequest struct {
    Enclave  *mpc.EnclaveData `json:"enclave,omitempty"`
    Password []byte           `json:"password,omitempty"`
}

type ExportResponse struct {
    CID     string `json:"cid,omitempty"`
    Success bool   `json:"success"`
}

​

Import from IPFS

type ImportRequest struct {
    CID      string `json:"cid,omitempty"`
    Password []byte `json:"password,omitempty"`
}

type ImportResponse struct {
    Enclave *mpc.EnclaveData `json:"enclave,omitempty"`
    Success bool             `json:"success"`
}

​

Vault Refresh

type RefreshRequest struct {
    Enclave *mpc.EnclaveData `json:"enclave,omitempty"`
}

type RefreshResponse struct {
    Okay bool             `json:"okay"`
    Data *mpc.EnclaveData `json:"data,omitempty"`
}

​

Task Management

​

Creating Tasks

import "github.com/sonr-io/sonr/internal/vault/tasks"

// Create a vault generation task
task, err := tasks.NewVaultGenerateTask(userID)
if err != nil {
    return err
}

// Enqueue the task
client := asynq.NewClient(asynq.RedisClientOpt{Addr: "127.0.0.1:6379"})
info, err := client.Enqueue(task)

​

Task Types

• vault:generate - Generate new cryptographic key pairs

1. Defining the task type constant in internal/vault/tasks/types.go
2. Creating appropriate payload and response structures
3. Implementing the task processor
4. Registering the handler in main.go

​

Configuration

​

Redis Configuration

const redisAddr = "127.0.0.1:6379"

​

Worker Configuration

asynq.Config{
    Concurrency: 10,
    Queues: map[string]int{
        "critical": 6,  // High priority tasks
        "default":  3,  // Normal priority tasks
        "low":      1,  // Low priority tasks
    },
}

​

Actor System Configuration

const KRequestTimeout = 20 * time.Second

​

Security Model

1. WebAssembly Isolation: All cryptographic operations run in WASM enclaves
2. Actor Encapsulation: Each vault actor maintains isolated state
3. Encrypted Storage: Vault data is encrypted before IPFS storage
4. Password Protection: Additional password layer for import/export operations
5. Request Validation: All requests undergo validation before processing

​

Development

​

Adding New Task Types

1. Define the task type:
   Copy

   // In internal/vault/tasks/types.go
   const TypeNewOperation = "vault:new_operation"
   

2. Create payload structures:
   Copy

   type NewOperationPayload struct {
       Field1 string `json:"field1"`
       Field2 int    `json:"field2"`
   }
   
   func NewNewOperationTask(field1 string, field2 int) (*asynq.Task, error) {
       payload, err := json.Marshal(NewOperationPayload{
           Field1: field1,
           Field2: field2,
       })
       if err != nil {
           return nil, err
       }
       return asynq.NewTask(TypeNewOperation, payload), nil
   }
   

3. Implement the processor:
   Copy

   func (processor *VaultProcessor) ProcessNewOperation(ctx context.Context, t *asynq.Task) error {
       var p NewOperationPayload
       if err := json.Unmarshal(t.Payload(), &p); err != nil {
           return fmt.Errorf("json.Unmarshal failed: %v: %w", err, asynq.SkipRetry)
       }
   
       // Process the task
       // ...
   
       return nil
   }
   

4. Register the handler:
   Copy

   // In main.go
   mux.Handle(tasks.TypeNewOperation, tasks.NewVaultProcessor())
   

​

Testing

• Task processing logic
• Actor system behavior
• WASM plugin integration
• Redis queue operations

make test-vaults

​

Monitoring and Observability

• Task processing events
• Actor lifecycle management
• Plugin operation results
• Error conditions and recovery

​

Performance Considerations

• Concurrency: Adjust worker count based on CPU cores and workload
• Queue Priorities: Balance task priorities according to business requirements
• Redis Memory Usage: Monitor Redis memory consumption with large task volumes
• WASM Performance: Plugin operations are CPU-intensive; size workers accordingly

​

Troubleshooting

​

Common Issues

could not run server: dial tcp 127.0.0.1:6379: connect: connection refused

• Ensure Redis server is running on the configured address
• Check Redis configuration and network connectivity

failed to create enclave host: plugin load error

• Verify WASM plugin file exists and is accessible
• Check plugin manifest configuration
• Review Extism runtime requirements

Enclave actor failed to start

• Review plugin loading prerequisites
• Check system memory and resource availability
• Verify Proto.Actor system configuration