SocketX on AWS

Introduction

SocketX Server is a WebSocket proxy that terminates SocketX/MTE-protected connections from SocketX clients, decodes client payloads inside the proxy, and forwards WebSocket frames to an upstream WebSocket service. The upstream leg is plaintext when the configured upstream uses ws:// and TLS-protected when it uses wss://.

SocketX preserves WebSocket text and binary frame semantics while wrapping payloads in the SocketX/MTE protocol between the client and proxy.

---

Prerequisites

Technical Requirements

• A web or mobile application that communicates with a backend service over WebSockets.
• A backend WebSocket service reachable from the SocketX deployment.
• AWS CLI access for the deployment path you choose.

Skills and Knowledge

• Familiarity with ECS and/or EKS.
• Experience configuring AWS networking, load balancers, and security groups.

---

Deployment Options

SocketX Server is provided as Docker images and can be deployed on AWS ECS, AWS EKS, or another container runtime.

1. Elastic Container Service (ECS)

Requirements

• Git
• AWS CLI
• AWS permissions to launch the required resources

Deployment Steps

1. Clone the CloudFormation template repository: AWS CloudFormation Templates
2. Modify parameters.json with your deployment configuration.
3. From the template directory, run deploy.sh create to deploy or the delete command to remove resources.

Configuration

Required parameters:

• VpcId - AWS VPC ID.
• SubnetIds - Comma-separated subnet IDs. Use at least two subnets.
• DomainMap - JSON object mapping hostnames to upstream WebSocket targets and allowed origins.

Optional parameters include:

• LogLevel - Logging level. Values are trace, debug, info, warn, error, fatal, panic, or disabled. Default is info.

parameters.json

[
  {
    "ParameterKey": "VpcId",
    "ParameterValue": ""
  },
  {
    "ParameterKey": "SubnetIds",
    "ParameterValue": ""
  },
  {
    "ParameterKey": "DomainMap",
    "ParameterValue": "{\"*\":{\"upstream\":\"ws://example.com\",\"allowedOrigins\":[\"*\"]}}"
  },
  {
    "ParameterKey": "LogLevel",
    "ParameterValue": "warn"
  }
]

---

2. Docker Image

Authenticate to the Eclypses AWS ECR registry and pull the image for the Marketplace listing you are using. Replace <version> with the image tag provided by Eclypses or Marketplace release metadata.

bash

aws ecr get-login-password \
  --region us-east-1 \
  | docker login --username AWS \
  --password-stdin 709825985650.dkr.ecr.us-east-1.amazonaws.com

docker pull 709825985650.dkr.ecr.us-east-1.amazonaws.com/eclypses/socketx-server:<version>

PowerShell

