Skip to content

WMO: add a geocode-prefix filter — country-wide is the only mode for sources without polygons (cn-cma-xx: 116 entities) #73

Description

@seevee

Description

Add a geocode-prefix filter as a fourth option in the WMO filter menu, alongside
country-wide, GPS location, and GPS tracker.

The user supplies a prefix (or several) matched against the values in
CAPAlert.geocodes for any scheme the source publishes. An alert is kept when any
of its geocode values starts with any configured prefix.

Motivation

For a source that publishes no polygons, country-wide is not the default — it is the
only mode that works.
Both existing narrowing modes are polygon-based
(WMOProvider._filter_by_polygon), so a user of such a source has no way to scope
their alerts at all.

cn-cma-xx (China, CMA) is the confirmed case:

observation value
RSS items 500
after the expires prefilter 491
live alert entities created 116
sampled bodies carrying <polygon> or <circle> 0 of 60
geocode scheme published CPEAS Geographic Code, e.g. 110228000000

Selecting GPS mode fails loud on every poll, which is the guard behaving correctly —
there is simply nothing for it to match:

Failed setup, will retry: WMO cn-cma-xx: GPS filter requested but 491 alerts
carry no polygons; this source does not publish per-alert geometry

So the user is left with 116 entities for the whole of China. That is not only
unwieldy — it destabilises the frontend. Observed in a dev instance while a single
country-wide cn-cma-xx entry populated:

Client unable to keep up with pending messages. Reached 4096 pending messages.
The system's load is too high or an integration is misbehaving; Last message was:
entity_registry_updated ... sensor.cap_alerts_wmo_cap_alert_bao_yu_061d030b

This is the configuration a Chinese-language user reaches by following #59 / #72 to
its conclusion: cn-cma-xx is the source that carries the zh-CN <info> blocks,
and country-wide is the only way to consume it.

Why prefix matching fits

CPEAS codes are hierarchical GB/T 2260 — 2 digits province, 4 prefecture, 6 county,
zero-padded to 12:

code scope
11 Beijing
1102 a Beijing prefecture-level division
110228000000 Miyun District

So one mechanism gives province-, prefecture-, and county-level scoping with no
region registry to fetch, no picker to populate, and no per-source special-casing.
Scheme-agnostic matching means it also covers other geometry-less sources that
publish some other code scheme (not yet surveyed — cn-cma-xx is the confirmed
case).

Crucially it hides nothing: alerts outside the prefix are ones that do not apply
to the user's area, which is the same contract the polygon filter already provides.

Alternatives considered

  • areaDesc substring filter — friendlier for users who do not know their codes
    (a Beijing user types 北京市), but imprecise, language-dependent, and it breaks when
    the selected <info> block changes language, which feat(wmo): select the CAP <info> block by language #72 made configurable.
  • Provider-neutral severity floor — the cheapest knob, and probably worth having
    separately, but wrong as the answer here: it discards alerts the user asked for
    rather than ones that do not apply to them.
  • Entity-count cap — bounded but arbitrary; silently dropping alerts is the wrong
    failure mode for an alerting integration.

Scope notes

  • Config flow: new wmo_geocode step in both async_step_wmo_filter and
    async_step_reconfigure_wmo_filter, plus strings.json / translations/.
  • Provider: filter applied where _filter_by_polygon is applied today, in
    WMOProvider.async_fetch.
  • The fail-loud contract needs deciding for the new mode — a prefix matching nothing
    is more likely a typo than a quiet period, but unlike the polygon case it cannot be
    distinguished from "no alerts in your area right now". See the plan.
  • Entity-count relief is the point, so it is worth measuring the real reduction for a
    representative prefix before/after.

Raised while verifying #72 in a dev instance; blocking the next alpha.

Metadata

Metadata

Assignees

No one assigned

    Labels

    enhancementNew feature or request

    Projects

    No projects

    Milestone

    No milestone

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions