Warframe Status

https://github.com/wfcd/warframe-status
Admin
Warframe Status is a NestJS-based API and WebSocket service providing real-time WorldState data for...
Tokens:6,098
Snippets:92
Trust Score:9.8
License:MIT
Update:2 months ago
Show doc for...
Tokens:
Raw
### Deploy with Docker Compose

Source: https://github.com/wfcd/warframe-status/blob/main/DEPLOYMENT.md

Initialize and start the service using the provided example configuration.

```bash
cp docker-compose.example.yml docker-compose.yml
docker compose up -d
```

--------------------------------

### Configure Docker Compose

Source: https://github.com/wfcd/warframe-status/blob/main/MIGRATION_PLAN.md

Example docker-compose.yml for orchestrating the container with environment variables and health checks.

```yaml
version: '3.8'

services:
  warframe-status:
    build: .
    image: warframe-status:latest
    container_name: warframe-status
    restart: unless-stopped
    ports:
      - "3000:3000"
    environment:
      # Server
      - NODE_ENV=production
      - HOST=0.0.0.0
      - PORT=3000
      
      # Clustering
      - USE_CLUSTER=true
      
      # Features (default enabled - set to override)
      # - USE_WORLDSTATE=false
      # - DISABLE_PRICECHECKS=true
      # - FEATURES=
      
      # Cache
      - BUILD=build
      
      # Optional integrations
      # - WFINFO_FILTERED_ITEMS=
      # - WFINFO_PRICES=
      # - TWITTER_KEY=
      # - TWITTER_SECRET=
      # - TWITTER_BEARER_TOKEN=
      # - SENTRY_DSN=
      
      # Logging
      - LOG_LEVEL=info
    volumes:
      - ./caches:/app/caches
    healthcheck:
      test: ["CMD", "wget", "--quiet", "--tries=1", "--spider", "http://localhost:3000/heartbeat"]
      interval: 30s
      timeout: 10s
      retries: 3
      start_period: 40s
```

--------------------------------

### Express Development Commands

Source: https://github.com/wfcd/warframe-status/blob/main/README.md

Commands for starting the Express development server, including an option for PM2 process management.

```bash
# Start development server
npm run dev

# With PM2
npm run dev:pm2
```

--------------------------------

### Global Test App Setup

Source: https://github.com/wfcd/warframe-status/blob/main/src/test/README.md

Retrieving a shared NestJS application instance to improve test performance.

```typescript
import { getApp } from '../hooks/setup.hook';

describe('Test Suite', () => {
  let nestApp: INestApplication;

  before(() => {
    nestApp = getApp(); // Get shared app instance
  });
});
```

--------------------------------

### WebSocket Event Response Structures

Source: https://github.com/wfcd/warframe-status/blob/main/README.md

Examples of event structures received from the WebSocket connection.

```json5
{
  event: 'twitter',
  packet: '[]', // tweets
}
```

```json5
{
  event: 'ws:update',
  packet: '{}', // entire updated worldstate
}
```

```json5
{
  event: '', // worldstate key,
  packet: '', // worldstate key data
}
```

--------------------------------

### Integration Test Example in TypeScript

Source: https://github.com/wfcd/warframe-status/blob/main/src/test/README.md

Integration test example featuring conditional skipping and extended timeouts for external API calls.

```typescript
describe('My Feature (integration)', function () {
  before(function () {
    // Skip if external APIs not available
    if (process.env.SKIP_INTEGRATION === 'true') {
      this.skip();
    }
  });

  it('should work with real data', async function () {
    this.timeout(30000); // Longer timeout for external calls
    
    const res = await request
      .execute(nestApp.getHttpServer())
      .get('/my-endpoint');
    
    res.should.have.status(200);
  });
});
```

--------------------------------

### Unit Test Example in TypeScript

Source: https://github.com/wfcd/warframe-status/blob/main/src/test/README.md

Standard unit test structure using Mocha and Chai with a shared NestJS application instance.

```typescript
import { expect } from 'chai';
import { getApp } from '../hooks/setup.hook';

describe('My Feature', () => {
  let nestApp: INestApplication;

  before(() => {
    nestApp = getApp();
  });

  it('should do something', async () => {
    const res = await request
      .execute(nestApp.getHttpServer())
      .get('/my-endpoint');
    
    expect(res.status).to.equal(200);
    expect(res.body).to.be.an('object');
  });
});
```

--------------------------------

### Build and Preview API Documentation

Source: https://github.com/wfcd/warframe-status/blob/main/README.md

Generate OpenAPI documentation and preview it locally.

```bash
# Export OpenAPI from Nest, lint with Redocly, and bundle static docs
npm run docs:build

# Local preview after building
npm run docs:preview
```

--------------------------------

