SPACE / SATELLITE TERMINAL v1.0.4
ATDT BBS Native PHP Door
================================

Space / Satellite Terminal is a live ANSI information door for ATDT BBS. It
combines current orbital, launch, space-weather, and near-Earth object data in
an 80x25-style retro terminal.

FEATURES
--------
- Live ISS latitude, longitude, altitude, velocity, footprint, and daylight status
- CelesTrak NORAD satellite lookup using GP orbital elements plus SATCAT metadata
- Upcoming launch schedule with mission detail screens
- NOAA planetary Kp, running A index, G/R/S scales, and Kp outlook
- NASA/JPL near-Earth close approaches within 10 lunar distances over 30 days
- ENTER cycles through the main live-information views
- Hidden door cursor through the ATDT manifest cursor setting
- No Composer dependencies
- No API keys
- No door-specific telemetry/history tables
- No historical telemetry storage

VERSION / IDENTITY
------------------
Door version: 1.0.4
Author: DOS BBS
Copyright 2026 Xendrome. All rights reserved.

The SysOp panel can store an optional contact address and BBS web site in
ATDT's small door key/value store. These values are used only to identify the
BBS in outbound HTTP User-Agent headers. Live API data is never stored in the
ATDT database.

STORAGE DESIGN
--------------
This build intentionally keeps its bounded runtime cache inside the door at:

  spaceterminal/cache/

The cache:
- overwrites/reuses entries by URL
- uses atomic writes
- uses non-blocking per-URL locks to prevent request stampedes
- retains last-good data for stale-if-error operation
- negatively caches failed providers for 60 seconds
- removes expired .tmp and orphaned .lock files
- is hard-capped at approximately 2 MiB and 96 JSON files
- stores no caller history

Runtime files that may appear in cache/ include JSON boxes, .lock files, .tmp
files during atomic writes, and a .gc cleanup timestamp. The release ZIP does
not ship a runtime .gc marker.

The cache directory includes a guarded deny-all .htaccess and empty index.html.
If the folder is recreated by the door, those protection files are recreated as
well. On web servers that do not honor .htaccess, the site administrator should
also deny direct web access to spaceterminal/cache/ at the server level.

NETWORK / RESILIENCE DESIGN
---------------------------
- HTTPS-only remote requests and HTTPS-only redirects
- IPv4 preferred for cURL on shared hosts with unreliable IPv6 routes
- 3 second connect timeout / 5 second per-request maximum
- approximately 8 second total network budget per caller screen
- 1 MiB hard response-size cap before a response can exhaust PHP memory
- stale-if-error on every live data source
- non-blocking cache locks: another caller uses existing cached data instead of waiting
- manual R refreshes respect source cache/minimum refresh intervals
- raw cURL/TLS/proxy details are logged for the SysOp, not shown to callers

The main terminal makes at most one live provider request (ISS). Its launch and
space-weather summary panels are cache-only; visiting L or W loads those feeds,
after which the main screen displays the cached summary.

LIVE SOURCES
------------
ISS position:
  https://api.wheretheiss.at

Satellite GP and SATCAT data:
  https://celestrak.org

Upcoming launches:
  https://ll.thespacedevs.com

Space weather:
  https://services.swpc.noaa.gov

Near-Earth close approaches:
  https://ssd-api.jpl.nasa.gov

All remote access is outbound HTTPS/TCP 443. No inbound service, daemon,
websocket, IRC connection, cron job, or background process is required.

INSTALLATION
------------
1. Copy the entire "spaceterminal" folder into ATDT's doors/ folder (or another
   native-door location supported by your ATDT installation).

2. Confirm the layout is:

     doors/
       spaceterminal/
         door.json
         door.php
         admin.php
         README.txt
         CHANGELOG.txt
         lib/
           AppInfo.php
           HttpCache.php
           SpaceService.php
         cache/
           .htaccess
           index.html

3. In the ATDT SysOp console, use "Scan doors/ folder".

4. Open the Space / Satellite Terminal v1.0.4 admin panel. Configure an optional
   SysOp contact/BBS website, then test providers individually as needed.

5. Add the door to a Menus entry using the DOOR action.

HOST REQUIREMENTS
-----------------
- ATDT BBS with Native PHP Door support
- PHP 8.1 or newer
- JSON extension
- mbstring extension
- OpenSSL support for HTTPS streams
- cURL strongly preferred; allow_url_fopen may be used as the HTTPS fallback
- outbound HTTPS/TCP 443
- write permission on spaceterminal/cache/

CALLER COMMANDS
---------------
I       ISS orbital tracking
S       Satellite lookup by NORAD catalog number
L       Upcoming launches
W       Space weather / solar conditions
N       Near-Earth close approaches
R       Refresh current view when that source's cache interval permits
?       Help
M       Main terminal from secondary screens
B       Back/Main on secondary screens where shown
Q       Quit from the main screen
X       Quit alias from the main screen
ENTER   Cycle ISS -> Launches -> Space Weather -> Near-Earth -> Main

SATELLITE LOOKUP
----------------
Examples:
25544   ISS (ZARYA)
20580   Hubble Space Telescope

Invalid text or an unknown/decayed NORAD number is reported as an input/not-found
condition, not as a network failure. The prompt immediately allows another ID.

Satellite detail uses two separately cached CelesTrak sources:
- GP orbital elements (15 minute normal TTL)
- SATCAT object type, country and launch-date metadata (7 day normal TTL)

CACHE / STALE LIFETIMES
-----------------------
ISS telemetry       15 sec normal TTL; manual R minimum 2 sec; stale up to 30 min
Satellite GP        15 min normal TTL; stale up to 24 hours
Satellite SATCAT    7 days normal TTL; stale up to 30 days
Launch schedule     10 min normal TTL; stale up to 6 hours
Space weather       5 min normal TTL; stale up to 2 hours
Close approaches    30 min normal TTL; stale up to 6 hours
Failed source retry 60 sec negative-cache window
Cleanup sweep       approximately every 30 minutes

DISPLAY SAFETY
--------------
Remote provider text is treated as untrusted display data. Control characters
including ESC are removed, pipe characters are escaped, and remote text is
rendered without ATDT %XX MCI substitution. Multibyte text is truncated,
wrapped and padded by display width rather than raw UTF-8 byte length.

NOTES
-----
Launch times are NET (no-earlier-than) values and can change.
Near-Earth close-approach data is not an impact prediction.
Space-weather values are scientific/operational products and may be revised.

This door is not affiliated with or endorsed by WhereTheISS, CelesTrak,
The Space Devs, NOAA, NASA, JPL, or their respective data providers.
