Server-Teil: Resolver, Fetcher und Jobs

Der Server-Teil einer App ist ein Modul aus Klassen, die die Plattform beim Start in einen eigenen Container lädt. Drei Decorator machen daraus Verhalten — @WidgetResolver, @Fetcher und @JobHandler —, und alles, was der Server-Teil von der Plattform braucht, bezieht er über Token. Diese Seite nennt die Verträge, Regeln und Grenzwerte.

Was der Server-Teil ist#

Nur Daten-Apps exportieren einen Server-Teil; Apps ohne Verhalten lassen ihn weg, statt ein leeres Modul zu pflegen. Die Plattform importiert das Modul nicht, sondern hebt seine Klassen in einen Container je App, in dem die Token gebunden sind. Eigene Routen des Server-Teils liegen unter /v1/apps/<id>/…. Zwei Apps können sich nie gegenseitig Klassen injizieren; ein Server-Teil sieht nur die Fläche des SDK.

Alle drei Decorator hinterlegen nur eine Markierung an der Klasse. Die Plattform liest sie beim Start, registriert Resolver, legt Worker für Fetcher und Jobs an und verdrahtet sie mit dem Snapshot-Bau. Je Klasse gilt genau eine Markierung je Sorte. Die Klasse trägt zusätzlich die Injektions-Markierungen des Plattform-Containers (@Injectable an der Klasse, @Inject(Token) an jedem Konstruktor-Parameter) — ohne sie kann der Container die Klasse nicht erzeugen.

@WidgetResolver#

Je Widget-Typ registriert eine App genau einen Resolver. Beim Snapshot-Bau ruft die Plattform resolve(ctx) mit der bereits validierten Konfiguration und erhält eine render-fertige Nutzlast — oder null.

Der Resolver der Wetter-App, gekürzt um Fehlerbehandlung und Zeitfenster-Rechnung. Er ruft die Quelle nie selbst: Er bestimmt den Ort (fest gewählt oder der Standort des Displays aus ctx.location), liest über den Fetcher-Cache (APP_FETCHER_CACHE) und reicht den Fetcher nur als Lader für den Fehltreffer hinein.

// gekürzt — ohne Fehlerprotokoll und Zeitfenster-Rechnung
@WidgetResolver({ widgetType: 'weather' })
@Injectable()
export class WeatherResolver implements IWidgetResolver<ResolvedWeatherData> {
  readonly widgetType = 'weather';

  constructor(
    @Inject(APP_FETCHER_CACHE) private readonly cache: AppFetcherCache,
    @Inject(APP_TENANT_DATA) private readonly tenant: AppTenantData,
    @Inject(APP_CLOCK) private readonly clock: AppClock,
    @Inject(APP_LOGGER) private readonly log: AppLogger,
    private readonly fetcher: WeatherFetcherService,
  ) {}

  async resolve(ctx: WidgetResolverContext): Promise<ResolvedWidgetPayload<ResolvedWeatherData> | null> {
    const parsed = WeatherConfigSchema.safeParse(ctx.config);
    if (!parsed.success) {
      // Autoren-Zustand — kein Betriebsfehler: das Widget zeigt seinen Hinweis.
      this.log.debug({ widgetInstanceId: ctx.widgetInstanceId }, 'weather.resolve.invalid-config');
      return null;
    }
    const config = parsed.data;
    // Fester Ort, Standort des Displays oder Ersatzort; ohne Ort still `null`.
    const place = resolveWeatherPlace(config.location, ctx.location);
    if (!place) return null;

    const tenant = await this.tenant.profile(ctx.tenantId);
    const locale = tenant?.defaultLocale ?? 'de-DE';
    const citySlug = computeCitySlug(place.latitude, place.longitude, place.countryCode);
    const ttlMs = WEATHER_VALIDITY_MS;
    const staleWindowMs = 3 * ttlMs;

    const { data: snapshot, cached, cachedAt } = await this.cache.getOrFetch<WeatherSnapshot>(
      WeatherFetcherService.fetchKey(citySlug),
      async () => {
        const result = await this.fetcher.fetchWeather({
          citySlug,
          latitude: place.latitude,
          longitude: place.longitude,
          locale,
        });
        return result.payload;
      },
      { ttl: ttlMs, staleWindow: staleWindowMs },
    );

    const anchor = cached && cachedAt ? cachedAt : this.clock.now();
    return {
      payload: mapToResolved(snapshot, place, config.units),
      source: cached ? `cache:api:${snapshot.provider}` : `api:${snapshot.provider}`,
      resolvedAt: this.clock.now(),
      ...zeitzusagen(anchor, ttlMs, staleWindowMs, this.clock.now()),
    };
  }
}