### Deploy with Docker

Source: https://github.com/wfcd/warframe-status/blob/main/README.md

Build and run the application container using Docker.

```bash
# Build image
docker build -t ghcr.io/wfcd/warframe-status:latest .

# Run container
docker run -d \
  --name warframe-status \
  -p 3001:3001 \
  -v ./caches:/app/caches \
  ghcr.io/wfcd/warframe-status:latest
```

--------------------------------

### Build and run Docker container

Source: https://github.com/wfcd/warframe-status/blob/main/DEPLOYMENT.md

Pull the latest image and run it with volume mapping for caches.

```bash
docker pull ghcr.io/wfcd/warframe-status:latest

docker run -d \
  --name warframe-status \
  -p 3001:3001 \
  -v ./caches:/app/caches \
  ghcr.io/wfcd/warframe-status:latest
```

```bash
docker build -t ghcr.io/wfcd/warframe-status:latest .
```

--------------------------------

### Project Lifecycle Commands

Source: https://github.com/wfcd/warframe-status/blob/main/README.md

Standard npm commands for managing the project lifecycle.

```bash
# Install dependencies
npm install

# Development mode (hot reload)
npm run dev

# Build for production
npm run build

# Production mode
npm start
```

--------------------------------

### Execute Build and Deployment Commands

Source: https://github.com/wfcd/warframe-status/blob/main/MIGRATION_PLAN.md

Common CLI commands for managing the Docker container lifecycle.

```bash
# Build image
docker compose build

# Run with cache hydration
docker compose up -d

# Check logs
docker compose logs -f

# Health check
curl http://localhost:3000/heartbeat

# Stop
docker compose down
```

--------------------------------

### Clear cache and reinstall dependencies

Source: https://github.com/wfcd/warframe-status/blob/main/src/test/README.md

Use this command sequence to resolve 'Cannot find module' errors by resetting the local environment.

```bash
# Clear cache and reinstall
rm -rf node_modules package-lock.json
npm install
```

--------------------------------

### Initialize WarframeStatus API

Source: https://github.com/wfcd/warframe-status/blob/main/docs/web/index.html

Initializes the API documentation interface with a local OpenAPI specification and custom scroll offset.

```javascript
initTry({ openApi: './openapi.json', redocOptions: { scrollYOffset: 50 }, });
```

--------------------------------

### Environment Configuration

Source: https://github.com/wfcd/warframe-status/blob/main/MIGRATION_PLAN.md

Required and optional environment variables for server operation.

```bash
# Server
NODE_ENV=production
HOST=0.0.0.0
PORT=3000

# Clustering
USE_CLUSTER=true

# Features (passive defaults - enabled unless disabled)
USE_WORLDSTATE=true        # Worldstate enabled by default
FEATURES=SOCKET            # WebSocket enabled by default
DISABLE_PRICECHECKS=false  # Price checks enabled by default

# Cache
BUILD=                     # Empty = lazy hydration, 'build' = force immediate

# External APIs (optional)
WFINFO_FILTERED_ITEMS=https://example.com/filtered_items.json
WFINFO_PRICES=https://example.com/prices.json

# Twitter (optional)
TWITTER_KEY=
TWITTER_SECRET=
TWITTER_BEARER_TOKEN=

# Monitoring
SENTRY_DSN=
LOG_LEVEL=info
```

--------------------------------

### Mock Service Initialization

Source: https://github.com/wfcd/warframe-status/blob/main/src/test/README.md

Instantiating mock services to isolate unit tests from external dependencies.

```typescript
import { MockWorldStateService } from '../mocks/worldstate.mock';

// In test setup
const mockWorldState = new MockWorldStateService();
// ... use in test module
```

--------------------------------

### Configure Dockerfile for Production

Source: https://github.com/wfcd/warframe-status/blob/main/MIGRATION_PLAN.md

Multi-stage Dockerfile using Node 25 Alpine to build and serve the application.

```dockerfile
FROM node:25-alpine AS builder

WORKDIR /app

COPY package*.json ./
RUN npm ci --ignore-scripts --only=production

COPY . .
RUN npm run build

FROM node:25-alpine

WORKDIR /app

COPY --from=builder /app/dist ./dist
COPY --from=builder /app/node_modules ./node_modules
COPY --from=builder /app/package*.json ./

RUN mkdir -p /app/caches

ENV NODE_ENV=production
ENV HOST=0.0.0.0
ENV PORT=3000

EXPOSE 3000

CMD ["node", "dist/main.js"]
```

--------------------------------

### Project Directory Structure

Source: https://github.com/wfcd/warframe-status/blob/main/src/test/README.md

Visual representation of the test directory layout within the NestJS migration.

