FreeTLab/pluriwave
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

feat(paises): add country browser and extract shared radio transport

Browse Source 
Extracts ServicioRadio's transport loop (server discovery, host rotation,
bounded retries, User-Agent, timeout, status check, json.decode, sticky-host
bookkeeping) out of `_get` into a new `_getJson(path, params) ->
Future<List<dynamic>>` helper, moved as one block with no logic edits. `_get`
is reimplemented on top, still owning every station-specific concern:
`lastcheckok: '1'`, `Emisora.fromApi` + the empty-uuid/url filter, and the
`_compararCalidad` quality sort. `_getJson` is deliberately sort-agnostic and
filter-agnostic so a non-station endpoint can reuse the resilience behaviour
without inheriting station-only semantics.

Non-negotiable ordering followed per design ADR-4: new
test/servicios/servicio_radio_transporte_test.dart characterises all 8
existing station calls (7 via `_get` plus `registrarClick`, which builds its
own URI) against the UNMODIFIED `_get` first - green by construction -
pinning path, lastcheckok=1, hidebroken=true, a non-empty User-Agent, exact
order/reverse/limit/offset, and the exact returned UUID sequence from a
fixture with deliberately shuffled bitrate/clickcount/votes. That last
assertion is what makes the extraction safe: a sort that silently sank into
transport would pass every other check. Re-running the same file after the
extraction is byte-identical green. test/servicios/servicio_radio_test.dart
is untouched by this work unit - its passing unmodified is itself a signal
that transport wasn't disturbed.

The 6 pre-existing `order: bitrate` occurrences (obtenerPopulares,
buscarPorNombre, buscarPorPais, buscarPorIdioma, buscarPorTag, buscar) are
untouched - a deliberate server-side quality bias deciding which stations
return within `limit`, unrelated to and never to be confused with the
user-facing "Ordenar" control, which stays entirely client-side via the
existing OrdenEmisoras (Engram reference/radio-browser-sort-order).

Behaviour delta, accepted per ADR-4, not a regression: moving
`_servidorActual` bookkeeping into `_getJson` means a successful
`/json/countries` call now warms the sticky host for subsequent station
calls too - one shared warm mirror per instance, desirable, not per-call-type
state.

