Portal WebSocket Protocol

The Portal WebSocket Protocol is the communication layer of the DragonFire Semantic Network, enabling semantic routing through geometric pathways. It organizes communication based on intent using a port-based architecture that maps directly to geometric forms.

Core Concepts

Semantic Ports

The Portal WebSocket Protocol uses semantic ports (numbered channels) to route messages based on their intent and purpose. Each port corresponds to a specific geometric form, creating natural mathematical pathways for different types of operations:

• 000-099 (Point/0D): System operations
• 100-199 (Line/1D): User interactions and authentication
• 200-299 (Triangle/2D): Data operations and profiles
• 300-399 (Tetrahedron/3D): Financial transactions
• 400-499 (Cube/3D): Storage operations
• 500-599 (Octahedron/3D): Knowledge operations and AI
• 600-699 (Icosahedron/3D): DragonFire core operations
• 700-799 (Dodecahedron/3D): Portal gateway functions

Message Structure

Portal messages follow a consistent structure that includes the semantic port, command, and payload:

{
  "port": 100,       // Semantic port number
  "command": "LOGIN", // Command to execute
  "payload": {       // Data associated with command
    "token": "auth_token_value"
  }
}

Implementation

The following example demonstrates how to initialize a Portal WebSocket connection and handle messages based on semantic ports:

// Initialize a Portal connection (client-side)
const initPortalConnection = async (endpoint, authToken) => {
  // Establish WebSocket connection
  const ws = new WebSocket(`wss://${endpoint}/dragonfire`);
  
  // Set up message handling
  ws.onopen = async () => {
    console.log("Portal connection established");
    
    // Immediately send authentication on port 100 (Auth)
    const authMessage = {
      port: 100,  // Semantic authentication port
      command: "LOGIN",
      payload: { token: authToken }
    };
    
    await sendPortalMessage(ws, authMessage);
  };
  
  // Message handler with semantic port routing
  ws.onmessage = (event) => {
    const message = JSON.parse(event.data);
    const { port, command, payload } = message;
    
    // Route message to appropriate handler based on semantic port
    switch(port) {
      case 100: // Auth port
        handleAuthMessages(command, payload);
        break;
      case 210: // Personal profile data
        handleProfileData(command, payload);
        break;
      case 300: // Purchase channel
        handlePurchaseMessages(command, payload);
        break;
      // Other semantic ports...
    }
  };
  
  return ws;
};

// Send a message on the Portal 
const sendPortalMessage = async (ws, message) => {
  return new Promise((resolve) => {
    ws.send(JSON.stringify(message));
    resolve();
  });
};

Working with Semantic Ports

Authentication (Port 100)

The authentication port (100) represents a Line (1D) geometric form, symbolizing the connection between the user and the system. This is typically the first port you'll interact with:

// Client-side authentication example
const loginUser = async (portalConnection, username, password) => {
  try {
    // Send login command on authentication port
    const response = await portalConnection.sendMessage({
      port: 100,
      command: "LOGIN",
      payload: {
        user: username,
        pass: password
      }
    });
    
    if (response.status === "OK") {
      // Store token for future requests
      localStorage.setItem("dragonfire_token", response.value);
      return true;
    } else {
      console.error("Login failed:", response.message);
      return false;
    }
  } catch (error) {
    console.error("Authentication error:", error);
    return false;
  }
};

Profile Data (Port 210)

The profile data port (210) represents a Triangle (2D) geometric form, reflecting the stable structure needed for personal data storage and retrieval:

// Subscribe to profile updates
dragonfire.subscribe(210, (profileData) => {
  console.log("Profile updated:", profileData);
  updateUserInterface(profileData);
});

// Request profile data
await portalConnection.sendMessage({
  port: 210,
  command: "GET",
  payload: {
    sections: ["basic", "preferences", "history"]
  }
});

Purchases (Port 300)

The purchase port (300) represents a Tetrahedron (3D) geometric form, providing the stable foundation needed for financial transactions:

// Make a purchase
const response = await portalConnection.sendMessage({
  port: 300,
  command: "BUY",
  payload: {
    item: productId,
    quantity: quantity,
    payment: "cardTokenXYZ",
    shipAddress: "addrTokenABC"
  }
});

Best Practices

Port Selection

When implementing a Portal WebSocket integration, choose ports based on operation intent to align with the geometric nature of the operation:

• Use point-based ports (000-099) for system-level operations
• Use line-based ports (100-199) for user connections and authentication
• Use triangle-based ports (200-299) for stable data operations
• Use tetrahedron-based ports (300-399) for financial exchanges
• Use appropriate 3D form ports (400-799) for complex operations

Error Handling

Implement robust error handling to manage connection issues, message parsing errors, and application-specific errors:

// Error handling example
ws.onerror = (error) => {
  console.error("WebSocket error:", error);
  initiateReconnection();
};

ws.onclose = (event) => {
  console.log(`Connection closed. Code: ${event.code}, Reason: ${event.reason}`);
  
  if (event.code !== 1000) { // Normal closure
    initiateReconnection();
  }
};

// Helper to handle reconnection
const initiateReconnection = () => {
  // Implement exponential backoff strategy
  const backoffTime = calculateBackoff(attemptCount);
  setTimeout(() => {
    console.log(`Attempting reconnection (${attemptCount})...`);
    initPortalConnection(endpoint, authToken);
  }, backoffTime);
};