```text
src/nest/test/
├── e2e/                          # End-to-end tests
│   ├── *.spec.ts                 # Unit tests (mocked dependencies)
│   └── *-integration.spec.ts     # Integration tests (real services)
├── hooks/
│   └── setup.hook.ts             # Global test setup and app initialization
├── mocks/
│   └── worldstate.mock.ts        # Mock WorldStateService for unit tests
└── env-setup.ts                  # Environment variable configuration
```

--------------------------------

### Project Directory Structure

Source: https://github.com/wfcd/warframe-status/blob/main/MIGRATION_PLAN.md

Overview of the source code organization for the NestJS-based application.

```text
src/
├── main.ts                          # Application entry with clustering
├── app.module.ts                    # Root module
├── controllers/                     # Route handlers
│   ├── worldstate.controller.ts
│   ├── items.controller.ts
│   ├── drops.controller.ts
│   ├── profile.controller.ts
│   ├── pricecheck.controller.ts
│   ├── rivens.controller.ts
│   ├── data.controller.ts
│   ├── wfinfo.controller.ts
│   ├── twitter.controller.ts
│   ├── rss.controller.ts
│   └── heartbeat.controller.ts
├── services/                        # Business logic
│   ├── worldstate.service.ts
│   ├── items-cache.service.ts      # 117MB multi-language cache
│   ├── drops-cache.service.ts
│   ├── rivens-cache.service.ts
│   ├── wfinfo-cache.service.ts
│   ├── twitch-cache.service.ts
│   ├── hydration.service.ts        # Cache orchestrator
│   ├── logger.service.ts
│   └── cache.service.ts
├── gateways/                        # WebSocket
│   └── worldstate.gateway.ts
├── modules/                         # Feature modules
│   ├── cache.module.ts
│   └── logger.module.ts
├── guards/                          # Auth/feature guards
│   └── feature-flag.guard.ts
├── lib/                             # Shared utilities (from Express)
│   └── utilities.ts
└── test/                            # Tests
    ├── unit/
    ├── integration/
    └── e2e/
```

--------------------------------

### Run Express Tests

Source: https://github.com/wfcd/warframe-status/blob/main/README.md

Execute the test suite for the Express application.

```bash
npm test
```

--------------------------------

### Code Linting Commands

Source: https://github.com/wfcd/warframe-status/blob/main/README.md

Commands to run Biome for linting and automatic formatting fixes.

```bash
# Lint code
npm run lint

# Fix linting issues
npm run lint:fix
```

--------------------------------

### Perform Rollback

Source: https://github.com/wfcd/warframe-status/blob/main/MIGRATION_PLAN.md

Commands to revert the application state using git or previous Docker images.

```bash
# Revert to Express
git checkout <last-express-commit>

# Or use old Docker image
docker pull ghcr.io/wfcd/warframe-status:<express-version>
```

--------------------------------

### Test Execution Commands

Source: https://github.com/wfcd/warframe-status/blob/main/src/test/README.md

Shell commands to run unit, integration, or all tests, including watch mode.

```bash
# Unit tests (default)
npm run test:nest

# Integration tests
npm run test:nest:integration

# All tests
npm run test:nest:all

# Watch mode (unit tests)
npm run test:nest:watch
```

--------------------------------

### Define Test Scripts in package.json

Source: https://github.com/wfcd/warframe-status/blob/main/MIGRATION_PLAN.md

Configuration for running unit, integration, and E2E tests using Mocha and c8 for coverage.

```json
{
  "test": "NODE_ENV=test mocha --config .mocharc.yaml",
  "test:watch": "npm test -- --watch",
  "test:cov": "c8 npm test",
  "test:integration": "NODE_ENV=test mocha --config .mocharc.integration.yaml",
  "test:e2e": "NODE_ENV=test mocha --config .mocharc.e2e.yaml"
}
```

--------------------------------

### Clustering Configuration

Source: https://github.com/wfcd/warframe-status/blob/main/MIGRATION_PLAN.md

Logic for spawning worker processes based on CPU count and environment variables.

```typescript
// Half of available CPUs
const cpus = Math.floor(os.cpus().length / 2);

if (cluster.isPrimary && cpus > 2 && process.env.USE_CLUSTER === 'true') {
  // Fork workers
  for (let i = 0; i < cpus; i++) cluster.fork();
  
  // Auto-restart on crash
  cluster.on('exit', (worker) => {
    logger.warn(`Worker ${worker.process.pid} died. Restarting...`);
    cluster.fork();
  });
} else {
  // Worker or non-cluster mode
  await bootstrap();
}
```

--------------------------------

### Manually regenerate DTOs and routes

Source: https://github.com/wfcd/warframe-status/blob/main/src/dto/worldstate-generated/README.md

Execute these commands to manually trigger the generation of DTO and route files.

