Skip to content

Commit 04b7354

Browse files
Sam-BollingSam-Bolling
committed
docs: add section 13 - orbit track descending sort fix, deployment hierarchy bootstrap gap, new Go server behavioral differences
1 parent de7c08f commit 04b7354

1 file changed

Lines changed: 140 additions & 2 deletions

File tree

‎docs/research/CSAPI_Go_Server_Integration_Report_2026-04-17.md‎

Lines changed: 140 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -1,7 +1,7 @@
11
# CSAPI-Go Server Integration Report
22

3-
**Date:** 2026-04-17
4-
**Status:** Complete — Updated with ISS Investigation Results
3+
**Date:** 2026-04-17 (last updated 2026-04-18)
4+
**Status:** Complete — Updated with ISS Orbit Track & Deployment-Hierarchy Findings
55
**Scope:** Dual-publish the entire OS4CSAPI publisher fleet to the
66
connected-systems-go server
77

@@ -671,6 +671,144 @@ The ISS Orbit Track system and datastream exist on the Go server, but the datast
671671

672672
---
673673

674+
## 13 ISS Orbit Track & Deployment-Hierarchy Investigation (Added 2026-04-18)
675+
676+
After §12 closed out the position-marker visibility question, a follow-up
677+
investigation was opened when the ISS **orbit track polyline** and the ISS
678+
**deployed-system marker** were both absent from the Go server map in the
679+
deployed Explorer, while rendering correctly on OSH SensorHub. This section
680+
documents four additional Go-server behaviors, one Explorer bug (now fixed),
681+
and one bootstrap gap (now fixed).
682+
683+
### 13.1 Root Cause 3 — Observations returned in DESCENDING order by default
684+
685+
- **Severity:** P2-Major
686+
- **Comparison:** SensorHub returns observations in **ascending** time order
687+
by default. The Go server returns them in **descending** (newest-first) order.
688+
- **Impact:** The Explorer's `loadObservationLayers()` burst-dedup loop assumed
689+
ascending order when collapsing repeated point-observations into a single
690+
polyline. Running it on descending data caused every item after the first to
691+
be classified as a duplicate and dropped, leaving `trackCoords.length === 1`
692+
and no polyline ever being added to the map.
693+
- **Fix (Explorer):** Added an explicit ascending `allItems.sort()` by
694+
`phenomenonTime` immediately before the dedup loop. Committed to
695+
`ogc-csapi-explorer` as `604d7c1` and deployed to Cloudflare Pages.
696+
- **Result:** The full 500-point ISS orbit track now renders correctly on the
697+
Go-server map, matching OSH behavior.
698+
699+
### 13.2 Go server silently ignores `sortBy` / `sortOrder` parameters
700+
701+
- **Severity:** P3-Minor
702+
- **Problem:** Passing `sortBy=phenomenonTime&sortOrder=asc` to
703+
`/datastreams/{id}/observations` has no effect — the server returns the same
704+
descending order regardless of parameter values. No error, no warning.
705+
- **Workaround:** Client-side sort (see §13.1). Ordering cannot be requested
706+
from the server; it must be imposed by the consumer.
707+
708+
### 13.3 Go server silently ignores time-range filters
709+
710+
- **Severity:** P3-Minor
711+
- **Problem:** `resultTime=<start>/<end>`, `phenomenonTime=<start>/<end>`, and
712+
`datetime=<start>/<end>` range filters are all silently accepted and then
713+
ignored on `/datastreams/{id}/observations`. The full unfiltered result set
714+
is returned (subject to `limit`).
715+
- **Impact:** Clients that rely on server-side time-windowing (e.g., "last
716+
N minutes") must paginate and filter client-side. This compounds the
717+
ordering issue from §13.1 because the newest-first default means an
718+
unbounded query trims the *oldest* data.
719+
- **Workaround:** Request large `limit` values and filter by timestamp
720+
client-side. Not yet filed as an issue.
721+
722+
### 13.4 Cloudflare Pages production deployment stuck on stale build
723+
724+
- **Severity:** P2-Major (deployment / CI issue, not Go-server)
725+
- **Problem:** Production bundle at `ogc-csapi-explorer.pages.dev` remained on
726+
the Apr 17 build (`index-B_aWg6nq.js`) for multiple days after new commits
727+
were pushed to `main`. The GitHub → Cloudflare auto-deploy hook appears to
728+
have skipped several commits. This masked the §13.1 fix and sent the
729+
investigation down several incorrect paths.
730+
- **Workaround:** Manual Cloudflare redeploy after confirming the stuck state
731+
by inspecting the bundle hash in the live page. Future fixes need a
732+
deployment-smoke step that asserts a known marker string from the latest
733+
commit is present in the served bundle before declaring a fix verified.
734+
735+
### 13.5 Go server missing ISS deployment subtree (bootstrap gap)
736+
737+
- **Severity:** P2-Major (data completeness; Go server has partial parity)
738+
- **Problem:** On OSH, the ISS tracking context is a **four-level** deployment
739+
hierarchy:
740+
```
741+
Orbital Tracking Demo (root, geometry: null)
742+
└─ LEO Objects (geometry: null)
743+
└─ ISS Tracking Role (geometry: null)
744+
├─ ISS Position Feed → platform@link → ISS Position Publisher
745+
└─ ISS Orbit Track Feed → platform@link → ISS Orbit Track Publisher
746+
```
747+
The **leaf** deployments carry the `platform@link` that ties a deployment
748+
to a system. The Explorer's snap-to-track-tip logic in `MapViewPage.vue`
749+
matches deployments to systems by
750+
`rd.properties['platform@link'].href.split('/').pop() === dsInfo.systemId`.
751+
- **Go-server state:** Bootstrap created only the root `Orbital Tracking Demo`
752+
deployment. The three descendants — LEO Objects, ISS Tracking Role, and the
753+
two leaves carrying `platform@link` — were never created. As a result no
754+
Go-server deployment had a `platform@link` to the ISS systems, and the
755+
deployed-system marker could not be positioned on the map.
756+
- **Fix:** Added `scripts/bootstrap_iss_deployments_go.py` to the
757+
`ogc-csapi-explorer` repo. It is idempotent, searches by UID under each
758+
parent, POSTs to `/deployments/{parent_id}/subdeployments` with
759+
`application/geo+json`, and tolerates the Go server's `201 Created` +
760+
empty-body response by re-fetching the new resource by UID. After running
761+
it, the Go server now has the complete four-level hierarchy with
762+
`platform@link` on both leaves pointing at the ISS Position Publisher and
763+
ISS Orbit Track Publisher.
764+
- **Follow-up for `bootstrap_iss.py`:** The main ISS bootstrap script in this
765+
repo already encodes the full `DEPLOYMENT_TREE`, but it was not executed
766+
end-to-end against the Go server during the original fleet migration
767+
(only the root was persisted). The deployment helper's recursive
768+
`create_deployment_node()` should be re-validated against the Go server as
769+
a regression guard.
770+
771+
### 13.6 Go server missing `/deployments/{id}/systems` endpoint
772+
773+
- **Severity:** P3-Minor
774+
- **Problem:** `GET /deployments/{id}/systems` returns **404 Not Found** on
775+
the Go server. OSH supports this endpoint and uses it to list the systems
776+
associated with a deployment (independently of `platform@link` traversal).
777+
- **Impact:** Clients that discover systems via deployment → systems
778+
navigation instead of the reverse (`platform@link`) path are broken
779+
against Go. The Explorer does not currently rely on this endpoint, so
780+
no behavior change was required, but third-party clients may.
781+
- **Workaround:** Use `/deployments/{id}/subdeployments` to walk to leaves,
782+
then follow each leaf's `platform@link.href` to the system.
783+
784+
### 13.7 Updated Behavioral Comparison Additions
785+
786+
| Behavior | SensorHub | connected-systems-go |
787+
|---|---|---|
788+
| Observation default sort order | Ascending by `phenomenonTime` | **Descending** (newest-first) |
789+
| `sortBy` / `sortOrder` query params | Honored | **Silently ignored** |
790+
| `resultTime` / `phenomenonTime` / `datetime` range filters | Honored | **Silently ignored** |
791+
| `/deployments/{id}/systems` endpoint | Supported | **404 Not Found** |
792+
| Deployment `201 Created` response body | Full resource JSON | Empty; `Location` header only |
793+
794+
### 13.8 New Explorer commits (ogc-csapi-explorer `main`)
795+
796+
| Commit | Description |
797+
|--------|-------------|
798+
| `604d7c1` | fix(map): sort observations ascending before burst-dedup to handle Go server's descending default order; restores ISS orbit-track polyline on Go |
799+
| (script) | `scripts/bootstrap_iss_deployments_go.py` — idempotent creator for the missing ISS deployment subtree on Go, with `platform@link` on both leaves |
800+
801+
### 13.9 Outstanding items to file as Go-server issues
802+
803+
- Default descending observation order (documentation / configurability)
804+
- `sortBy` / `sortOrder` silently ignored
805+
- Time-range filters (`resultTime`, `phenomenonTime`, `datetime`) silently ignored
806+
- `/deployments/{id}/systems` endpoint missing (404)
807+
- `201 Created` with empty body on POST (should return created resource or at
808+
least `Location` consistently; clients must refetch by UID)
809+
810+
---
811+
674812
## Appendix A — VM Service Inventory
675813

676814
Services running on `129.80.248.53` as of 2026-04-17:

0 commit comments

Comments
 (0)