Zwei Details aus der ungekürzten Fassung: Ein Fehler des Anbieters oder der Infrastruktur wird als weather.resolve.failed protokolliert und weitergeworfen, damit der Snapshot-Bau ihn als Resolver-Fehler ausweist statt als „kein Ergebnis“. Und bei einem Cache-Treffer verankern die Zeitfenster am ursprünglichen Abrufzeitpunkt (cachedAt), nicht an „jetzt“ — zeitzusagen aus @szenera/apps-sdk/backend rechnet validUntil und cacheUntil daraus.

Der Kontext (WidgetResolverContext):

Die Antwort (ResolvedWidgetPayload): payload, source, resolvedAt, validUntil, cacheUntil. Die beiden Zeitpunkte wandern in den Snapshot und steuern, wann die Plattform neu rechnet. Der Snapshot gilt bis zum frühesten validUntil seiner Widgets, und genau dann baut die Plattform ihn neu. Ein Resolver, dessen Anzeige zu einem bekannten Zeitpunkt wechselt (ein Dienstfenster endet, ausverkauft gilt bis 5 Uhr, eine Karte ab einem Stichtag), setzt validUntil auf diesen Zeitpunkt. Liegt er weniger als 30 Sekunden voraus, fängt ihn der Durchlauf alle fünf Minuten auf.

Die Regeln:

Beim Start prüft die Plattform, dass jeder registrierte Widget-Typ im Manifest steht, keine zwei Resolver denselben Typ beanspruchen und jedes Widget mit noResolver: false einen Resolver hat.

@Fetcher#

@Fetcher markiert eine Methode, die eine fremde Quelle abruft. Die Plattform legt dafür einen eigenen Worker an, der genau einen Lauf gleichzeitig ausführt, damit begrenzte fremde Quellen geschont bleiben.

Die Methode gibt FetcherResult<TPayload> zurück: payload, validUntil, cacheUntil und source (Herkunft, z. B. api:openweather).

@Fetcher({ key: 'weather:{citySlug}', defaultValidity: 'PT30M', defaultCacheUntil: 'PT2H' })
async fetchWeather(args: FetchArgs): Promise<FetcherResult<WeatherSnapshot>> {
  const snapshot = await this.router.fetch(args);
  const now = this.clock.now();
  return {
    payload: snapshot,
    validUntil: new Date(now.getTime() + 30 * 60 * 1000),
    cacheUntil: new Date(now.getTime() + 2 * 60 * 60 * 1000),
    source: `api:${snapshot.provider}`,
  };
}

Geplante Läufe und das Auffrischen über die API rufen eine Fetcher-Methode ohne Argumente auf. Deklariert sie Pflichtparameter, führt die Plattform sie als reinen Cache-Lader: geplante Läufe und Auffrischen lehnen sie ab, aufgerufen wird sie nur von der App selbst — aus getOrFetch im Resolver oder aus einem Job, der die Argumente kennt. Periodisches Abrufen ist deshalb Sache eines @JobHandler.

getOrFetch prüft auf jedem Weg, auch beim Treffer im Cache, ob die Organisation die App aktiv installiert hat; sonst antwortet die Plattform mit App.NotInstalled (HTTP 409). Die beiden Zeitfenster ergeben drei Lagen:

Scheitert die Auffrischung, bleibt der gespeicherte Eintrag bis cacheUntil unangetastet — eine gestörte Quelle nimmt dem Bildschirm nicht auch das Bild.

@JobHandler#

@JobHandler markiert eine Methode als wiederkehrenden, plattformweiten Job. Die Plattform legt einen Zeitplan an, den ein Cron abarbeitet, und ruft die Methode ohne Organisation im Kontext auf; der Handler fächert selbst über die installierten Organisationen.

Die Organisationen liefert listTenantsForApp() am Job-Queue-Token — nur die mit aktiver Installation dieser App; eine fremde App lässt sich nicht aufzählen. Ein key, der bereits als Fetcher registriert ist, wird mit Warnung übersprungen.

Die Token#

Der Server-Teil bezieht jede übergreifende Fähigkeit über ein Token; die Plattform bindet dahinter eine Umsetzung, die alles automatisch mit der App-Kennung abgrenzt. Drei Token tragen Kontext, die übrigen Dienste.