```bash
npm run generate:dtos
npm run generate:routes
```

--------------------------------

### Run NestJS Tests

Source: https://github.com/wfcd/warframe-status/blob/main/README.md

Execute unit, integration, or watch mode tests for the NestJS application.

```bash
# Unit tests (fast, uses mocks)
npm run test:nest

# Integration tests (slow, uses real APIs)
npm run test:nest:integration

# All tests
npm run test:nest:all

# Watch mode
npm run test:nest:watch
```

--------------------------------

### Deploy with Cloudflare WARP sidecar

Source: https://github.com/wfcd/warframe-status/blob/main/DEPLOYMENT.md

Use the WARP sidecar configuration to bypass geo-restrictions for worldstate endpoints.

```bash
cp docker-compose.warp.example.yml docker-compose.yml
docker compose up -d
```

```bash
curl http://localhost:8080/heartbeat
curl http://localhost:8080/pc/alerts
```

--------------------------------

### Git Workflow Commands

Source: https://github.com/wfcd/warframe-status/blob/main/README.md

Standard commands for contributing to the repository via feature branches.

```bash
git checkout -b feature/amazing-feature
git commit -m 'Add amazing feature'
git push origin feature/amazing-feature
```

--------------------------------

### NestJS Development Commands

Source: https://github.com/wfcd/warframe-status/blob/main/README.md

Commands for managing the NestJS development lifecycle, including hot-reloading, debugging, and production builds.

```bash
# Start development server (hot reload)
npm run nest:start:dev

# Debug mode
npm run nest:start:debug

# Build for production
npm run nest:build

# Run tests
npm run test:nest
```

--------------------------------

### REST-ish API Access

Source: https://github.com/wfcd/warframe-status/blob/main/README.md

Access worldstate data and static game information via standard HTTP requests.

```APIDOC
## GET /$platform

### Description
Retrieves the worldstate for a specific platform.

### Method
GET

### Endpoint
/$platform

## GET /$platform/$child-item

### Description
Retrieves specific child-item data for a platform.

### Method
GET

### Endpoint
/$platform/$child-item

## GET /$a-bunch-of-static-data

### Description
Retrieves static game data.

### Method
GET

### Endpoint
/$a-bunch-of-static-data
```

--------------------------------

### WebSocket API

Source: https://github.com/wfcd/warframe-status/blob/main/README.md

Connect to the WebSocket server to receive real-time updates and subscribe to specific event streams.

```APIDOC
## WebSocket Connection

### Description
Connect to the service via ws:// or wss:// to receive real-time updates. Requests are sent as JSON strings in the socket packet.

### Endpoint
ws://$host:$port/socket

### Request Examples
- Worldstate Request: { "event": "ws:req", "packet": { "platform": "$platform", "language": "$language" } }
- Twitter Feed: { "event": "twitter" }
- RSS Feed: { "event": "rss" }
```

--------------------------------

### Verify DTO output without writing files

Source: https://github.com/wfcd/warframe-status/blob/main/src/dto/worldstate-generated/README.md

Use the --check flag to validate the current state of generated DTOs against the source without modifying the filesystem.

```bash
npm run generate:dtos -- --check
```

--------------------------------

### Verify API health

Source: https://github.com/wfcd/warframe-status/blob/main/DEPLOYMENT.md

Check the heartbeat endpoint to ensure the service is running correctly.

```bash
curl http://localhost:3001/heartbeat
```

```json
{ "message": "Success", "code": 200 }
```

--------------------------------

### WebSocket Message Protocol

Source: https://github.com/wfcd/warframe-status/blob/main/MIGRATION_PLAN.md

Standardized event structures for client-server communication.

```typescript
// Client → Server
{ event: 'ws:req', packet: { platform: 'pc', language: 'en' } }
{ event: 'twitter' }
{ event: 'rss' }

// Server → Client
{ event: 'connected', packet: {} }
{ event: 'ws:provide', packet: { /* worldstate data */ } }
{ event: 'ws:update', packet: { /* full worldstate */ } }
{ event: 'ws:event', packet: { /* specific event */ } }
{ event: 'tweet', packet: [] }
```

--------------------------------

### WebSocket Request JSON Structure

Source: https://github.com/wfcd/warframe-status/blob/main/README.md

JSON structures for sending requests over the WebSocket connection.

```json
{ "event": "ws:req", "packet": { "platform": "$platform", "language": "$language" } }
```

```json
{ "event": "twitter" }
```

```json
{ "event": "rss" }
```

--------------------------------

### Increase test timeout

Source: https://github.com/wfcd/warframe-status/blob/main/src/test/README.md

Adjust the timeout duration within a test file to prevent premature failures during slow external API responses.

```typescript
this.timeout(60000)
```
Tokens:
Raw