refactor(provider): extract gnews adapter

Author: AlisinaDevelo

CHANGELOG.md

@@ -22,6 +22,10 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 - Docker healthcheck now honors the runtime `PORT` environment variable.
 - Versioned `/api/v1/*` endpoints with `{ data, meta }` response envelopes, cache metadata, and structured error bodies.
 
+### Changed
+
+- Split GNews-specific provider mapping and payload validation into a provider adapter, leaving the news service focused on cache/search orchestration.
+
 ### Security
 
 - Refreshed the dependency lockfile and upgraded OpenTelemetry packages; `npm audit --omit=dev` reports zero vulnerabilities.

README.md

@@ -146,7 +146,8 @@ Legacy errors: `{ "error": "message" }`. Versioned `/api/v1/*` errors: `{ "error
 - `src/http/responses.ts` — Versioned response envelope helpers.
 - `src/cache/store.ts` — Pluggable cache: memory or Redis.
 - `src/metrics/register.ts` — Prometheus registry: HTTP, cache, and upstream provider metrics.
-- `src/services/newsService.ts` — GNews client, normalized cache keys, cache resilience/coalescing, timeouts, upstream instrumentation.
+- `src/providers/gnewsProvider.ts` — GNews adapter: provider params, payload validation, timeouts, upstream instrumentation.
+- `src/services/newsService.ts` — Article search orchestration: normalized cache keys, cache resilience/coalescing, title/source narrowing.
 - `test/` — Vitest; HTTP tests mock `axios` (no live GNews in CI).
 
 Architecture diagram: [docs/ARCHITECTURE.md](docs/ARCHITECTURE.md). Release notes: [CHANGELOG.md](CHANGELOG.md).

docs/ARCHITECTURE.md

@@ -9,13 +9,14 @@ flowchart LR
   Routes --> Controllers
   Controllers --> NewsService
   NewsService --> Cache
-  NewsService --> GNews["GNews API"]
+  NewsService --> Provider["GNews provider adapter"]
+  Provider --> GNews["GNews API"]
 ```
 
 1. **Process** — `dotenv` loads first; **`otel-bootstrap`** starts OpenTelemetry when an OTLP endpoint (or `OTEL_TRACING_ENABLED=1`) is configured, before Express loads so HTTP is instrumented.
 2. **Express** (`src/app.ts`) applies middleware in order: trust-proxy (optional), **Pino** request logging, **metrics** observer, **Helmet**, JSON body parser, **rate limiting** (skips `/health`, `/ready`, `/openapi.yaml`, `/metrics`), then mounts `/api` routes.
 3. **Controllers** validate query parameters and map domain results to HTTP status codes.
-4. **News service** builds cache keys from normalized search parameters (`query`, `count`, `lang`, `country`, `from`, `to`, `sortBy`), reads through `getCacheStore()` (in-memory or **Redis** when `REDIS_URL` is set), coalesces identical in-flight misses per process, and otherwise calls GNews `/api/v4/search` via `axios`. Cache backend errors are logged and metriced without failing the article request.
+4. **News service** builds cache keys from normalized search parameters (`query`, `count`, `lang`, `country`, `from`, `to`, `sortBy`), reads through `getCacheStore()` (in-memory or **Redis** when `REDIS_URL` is set), coalesces identical in-flight misses per process, and delegates upstream fetches to the GNews provider adapter. Cache backend errors are logged and metriced without failing the article request.
 5. **Response mapping** keeps legacy `/api/articles*` endpoints backward compatible with raw arrays, while `/api/v1/*` returns `{ data, meta }` envelopes with `requestId`, normalized filters, and cache status.
 6. **Title** and **source** endpoints reuse the search call, then narrow results in memory (exact title match; case-insensitive source name match).
 
@@ -41,8 +42,8 @@ sequenceDiagram
     Cache-->>Svc: articles
   else miss (read fail falls through here too)
     Svc->>Svc: coalesce identical in-flight misses
-    Svc->>GNews: GET /api/v4/search (timeout)
-    GNews-->>Svc: articles  (502 on provider/transport error)
+    Svc->>GNews: provider adapter: GET /api/v4/search (timeout)
+    GNews-->>Svc: normalized articles  (502 on provider/transport error)
     Svc->>Cache: set(key, articles, TTL 600s)
   end
   Svc-->>API: articles

src/providers/gnewsProvider.ts