Adds the Paises browser over the verified `/json/countries` contract (Engram
reference/radio-browser-countries-endpoint): new lib/modelos/pais_radio.dart
(`PaisRadio.fromApi` parses `stationcount` via `int.tryParse` since the API
returns it as a JSON string, not an int - an `as int` cast would throw),
`obtenerPaises()` sends neither `lastcheckok` nor `order` (the screen sorts
client-side by name; the API's raw byte order isn't proper collation for any
locale this app ships), and inherits `hidebroken=true` from the unchanged
`_uri` (desirable here too, since the endpoint's own default is false).
`EstadoBusqueda` gains `paises`/`cargandoPaises`/`cargarPaises()` with an
in-memory cache guard so re-entering the screen never refetches.

New PantallaPaises (lib/pantallas/pantalla_paises.dart): a "Tus idiomas"
shortlist (one representative country per the app's 13 supported locales,
matched against the fetched list - the proposal/spec name this section but
don't specify its derivation) above the full alphabetical list, each entry
showing its parsed station count. Reachable from Buscar's discovery landing
state via a new entry row, added now rather than left dangling per this
file's own forward-reference comment (and the WU15/WU15b lesson: a
fully-tested but unreachable screen is a real defect, not a follow-up).

New ARB keys (en/es only, matching this change's established precedent):
countriesScreenTitle, countriesYourLanguagesTitle, countriesAllTitle,
radioCountriesError.

Tests: 631 -> 649 (2 skipped, unchanged). flutter analyze unchanged at 1
pre-existing info. grep confirms `countrycodes` appears nowhere in lib/.
This commit is contained in:
FreeTLab
2026-07-29 09:36:31 +02:00
parent 9bd828139f
commit c6f16c81b5
27 changed files with 1087 additions and 46 deletions
Download Patch File Download Diff File Expand all files Collapse all files
lib/servicios/servicio_radio.dart
+67 -14
View File
@@ -4,6 +4,7 @@ import 'package:http/http.dart' as http;
import 'package:package_info_plus/package_info_plus.dart';
import '../modelos/emisora.dart';
import '../modelos/pais_radio.dart';
/// Cliente para la Radio Browser API (https://api.radio-browser.info/).
///
@@ -157,7 +158,25 @@ class ServicioRadio {
return _descubrimientoEnCurso!;
}
Future<List<Emisora>> _get(String path, Map<String, String> params) async {
/// Transport ONLY: server discovery, host rotation, bounded retries,
/// User-Agent, timeout, status check, `json.decode`, sticky-host
/// bookkeeping. No filters, no models, no ordering — deliberately
/// sort-agnostic and filter-agnostic so non-station endpoints (e.g.
/// `/json/countries`, via [obtenerPaises]) can reuse this resilience
/// behaviour without inheriting station-only semantics such as
/// `lastcheckok` or bitrate ordering (design ADR-4).
///
/// Extracted verbatim from `_get` — no logic edits — so the 8 existing
/// station calls stay byte-identical
/// (`test/servicios/servicio_radio_transporte_test.dart`).
///
/// Named behaviour delta, accepted per ADR-4: `_servidorActual` is set here
/// on success/failure, so a successful `/json/countries` call now warms
/// the sticky host for subsequent station calls too.
Future<List<dynamic>> _getJson(
String path,
Map<String, String> params,
) async {
await _descubrirServidores();
Exception? ultimoError;
final indiceBase = _indiceServidorInicial();
@@ -165,14 +184,11 @@ class ServicioRadio {
for (int intento = 0; intento < totalIntentos; intento++) {
final servidor = _servidorPorIntento(indiceBase, intento);
final uri = _uri(servidor, path, {'lastcheckok': '1', ...params});
final uri = _uri(servidor, path, params);
try {
final resp = await _cliente
.get(
uri,
headers: {'User-Agent': await _resolverUserAgent()},
)
.get(uri, headers: {'User-Agent': await _resolverUserAgent()})
.timeout(_timeout);
if (resp.statusCode != 200) {
@@ -181,14 +197,7 @@ class ServicioRadio {
final lista = json.decode(resp.body) as List<dynamic>;
_servidorActual = servidor;
final emisoras =
lista
.cast<Map<String, dynamic>>()
.map(Emisora.fromApi)
.where((e) => e.uuid.isNotEmpty && e.url.isNotEmpty)
.toList();
emisoras.sort(_compararCalidad);
return emisoras;
return lista;
} on Exception catch (e) {
ultimoError = e;
_servidorActual = null;
@@ -203,6 +212,22 @@ class ServicioRadio {
throw ultimoError ?? Exception('Error desconocido al consultar la API');
}
/// Station layer over [_getJson]: adds the station-only `lastcheckok`
/// filter, maps to [Emisora], drops entries with an empty `uuid`/`url`,
/// and applies the quality sort. None of this belongs in transport — see
/// [_getJson]'s doc comment.
Future<List<Emisora>> _get(String path, Map<String, String> params) async {
final lista = await _getJson(path, {'lastcheckok': '1', ...params});
final emisoras =
lista
.cast<Map<String, dynamic>>()
.map(Emisora.fromApi)
.where((e) => e.uuid.isNotEmpty && e.url.isNotEmpty)
.toList();
emisoras.sort(_compararCalidad);
return emisoras;
}
/// Emisoras más votadas globalmente.
Future<List<Emisora>> obtenerPopulares({
int limit = 30,
@@ -301,6 +326,34 @@ class ServicioRadio {
});
}
/// Países disponibles vía `/json/countries` (station-discovery-browse
/// spec — "Países Browser Over the Verified Countries Contract").
///
/// Deliberately reuses [_getJson], never [_get]:
/// - **No `lastcheckok`.** That filter is station-only and meaningless on
/// a countries listing — sending it would be the whole bug this
/// extraction exists to avoid (Engram id 2500).
/// - **No `order` parameter.** Not because the endpoint default is
/// convenient, but because the screen sorts client-side by name anyway:
/// the API orders by raw byte order, which is not proper collation for
/// any locale this app ships (Engram id 2505's client-side-sort
/// reasoning applies here too).
/// - `hidebroken=true` is still applied (inherited from `_uri`, unchanged)
/// — the endpoint's own default is `false`, so this keeps dead stations
/// out of the per-country counts, which is desirable, not a station-only
/// concern.
///
/// The `.where(...)` guard mirrors `_get`'s own precedent of dropping
/// entries with empty required fields — not a claim about API behaviour.
Future<List<PaisRadio>> obtenerPaises() async {
final lista = await _getJson('/json/countries', const {});
return lista
.whereType<Map<String, dynamic>>()
.map(PaisRadio.fromApi)
.where((p) => p.nombre.isNotEmpty && p.codigoIso.length == 2)
.toList();
}
int _compararCalidad(Emisora a, Emisora b) {
final bitrateA = a.bitrate ?? 0;
final bitrateB = b.bitrate ?? 0;