Skip to content

Architecture Overview Real Time Integration Strategy

Jump to bottom
Jordan edited this page Aug 17, 2026 · 4 revisions

Real-Time Integration Strategy

Preserved Qoder snapshot. This deep-dive page is retained so the earlier Wiki work and its source trail are not lost. For the reconciled implementation, Architecture Overview is canonical; references below to retired controllers, listeners, services, or API shapes are historical.

**Referenced Files in This Document** - [ResourceCalculationService.php](https://github.com/ObsidianNetwork/dynamic-pterodactyl/blob/6b7f83bda6f7c3fe014d52428b31af1638daa6cc/Services/ResourceCalculationService.php) - [AvailabilityController.php](https://github.com/ObsidianNetwork/dynamic-pterodactyl/blob/6b7f83bda6f7c3fe014d52428b31af1638daa6cc/Http/Controllers/Api/AvailabilityController.php) - [api.php](https://github.com/ObsidianNetwork/dynamic-pterodactyl/blob/6b7f83bda6f7c3fe014d52428b31af1638daa6cc/routes/api.php) - [DynamicPterodactyl.php](https://github.com/ObsidianNetwork/dynamic-pterodactyl/blob/6b7f83bda6f7c3fe014d52428b31af1638daa6cc/DynamicPterodactyl.php) - [ResourceCalculationServiceTest.php](https://github.com/ObsidianNetwork/dynamic-pterodactyl/blob/6b7f83bda6f7c3fe014d52428b31af1638daa6cc/tests/Unit/ResourceCalculationServiceTest.php) - [08-ALGORITHMS.md](https://github.com/ObsidianNetwork/dynamic-pterodactyl/blob/6b7f83bda6f7c3fe014d52428b31af1638daa6cc/08-ALGORITHMS.md) - [03-API.md](https://github.com/ObsidianNetwork/dynamic-pterodactyl/blob/6b7f83bda6f7c3fe014d52428b31af1638daa6cc/03-API.md)

Table of Contents

  1. Introduction
  2. Project Structure
  3. Core Components
  4. Architecture Overview
  5. Detailed Component Analysis
  6. Dependency Analysis
  7. Performance Considerations
  8. Troubleshooting Guide
  9. Conclusion

Introduction

This document explains the real-time integration strategy with the Pterodactyl panel API used by this extension. The core architectural decision is to never cache Pterodactyl API responses and always fetch current utilization data directly. This avoids stale availability, eliminates cache invalidation complexity, and prevents overselling during checkout.

The service layer batches API calls efficiently while preserving accuracy, and error handling covers timeouts, authentication failures, rate limiting, malformed responses, and degraded cluster snapshots when the upstream panel is unavailable.

Project Structure

The real-time integration spans a small set of focused components:

  • Service layer for real-time resource calculation and batching
  • API controllers that expose availability and admin-only node details
  • Route registration and throttling to protect the Pterodactyl API budget
  • Extension boot process wiring routes, views, listeners, and scheduled tasks
graph TB
Client["Customer or Admin Request"]
Routes["API Routes<br/>Throttled Endpoints"]
AvailabilityCtrl["AvailabilityController"]
ResourceSvc["ResourceCalculationService"]
PteroAPI["Pterodactyl Panel API"]
DB["Local Database<br/>Reservations & Config"]
Client --> Routes
Routes --> AvailabilityCtrl
AvailabilityCtrl --> ResourceSvc
ResourceSvc --> PteroAPI
ResourceSvc --> DB
Loading

Diagram sources

Section sources

Core Components

  • ResourceCalculationService: Centralizes all Pterodactyl API interactions, builds per-location and per-node availability, and constructs a full cluster snapshot without caching. It also implements robust HTTP retry, timeout, and error handling.
  • AvailabilityController: Exposes customer-facing availability endpoints that return aggregate location capacity only; node-level detail is reserved for admin flows.
  • Routes: Throttle availability and pricing endpoints to protect the Pterodactyl API budget and reduce load spikes.
  • Extension Boot: Registers routes, views, event listeners, and scheduled cleanup/alerts.

Key responsibilities:

  • Always read live state from Pterodactyl
  • Batch reads to minimize API calls
  • Preserve accuracy by including pending reservations
  • Fail fast on authentication and rate-limit errors
  • Return degraded snapshots when the panel is down

Section sources

Architecture Overview

The system uses a real-time, non-cached approach to ensure accurate availability at every step of the customer journey.

sequenceDiagram
participant C as "Client"
participant R as "Routes (throttled)"
participant A as "AvailabilityController"
participant S as "ResourceCalculationService"
participant P as "Pterodactyl API"
participant D as "Database"
C->>R : GET /availability/{locationId}
R->>A : getByLocation(locationId)
A->>S : getLocationAvailability(locationId)
S->>P : GET /locations/{id}?include=nodes,servers
S->>D : SUM pending reservations per node
S-->>A : Location availability + max available
A-->>C : Aggregate capacity response
Loading

Diagram sources

Detailed Component Analysis

Real-Time API Strategy and No-Caching Policy

  • All availability queries go directly to Pterodactyl. There is no local cache of nodes, servers, or utilization.
  • This design avoids stale data risks and simplifies correctness guarantees around reservation lifecycles.
  • Customer-facing endpoints return only aggregated per-location maxima; node-level detail is admin-only.

Section sources

Batching in buildClusterSnapshot()

buildClusterSnapshot() minimizes API calls while maintaining accuracy:

  • Fetches locations once
  • Attempts to fetch nodes with included servers in one paginated call
  • Falls back to a two-call strategy (nodes list plus servers index) if needed
  • Aggregates pending reservations across all nodes in a single grouped query
  • Computes totals, allocated, available, and utilization per node and per location
flowchart TD
Start(["buildClusterSnapshot"])
GetLoc["Fetch locations"]
TryNodesInc["Try fetch nodes with include=servers"]
FallbackNodes["Fallback: fetch nodes + fetch servers index"]
Pending["Aggregate pending reservations by node"]
ForEachNode["For each node:<br/>compute totals, allocated, available, utilization"]
Aggregate["Aggregate per location totals"]
Return(["Return snapshot"])
Start --> GetLoc --> TryNodesInc
TryNodesInc --> |Success| Pending
TryNodesInc --> |Failure| FallbackNodes --> Pending
Pending --> ForEachNode --> Aggregate --> Return
Loading

Diagram sources

Section sources

HTTP Client, Timeouts, Retries, and Error Handling

All outbound requests go through a centralized helper that:

  • Attaches Authorization and Accept headers
  • Applies per-attempt timeout and connect timeout
  • Retries only on transient connection exceptions
  • Treats 429 as a hard failure (rate limit exceeded)
  • Reports detailed upstream errors internally but throws sanitized messages outward
  • Validates JSON payloads and rejects malformed responses
flowchart TD
Enter(["pterodactylGet(path, query)"])
Headers["Attach headers<br/>Authorization, Accept"]
Timeout["Apply timeouts<br/>connectTimeout + timeout"]
Retry{"ConnectionException?"}
Call["HTTP GET"]
RateLimit{"Status 429?"}
Failed{"Response failed?"}
Report["Report full body for diagnostics"]
ThrowErr["Throw sanitized RuntimeException"]
Validate{"Valid JSON?"}
Return(["Return payload"])
Enter --> Headers --> Timeout --> Call
Call --> Retry
Retry --> |Yes| Retry
Retry --> |No| RateLimit
RateLimit --> |Yes| ThrowErr
RateLimit --> |No| Failed
Failed --> |Yes| Report --> ThrowErr
Failed --> |No| Validate
Validate --> |Yes| Return
Validate --> |No| ThrowErr
Loading

Diagram sources

Error scenarios covered:

  • Authentication failures: handled by Pterodactyl returning client errors; these are reported and thrown as runtime exceptions with sanitized messages
  • Timeouts and connection errors: retried up to configured attempts; after retries, a sanitized exception is thrown
  • Rate limiting: explicit 429 handling throws a clear message instructing retry later
  • Malformed JSON: validated and rejected with a descriptive exception
  • Degraded snapshot: when the panel returns server errors, buildClusterSnapshot returns an empty snapshot marked as unavailable instead of crashing the caller

Section sources

Connection Pooling and Request Batching

  • Connection pooling: Uses the framework’s HTTP client, which reuses connections by default. This reduces TCP handshake overhead for repeated calls within a request lifecycle.
  • Request batching:
    • Paginates large lists (locations, nodes) to avoid oversized responses
    • Prefers fetching nodes with included servers to reduce round trips
    • Falls back to a two-call strategy if includes are not supported or fail
    • Aggregates pending reservations in a single database query per snapshot

These choices keep the number of API calls constant regardless of cluster size, as verified by tests asserting bounded call counts even with many nodes.

Section sources

Monitoring and Logging

  • Internal diagnostics: Full upstream error bodies are reported for observability without leaking sensitive details to callers
  • Admin connectivity checks: A dedicated diagnostic endpoint uses a longer timeout and different error surface to validate configuration and reachability
  • Scheduled tasks: Cleanup of expired reservations and capacity alerts run on schedules defined in the extension boot process
  • Throttling: Public endpoints are rate-limited to protect both the application and the Pterodactyl API budget

Operational recommendations:

  • Track success/failure rates of Pterodactyl calls via your application logging pipeline
  • Monitor average and p95/p99 latency of availability endpoints
  • Alert on repeated 429 or 5xx responses from Pterodactyl
  • Correlate dashboard health banners with connection test results

Section sources

Dependency Analysis

The real-time integration depends on:

  • Framework HTTP client for outbound requests
  • Local database for pending reservations and configuration
  • Pterodactyl Panel API for authoritative node and server state
graph LR
RC["ResourceCalculationService"]
HC["Framework HTTP Client"]
DB["Local Database"]
PA["Pterodactyl Panel API"]
RC --> HC
RC --> DB
HC --> PA
Loading

Diagram sources

Section sources

Performance Considerations

  • Timeouts: Per-attempt timeouts and connect timeouts prevent long hangs; retries are limited to transient connection issues
  • Retries: Only connection exceptions trigger retries; HTTP errors like 429 and 5xx do not retry to avoid amplifying upstream load
  • Pagination: Large datasets are fetched page-by-page to control memory and network usage
  • Batching: Prefer includes where possible; fall back to minimal calls when necessary
  • Throttling: Public endpoints are throttled to respect Pterodactyl API limits
  • Degraded mode: When the panel is down, snapshot methods return a safe, empty structure so UIs remain responsive

[No sources needed since this section provides general guidance]

Troubleshooting Guide

Common issues and how they are handled:

  • Authentication failures: Upstream client errors are reported and surfaced as sanitized exceptions; verify API key and permissions
  • Timeouts: Connection exceptions are retried; if exhausted, a clear error is thrown; check network paths and DNS
  • Rate limiting: 429 responses throw a specific error; implement client-side backoff and reduce request frequency
  • Malformed responses: Invalid JSON triggers a validation error; inspect upstream panel health
  • Panel downtime: buildClusterSnapshot returns a degraded snapshot indicating unavailability; UI can show a warning banner

Verification steps:

  • Use the connection test method to validate URL and API key with a longer timeout
  • Check logs for reported upstream errors and status codes
  • Confirm throttling settings align with Pterodactyl API limits

Section sources

Conclusion

This extension integrates with Pterodactyl using a strict real-time strategy: no caching, direct API reads, and careful batching to balance accuracy and performance. Robust error handling ensures graceful degradation when the panel is unavailable, while throttling and timeouts protect both systems under load. Operational monitoring and logging provide visibility into API health and performance, enabling proactive management of capacity and reliability.

DynamicPterodactyl · Dynamic Resource Sliders for Paymenter × Pterodactyl · Reviewed code checkpoint · Publication commits intentionally pin their latest code-bearing predecessor because a Git commit cannot self-reference its unknown object ID.

DynamicPterodactyl

Guides

Architecture

Core Services

API Reference

Database

System

Clone this wiki locally