@@ -0,0 +1,68 @@
+import axios from "axios";
+import { UPSTREAM_BASE_URL, UPSTREAM_TIMEOUT_MS } from "../config/upstream";
+import { HttpError } from "../errors/HttpError";
+import {
+  upstreamRequestDurationSeconds,
+  upstreamRequestsTotal,
+} from "../metrics/register";
+import { Article } from "../types/article";
+import { ArticleSearchOptions } from "../types/search";
+
+export interface NewsProvider {
+  search(options: ArticleSearchOptions): Promise<Article[]>;
+}
+
+function normalizeArticles(data: unknown): Article[] {
+  if (
+    data === null ||
+    typeof data !== "object" ||
+    !("articles" in data) ||
+    !Array.isArray((data as { articles: unknown }).articles)
+  ) {
+    throw new HttpError(502, "Invalid response from news provider", "invalid_provider_payload");
+  }
+  return (data as { articles: Article[] }).articles;
+}
+
+function toProviderParams(options: ArticleSearchOptions): Record<string, string | number | undefined> {
+  return {
+    q: options.query,
+    max: options.count,
+    token: process.env.GNEWS_API_KEY,
+    lang: options.lang,
+    country: options.country,
+    from: options.from,
+    to: options.to,
+    sortby: options.sortBy,
+  };
+}
+
+export class GNewsProvider implements NewsProvider {
+  async search(options: ArticleSearchOptions): Promise<Article[]> {
+    const stopUpstreamTimer = upstreamRequestDurationSeconds.startTimer();
+
+    try {
+      const response = await axios.get<{ articles: Article[] }>(`${UPSTREAM_BASE_URL}/search`, {
+        params: toProviderParams(options),
+        timeout: UPSTREAM_TIMEOUT_MS,
+        validateStatus: (s) => s >= 200 && s < 300,
+      });
+
+      const articles = normalizeArticles(response.data);
+      upstreamRequestsTotal.inc({ outcome: "success" });
+      stopUpstreamTimer({ outcome: "success" });
+      return articles;
+    } catch (err) {
+      const outcome =
+        err instanceof HttpError && err.statusCode === 502 ? "invalid_payload" : "error";
+      upstreamRequestsTotal.inc({ outcome });
+      stopUpstreamTimer({ outcome });
+      if (axios.isAxiosError(err)) {
+        throw new HttpError(502, "Upstream news service unavailable", "upstream_unavailable");
+      }
+      throw err;
+    }
+  }
+}
+
+export const newsProvider: NewsProvider = new GNewsProvider();

src/services/newsService.ts

@@ -1,18 +1,10 @@
-import axios from "axios";
 import { Article } from "../types/article";
-import { HttpError } from "../errors/HttpError";
 import { CacheStore, getCacheStore } from "../cache/store";
-import { UPSTREAM_BASE_URL, UPSTREAM_TIMEOUT_MS } from "../config/upstream";
 import { ArticleSearchFilters, ArticleSearchOptions } from "../types/search";
-import {
-  cacheErrorsTotal,
-  cacheEventsTotal,
-  upstreamRequestDurationSeconds,
-  upstreamRequestsTotal,
-} from "../metrics/register";
+import { cacheErrorsTotal, cacheEventsTotal } from "../metrics/register";
 import { logger } from "../logger";
+import { newsProvider } from "../providers/gnewsProvider";
 
-const API_KEY = process.env.GNEWS_API_KEY;
 const inFlightSearches = new Map<string, Promise<ArticleSearchResult>>();
 
 export type ArticleSearchCacheStatus = "hit" | "miss" | "coalesced";
@@ -22,18 +14,6 @@ export interface ArticleSearchResult {
   cache: ArticleSearchCacheStatus;
 }
 
-function normalizeArticles(data: unknown): Article[] {
-  if (
-    data === null ||
-    typeof data !== "object" ||
-    !("articles" in data) ||
-    !Array.isArray((data as { articles: unknown }).articles)
-  ) {
-    throw new HttpError(502, "Invalid response from news provider", "invalid_provider_payload");
-  }
-  return (data as { articles: Article[] }).articles;
-}
-
 function searchCacheKey(options: ArticleSearchOptions): string {
   return JSON.stringify({
     query: options.query,
@@ -46,19 +26,6 @@ function searchCacheKey(options: ArticleSearchOptions): string {
   });
 }
 
-function toProviderParams(options: ArticleSearchOptions): Record<string, string | number | undefined> {
-  return {
-    q: options.query,
-    max: options.count,
-    token: API_KEY,
-    lang: options.lang,
-    country: options.country,
-    from: options.from,
-    to: options.to,
-    sortby: options.sortBy,
-  };
-}
-
 async function readCachedArticles(
   store: CacheStore,
   cacheKey: string
@@ -98,29 +65,7 @@ async function fetchArticlesFromUpstream(
   store: CacheStore,
   cacheKey: string
 ): Promise<ArticleSearchResult> {
-  const stopUpstreamTimer = upstreamRequestDurationSeconds.startTimer();
-  let articles: Article[];
-  try {
-    const response = await axios.get<{ articles: Article[] }>(`${UPSTREAM_BASE_URL}/search`, {
-      params: toProviderParams(options),
-      timeout: UPSTREAM_TIMEOUT_MS,
-      validateStatus: (s) => s >= 200 && s < 300,
-    });
-
-    articles = normalizeArticles(response.data);
-    upstreamRequestsTotal.inc({ outcome: "success" });
-    stopUpstreamTimer({ outcome: "success" });
-  } catch (err) {
-    const outcome =
-      err instanceof HttpError && err.statusCode === 502 ? "invalid_payload" : "error";
-    upstreamRequestsTotal.inc({ outcome });
-    stopUpstreamTimer({ outcome });
-    if (axios.isAxiosError(err)) {
-      throw new HttpError(502, "Upstream news service unavailable", "upstream_unavailable");
-    }
-    throw err;
-  }
-
+  const articles = await newsProvider.search(options);
   await writeCachedArticles(store, cacheKey, articles);
   return { articles, cache: "miss" };
 }