AppGuardedFetch ist Pflicht für Nutzeradressen#

Sobald ein Server-Teil eine Adresse abruft, die jemand im Portal eingetragen hat (Feed, Kalender, Nachrichtenquelle aus einer Widget-Konfiguration), muss er fetchText nehmen — nie das globale fetch. Der Guard lässt nur http: und https: durch, prüft alle aufgelösten Adressen gegen die Sperrliste privater und reservierter Bereiche, wiederholt die Prüfung bei jeder Weiterleitung, kappt die Antwort im Strom und erzwingt ein Zeitlimit. Vorgaben: timeoutMs: 10000, maxBytes: 2097152 (2 MiB), maxRedirects: 3.

Jeder Fehlschlag trägt einen maschinenlesbaren reason: invalid-url, blocked-scheme, blocked-address, dns-failure, too-many-redirects, too-large, timeout, http-error, network-error. isGuardedFetchError erkennt ihn strukturell, sodass ein Resolver den Grund als Klartext in seine Nutzlast heben kann. Für einen fest im Code verdrahteten Anbieter (etwa die Wetter-API) ist der Guard nicht gedacht — dort wählt keine Nutzereingabe das Ziel.

Geänderte Daten an die Displays melden#

Ändert sich etwas, das ein Widget schon zeigt, meldet der Server-Teil das mit contentChanged. Die Plattform baut dann die Displays der Organisation neu, deren Programm die App enthält, und stößt die an, deren Inhalt sich wirklich geändert hat. Die Displays zeigen die Änderung nach wenigen Sekunden. Ohne Meldung kommt sie erst an, wenn der Snapshot aus einem anderen Grund neu entsteht, im schlimmsten Fall nach Stunden.

await this.prisma.$transaction(async (tx) => {
  await (tx as MyPrismaClient).dish.update({ where: { id }, data: { soldOut: true } });
  await this.events.contentChanged(tx, { tenantId });
});

Ein Neubau mit unverändertem Inhalt stößt kein Display an, eine Meldung zu viel kostet also wenig. Eine fehlende kostet eine veraltete Anzeige. emit(tx, 'content.changed', …) nimmt denselben Weg wie contentChanged. Im Test zeichnet createMockAppContainer die Meldung in emittedEvents auf.

Installieren und Deinstallieren: die Lebenszyklus-Punkte#

Eine mit @AppLifecycle() markierte Klasse des Server-Teils darf onInstall(tenantId) und onUninstall(tenantId) tragen — höchstens eine Klasse je App, und beide Punkte müssen idempotent sein, weil eine Neuinstallation ihren Bestand wieder vorfindet. Wirft onInstall, gilt die Installation als gescheitert und die Organisation sieht den Fehler. Wirft onUninstall, bleibt die Deinstallation wirksam und der Fehler landet im Protokoll.

Ohne laufende Plattform testen#

createMockAppContainer aus @szenera/apps-sdk/testing liefert je Token eine In-Memory-Umsetzung samt Aufzeichnung; mockWidgetResolverContext baut einen synthetischen Kontext, zunächst ohne location. Eine App mit player-location setzt ihn mit mockWidgetLocation() oder null.

import { createMockAppContainer, mockWidgetResolverContext } from '@szenera/apps-sdk/testing';
import { APP_CLOCK, APP_FETCHER_CACHE, APP_LOGGER, APP_TENANT_DATA } from '@szenera/apps-sdk/backend';

const c = createMockAppContainer({
  appId: 'weather',
  clockNow: new Date('2026-06-23T00:00:00Z'),
  tenantMock: { id: 'tnt_a', slug: 'apo', displayName: 'Apo', defaultLocale: 'en-US', defaultTimezone: 'Europe/Berlin' },
});

// Eigene Klassen der App (hier der Fetcher) kommen als Stummel von Hand.
const resolver = new WeatherResolver(
  c.get(APP_FETCHER_CACHE),
  c.get(APP_TENANT_DATA),
  c.get(APP_CLOCK),
  c.get(APP_LOGGER),
  fetcherStub,
);
const result = await resolver.resolve(mockWidgetResolverContext({ widgetType: 'weather' }));
expect(c.emittedEvents).toEqual([]);

Weiterführendes#

• Datenzugriff, Rechte und Bedingungen — was dataAccess.reads an APP_TENANT_DATA bindet.
• Widget, Konfiguration und Vorschau — das Widget, das der Resolver bedient.
• Die Beispiel-Apps — welche App welche Bausteine trägt.