aws ecr get-login-password `
  --region us-east-1 `
  | docker login --username AWS `
  --password-stdin 709825985650.dkr.ecr.us-east-1.amazonaws.com

docker pull 709825985650.dkr.ecr.us-east-1.amazonaws.com/eclypses/socketx-server:<version>

Run the container with a valid DOMAIN_MAP:

bash

docker run --rm -it \
  --name socketx \
  -p 8080:8080 \
  -e DOMAIN_MAP='{"*":{"upstream":"ws://example.com","allowedOrigins":["*"]}}' \
  709825985650.dkr.ecr.us-east-1.amazonaws.com/eclypses/socketx-server:<version>

PowerShell

docker run --rm -it `
  --name socketx `
  -p 8080:8080 `
  -e 'DOMAIN_MAP={"*":{"upstream":"ws://example.com","allowedOrigins":["*"]}}' `
  709825985650.dkr.ecr.us-east-1.amazonaws.com/eclypses/socketx-server:<version>

---

Server Configuration

SocketX Server is configured with environment variables.

Required Variables

• DOMAIN_MAP - JSON string mapping hostnames to upstream WebSocket targets and allowed origins.

Interactive Builder

Use the DOMAIN_MAP Builder tool to configure your domain mappings visually and copy a ready-to-use DOMAIN_MAP value.

DOMAIN_MAP Format

{
  "api.example.com": {
    "upstream": "wss://backend.example.com/socket",
    "allowedOrigins": ["https://app.example.com"]
  },
  "*.staging.example.com": {
    "upstream": "ws://staging-backend:8080",
    "allowedOrigins": ["https://*.staging.example.com"]
  },
  "*": {
    "upstream": "ws://default-backend:8080",
    "allowedOrigins": ["*"]
  }
}

Matching order is exact host, subdomain wildcard such as *.example.com, then global wildcard *. The incoming Host header may include a port, so include that port in the key or use a wildcard mapping when required.

allowedOrigins is required in practice. Empty or missing origin lists reject connections. Exact origins include the scheme, for example https://app.example.com. Origin wildcard entries must begin with *., for example https://*.example.com.

Optional Variables

Variable	Default	Description
LISTEN_HOST	0.0.0.0	Address the server binds to.
LISTEN_PORT	8080	Port the server listens on.
LOG_LEVEL	info	trace, debug, info, warn, error, fatal, panic, or disabled.
MTE_COMPANY_NAME	Built in	MTE license company name.
MTE_LICENSE_KEY	Built in	MTE license key.
MTE_KYBER_STRENGTH	512	0, 512, 768, or 1024.
MTE_DECODER_WINDOW_SIZE	1000	MTE decoder re-sequencing window.
WS_READ_BUFFER_SIZE	1024	WebSocket read buffer size in bytes.
WS_WRITE_BUFFER_SIZE	1024	WebSocket write buffer size in bytes.
CLIENT_PONG_TIMEOUT	60	Seconds allowed to receive client pong.
CLIENT_PING_INTERVAL	54	Seconds between proxy-to-client pings.
UPSTREAM_PONG_TIMEOUT	60	Seconds allowed to receive upstream pong.
UPSTREAM_PING_INTERVAL	54	Seconds between proxy-to-upstream pings.
WRITE_TIMEOUT	10	Seconds allowed for WebSocket writes.
USE_CONSOLE_LOGS	false	Set to true for human-readable logs.

AWS Billing Variables

Variable	Description
BILLING_STRATEGY	register_usage, request_based, external_meter, or eclypses_no_billing.
BILLING_PROVIDER	Must be aws for AWS billing.
BILLING_PRODUCT	Must be socketx when billing is enabled.
BILLING_REPORT_INTERVAL	Go duration for request-based windows. Default 15m; only used with request_based.

AWS image variants:

• Standard/register image: BILLING_STRATEGY=register_usage; calls AWS Marketplace RegisterUsage once at startup.
• Request-based image: BILLING_STRATEGY=request_based; reports encoded_messages and decoded_messages via AWS Marketplace MeterUsage.
• External-meter image: BILLING_STRATEGY=external_meter; same startup registration behavior as register_usage, but uses the external-meter product code.

Request-based billing counts successful ProxyData encode/decode operations only. Handshake messages are not counted.

Minimal Example

DOMAIN_MAP={"*":{"upstream":"ws://example.com","allowedOrigins":["*"]}}

Full Example

DOMAIN_MAP={"*":{"upstream":"ws://example.com","allowedOrigins":["*"]}}
LISTEN_HOST=0.0.0.0
LISTEN_PORT=8080
LOG_LEVEL=info
WS_READ_BUFFER_SIZE=2048
WS_WRITE_BUFFER_SIZE=2048
CLIENT_PONG_TIMEOUT=60
CLIENT_PING_INTERVAL=54
UPSTREAM_PONG_TIMEOUT=60
UPSTREAM_PING_INTERVAL=54
WRITE_TIMEOUT=10

---

Client-Side Setup

Eclypses provides client-side SDKs to integrate with SocketX Server:

• JavaScript Package

---

Testing & Health Checks

• Monitor container logs for the startup message: Starting server.
• Test the echo route:

curl http://<SOCKETX_HOST_OR_IP>:<PORT>/api/socketx-echo?msg=test

Expected response:

{
  "message": "test",
  "timestamp": "<RFC3339 timestamp>"
}

---

Monitoring

Amazon Managed Grafana

1. Create a Grafana workspace in AWS.
   • AWS instructions
2. Add CloudWatch as a data source. IAM role authentication is recommended.
   • AWS instructions
3. Import the provided dashboard:
   • SocketX Grafana Dashboard

Dashboard Metrics

• Total connections
• Total MTE operations
• Total bytes processed
• Average WebSocket session duration
• Average encryption duration
• Average decryption duration
• Traffic throughput
• Payload size distribution
• WebSocket message direction
• Session audit logs
• Encryption and decryption event logs

---

Observability

Startup logs include a redacted config object with fields such as listen_addr, log_level, socketx_version, mte_version, mte_kyber_strength, timeout values, buffer sizes, and billing settings.

MTE encryption and decryption event logs include:

• connection_id
• event_type
• duration_ms
• payload_size_bytes
• payload_sha256
• eeid
• host
• origin
• upstream_server

Connection close logs include an audit object with connection timing, message counts, byte counts, total encode/decode time, and WebSocket close information.

payload_sha256 is a hash of plaintext payload bytes at the proxy for correlation and audit workflows. It is not a standalone compliance certification or tamper-evidence guarantee.

---

Troubleshooting

1. Invalid configuration
   • Check logs for missing or invalid environment variables.
   • Verify DOMAIN_MAP is valid JSON and each entry has upstream and allowedOrigins.
2. SocketX unreachable
   • Verify security groups, listener rules, load balancer settings, and container port mappings.
3. Origin rejected
   • Confirm the browser Origin value matches the selected host mapping's allowedOrigins list.
4. Upstream connection fails
   • Confirm the configured upstream URL and client-provided pathname combine into a valid WebSocket URL.

Enable debug logs with LOG_LEVEL=debug.

---

Security Notes

• The server does not persist WebSocket payloads.
• Runtime environment variables may contain license, billing, or deployment configuration values and should be protected accordingly.
• The current Dockerfiles use a distroless runtime image but do not set an explicit non-root USER.
• Use wss:// upstream URLs when the proxy-to-upstream leg must be TLS-protected.

---

Costs

Marketplace charges depend on the selected AWS listing and plan. AWS infrastructure costs, such as ECS/EKS, CloudWatch, VPC networking, and load balancers, also apply.

AWS Service	Purpose
ECS or EKS	Container orchestration
CloudWatch	Logging and monitoring
VPC	Network isolation
Elastic Load Balancer	External traffic routing

---

Maintenance

Routine Updates

• Updated container images are distributed through the applicable AWS Marketplace or Eclypses release channel.

Fault Recovery

• Relaunch the SocketX container or task. Clients reconnect and pair again.

Service Limits

• ECS: ECS Service Quotas
• CloudWatch: CloudWatch Limits
• ELB: Load Balancer Limits

---

Supported Regions

Supported regions depend on the selected AWS Marketplace listing and Eclypses release channel. Check the listing or contact Eclypses Support for current availability.

---

Support

For assistance, contact Eclypses Support:

customer_support@eclypses.com

Monday-Friday, 8:00 AM-5:00 PM MST, excluding holidays.