WSA Implementation

Makefile

@@ -0,0 +1,92 @@
+DOCKER_EXEC = docker compose exec api
+PHPUNIT = $(DOCKER_EXEC) vendor/bin/phpunit --bootstrap tests/autoload.php --testdox
+
+# Events-shape migration runners. Dry-run by default; pass APPLY=1 to write.
+MIGRATE_EVENTS = $(DOCKER_EXEC) php management/events
+APPLY_FLAG = $(if $(APPLY),--apply,)
+
+.PHONY: help test event-tests regression-tests test-filter test-file shell exec restart-movies db-shell \
+        migrate-events migrate-screenshots migrate-movies migrate-client-states requeue-movie
+
+.DEFAULT_GOAL := help
+
+help:
+	@echo "Available commands:"
+	@echo "  make test                  - Run all unit tests"
+	@echo "  make event-tests           - Run EventsApi tests"
+	@echo "  make regression-tests      - Run regression tests"
+	@echo "  make test-filter f=...     - Run tests whose name matches the PHPUnit --filter regex"
+	@echo "                               e.g. make test-filter f=testItShouldFallBack"
+	@echo "                               e.g. make test-filter f=LegacyEventString"
+	@echo "  make test-file p=...       - Run a single test file or directory under tests/unit_tests"
+	@echo "                               e.g. make test-file p=tests/unit_tests/validation/LegacyEventStringTest.php"
+	@echo "                               e.g. make test-file p=tests/unit_tests/events"
+	@echo "  make shell                 - Open bash shell in api container"
+	@echo "  make exec cmd=\"...\"        - Run a command in api container"
+	@echo "  make restart-movies        - Restart movies container"
+	@echo "  make db-shell              - Open MySQL shell"
+	@echo "  make migrate-events        - Events-shape migration, all tables (dry-run)"
+	@echo "                               lists unique tree=>shape conversions, writes nothing"
+	@echo "                               add APPLY=1 to actually write, e.g. make migrate-events APPLY=1"
+	@echo "  make migrate-screenshots   - Only the screenshots table (dry-run; APPLY=1 to write)"
+	@echo "  make migrate-movies        - Only the movies table (dry-run; APPLY=1 to write)"
+	@echo "  make migrate-client-states - Only the client_states table (dry-run; APPLY=1 to write)"
+	@echo "  make requeue-movie id=...  - Rebuild a movie by its public id (force=true)"
+	@echo "                               e.g. make requeue-movie id=hl66n"
+
+shell:
+	$(DOCKER_EXEC) bash
+
+exec:
+	$(DOCKER_EXEC) $(cmd)
+
+test:
+	$(PHPUNIT) tests/unit_tests
+
+event-tests:
+	$(PHPUNIT) tests/unit_tests/events/
+
+regression-tests:
+	$(PHPUNIT) tests/unit_tests/regression/
+
+# Run only tests whose method name matches the given regex.
+# Usage: make test-filter f=<regex>      (also accepts: filter=, FILTER=)
+test-filter:
+	@if [ -z "$(f)$(filter)$(FILTER)" ]; then \
+		echo "Error: pass a filter, e.g. make test-filter f=testItShouldFallBack"; exit 1; \
+	fi
+	$(PHPUNIT) tests/unit_tests --filter '$(f)$(filter)$(FILTER)'
+
+# Run a single test file (or limit to a sub-directory).
+# Usage: make test-file p=tests/unit_tests/validation/LegacyEventStringTest.php
+test-file:
+	@if [ -z "$(p)$(path)$(PATH_)" ]; then \
+		echo "Error: pass a path, e.g. make test-file p=tests/unit_tests/validation/LegacyEventStringTest.php"; exit 1; \
+	fi
+	$(PHPUNIT) '$(p)$(path)$(PATH_)'
+
+restart-movies:
+	docker compose restart movies
+
+db-shell:
+	docker compose exec database mariadb -u helioviewer -phelioviewer helioviewer
+
+# Events-shape migration. Each target is dry-run by default (lists unique
+# tree=>shape conversions, no writes); pass APPLY=1 to perform the UPDATEs.
+migrate-screenshots:
+	$(MIGRATE_EVENTS)/migrate_screenshots_events_shape.php $(APPLY_FLAG)
+
+migrate-movies:
+	$(MIGRATE_EVENTS)/migrate_movies_events_shape.php $(APPLY_FLAG)
+
+migrate-client-states:
+	$(MIGRATE_EVENTS)/migrate_client_states_events_shape.php $(APPLY_FLAG)
+
+migrate-events: migrate-screenshots migrate-movies migrate-client-states
+
+# Rebuild a movie by its public id (e.g. hl66n). force=true so it re-queues even
+# when the cached file already exists. Usage: make requeue-movie id=hl66n
+requeue-movie:
+	@if [ -z "$(id)" ]; then echo "Error: pass id=<movieCode>, e.g. make requeue-movie id=hl66n"; exit 1; fi
+	$(DOCKER_EXEC) curl -s "http://localhost/?action=reQueueMovie&id=$(id)&force=true"
+	@echo

README.md

@@ -16,6 +16,25 @@ If you wish to run your own local copy of Helioviewer.org, you have 2 options.
 - Through the development [container](https://hub.docker.com/r/dgarciabriseno/helioviewer.org-docker).
 - Manual Installation with instructions [here](https://helioviewer-project.github.io/install/).
 
+## Development
+
+A `Makefile` wraps the common `docker compose` workflows for the API container.
+Run `make help` for the full list. The most-used targets:
+
+| Command | What it does |
+| --- | --- |
+| `make test` | Run all unit tests |
+| `make event-tests` | Run the events test suite |
+| `make regression-tests` | Run the regression suite |
+| `make test-file p=<path>` | Run a single test file or directory, e.g. `make test-file p=tests/unit_tests/events` |
+| `make test-filter f=<regex>` | Run tests whose method name matches a regex, e.g. `make test-filter f=testItShouldFallBack` |
+| `make shell` | Open a bash shell in the `api` container |
+| `make exec cmd="..."` | Run an arbitrary command in the `api` container |
+| `make restart-movies` | Restart the `movies` worker container |
+| `make db-shell` | Open a MySQL shell against the dev database |
+
+All targets assume the development container is running (`docker compose up`).
+
 ## License
 
 Helioviewer.org is licensed under the Mozilla Public License.

docroot/schema/client_state.schema.json

@@ -10,8 +10,11 @@
         "centerX": { "type": "number" },
         "centerY": { "type": "number" },
         "imageScale": { "type": "number" },
-        "eventLayers": {
-            "$ref": "https://api.helioviewer.org/schema/event_layers.schema.json"
+        "event_selections": {
+            "$ref": "https://api.helioviewer.org/schema/event_selections.schema.json"
+        },
+        "event_visibility_selections": {
+            "$ref": "https://api.helioviewer.org/schema/event_visibility_selections.schema.json"
         },
         "imageLayers": {
             "type": "array",
@@ -29,7 +32,8 @@
         "centerX",
         "centerY",
         "imageScale",
-        "eventLayers",
+        "event_selections",
+        "event_visibility_selections",
         "imageLayers",
         "celestialBodies"
     ]

docroot/schema/event_layers.schema.json

@@ -16,7 +16,8 @@
                     "enum": [
                         "HEK",
                         "CCMC",
-                        "RHESSI"
+                        "RHESSI",
+                        "WSA"
                     ]
                 },
                 "visible": { "type": "boolean" },
@@ -53,7 +54,7 @@
                             },
                             "event_instances": {
                                 "type": "array",
-                                "maxItems": 30,
+                                "maxItems": 200,
                                 "items": {
                                     "type": "string",
                                     "pattern": "^[a-zA-Z0-9]{2,3}--[a-zA-Z0-9_ +\\\\()\\-]{1,50}--[a-zA-Z0-9_.\\()+]+$",
@@ -66,6 +67,7 @@
                 },
                 "layers_v2": {
                     "type": "array",
+                    "maxItems": 200,
                     "items": {
                         "type": "string",
                         "minLength": 1,

docroot/schema/event_selections.schema.json

@@ -0,0 +1,14 @@
+{
+    "$schema": "https://json-schema.org/draft/2020-12/schema",
+    "$id": "https://api.helioviewer.org/schema/event_selections.schema.json",
+    "title": "Event Selections",
+    "description": "Selection paths for the events API. Paths are canonical SOURCE>>Label[>>FRM[>>...]] strings; variable depth is allowed. Upstream cap is 200 selections per request.",
+    "type": "array",
+    "minItems": 0,
+    "maxItems": 200,
+    "items": {
+        "type": "string",
+        "minLength": 1,
+        "maxLength": 600
+    }
+}

docroot/schema/event_visibility_selections.schema.json

@@ -0,0 +1,24 @@
+{
+    "$schema": "https://json-schema.org/draft/2020-12/schema",
+    "$id": "https://api.helioviewer.org/schema/event_visibility_selections.schema.json",
+    "title": "Event Visibility Selections",
+    "description": "Per-source marker and label visibility flags. Keys are canonical event source names; unknown sources are rejected. Both flags are optional per source and default to true server-side when omitted.",
+    "type": "object",
+    "additionalProperties": false,
+    "properties": {
+        "HEK":    { "$ref": "#/$defs/source_flags" },
+        "CCMC":   { "$ref": "#/$defs/source_flags" },
+        "RHESSI": { "$ref": "#/$defs/source_flags" },
+        "WSA":    { "$ref": "#/$defs/source_flags" }
+    },
+    "$defs": {
+        "source_flags": {
+            "type": "object",
+            "additionalProperties": false,
+            "properties": {
+                "marker_visibility": { "type": "boolean" },
+                "label_visibility":  { "type": "boolean" }
+            }
+        }
+    }
+}

docroot/schema/events_data_coverage.schema.json

@@ -0,0 +1,17 @@
+{
+    "$schema": "https://json-schema.org/draft/2020-12/schema",
+    "$id": "https://api.helioviewer.org/schema/events_data_coverage.schema.json",
+    "title": "eventsDataCoverage request body",
+    "description": "Selection paths for the events timeline. Paths are canonical SOURCE>>Label[>>FRM[>>...]] strings; variable depth is allowed. At least one selection is required.",
+    "type": "object",
+    "additionalProperties": false,
+    "required": ["event_selections"],
+    "properties": {
+        "event_selections": {
+            "allOf": [
+                { "$ref": "https://api.helioviewer.org/schema/event_selections.schema.json" },
+                { "minItems": 1 }
+            ]
+        }
+    }
+}

docroot/schema/post_movie.schema.json

@@ -19,8 +19,11 @@
             "maxLength": 1000,
             "pattern": "^[\\_\\w\\]\\[,\\-:\\.\\+ ]+$"
         },
-        "eventsState": {
-            "$ref": "https://api.helioviewer.org/schema/event_layers.schema.json"
+        "event_selections": {
+            "$ref": "https://api.helioviewer.org/schema/event_selections.schema.json"
+        },
+        "event_visibility_selections": {
+            "$ref": "https://api.helioviewer.org/schema/event_visibility_selections.schema.json"
         },
         "imageScale": { "type": "number" },
         "format": {

docroot/schema/post_screenshot.schema.json

@@ -17,8 +17,11 @@
             "maxLength": 1000,
             "pattern": "^[\\_\\w\\]\\[,\\-:\\.\\+ ]+$"
         },
-        "eventsState": {
-            "$ref": "https://api.helioviewer.org/schema/event_layers.schema.json"
+        "event_selections": {
+            "$ref": "https://api.helioviewer.org/schema/event_selections.schema.json"
+        },
+        "event_visibility_selections": {
+            "$ref": "https://api.helioviewer.org/schema/event_visibility_selections.schema.json"
         },
         "scale": { "type": "boolean" },
         "scaleType": {

docs/src/openapi.yaml

@@ -542,17 +542,9 @@ paths:
                 "endTime":     "2010-03-04T12:12:12Z",
                 "imageScale":  21.04,
                 "layers":      "[3,1,100]",
-                "eventsState": {
-                    "tree_HEK": {
-                        "labels_visible": true,
-                        "layers": [
-                            {
-                                "event_type": "flare",
-                                "frms": ["frm10", "frm20"],
-                                "event_instances": ["flare--frm1--event1", "flare--frm2--event2"]
-                            }
-                        ]
-                    }
+                "event_selections": ["HEK>>Active Region", "HEK>>Flare>>SWPC"],
+                "event_visibility_selections": {
+                    "HEK": { "marker_visibility": true, "label_visibility": true }
                 },
                 "x1": -5000,
                 "y1": -5000,
@@ -829,17 +821,32 @@ paths:
         - $ref: '#/components/parameters/screenshotDate'
         - $ref: '#/components/parameters/screenshotImageScale'
         - $ref: '#/components/parameters/screenshotLayers'
+        - name: event_selections
+          in: query
+          required: false
+          description: >
+            Canonical event selections as a semicolon-separated list of
+            ``SOURCE>>Label[>>FRM]`` paths, e.g.
+            ``HEK>>Active Region;CCMC>>DONKI``. Takes precedence over the legacy
+            ``events`` bracket-string when both are supplied. URL-encode the
+            value (``;`` and ``>>`` in particular).
+          schema:
+            type: string
         - name: events
           in: query
           required: false
           description: >
-            Feature/event annotations (e.g. `[AR,HMI_HARP;SPoCA,1],[CH,all,1]`).
+            Legacy feature/event annotations as a bracket-string, e.g.
+            ``[AR,HMI_HARP;SPoCA,1],[CH,all,1]``. Superseded by
+            ``event_selections``; used only when ``event_selections`` is absent.
           schema:
             type: string
         - name: eventLabels
           in: query
           required: false
-          description: Annotate each event marker with a text label.
+          description: >
+            Annotate each event marker with a text label. Applies to whichever
+            of ``event_selections`` / ``events`` is used.
           schema:
             type: boolean
         - $ref: '#/components/parameters/screenshotScale'
@@ -2160,6 +2167,42 @@ components:
         full:
           type: string
 
+    EventSelections:
+      type: array
+      maxItems: 200
+      description: >
+        Canonical event selection paths, each a ``SOURCE>>Label[>>FRM[>>...]]``
+        string (variable depth allowed). Upstream cap is 200 selections per
+        request.
+      items:
+        type: string
+        minLength: 1
+        maxLength: 600
+      example: ["HEK>>Active Region", "CCMC>>DONKI"]
+
+    EventVisibilitySelections:
+      type: object
+      additionalProperties: false
+      description: >
+        Per-source marker/label visibility. Keys are canonical event source
+        names; both flags are optional per source and default to true
+        server-side when omitted.
+      properties:
+        HEK:    { $ref: '#/components/schemas/EventSourceFlags' }
+        CCMC:   { $ref: '#/components/schemas/EventSourceFlags' }
+        RHESSI: { $ref: '#/components/schemas/EventSourceFlags' }
+        WSA:    { $ref: '#/components/schemas/EventSourceFlags' }
+      example:
+        HEK: { marker_visibility: true, label_visibility: false }
+        CCMC: { marker_visibility: true, label_visibility: true }
+
+    EventSourceFlags:
+      type: object
+      additionalProperties: false
+      properties:
+        marker_visibility: { type: boolean }
+        label_visibility:  { type: boolean }
+
     PostMovieRequest:
       type: object
       required: [startTime, endTime, imageScale, layers]
@@ -2175,11 +2218,10 @@ components:
         layers:
           type: string
           example: "[3,1,100]"
-        eventsState:
-          type: object
-          description: >
-            Optional feature/event annotation state. See the Helioviewer
-            events state documentation for structure details.
+        event_selections:
+          $ref: '#/components/schemas/EventSelections'
+        event_visibility_selections:
+          $ref: '#/components/schemas/EventVisibilitySelections'
         imageScale:
           type: number
           format: double
@@ -2263,9 +2305,10 @@ components:
         layers:
           type: string
           example: "[3,1,100]"
-        eventsState:
-          type: object
-          description: Optional feature/event annotation state.
+        event_selections:
+          $ref: '#/components/schemas/EventSelections'
+        event_visibility_selections:
+          $ref: '#/components/schemas/EventVisibilitySelections'
         scale:
           type: boolean
           default: false