peptide-repo/prautoblogger
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

fix: migrate Runware catalog to modelSearch; failure cooldown (v0.18.3 R4)

Browse Source 
Runware retired taskType:models; all 42 daily catalog 401s come from this

deprecated endpoint. Migrated to auth+modelSearch pair per Runware's

current API. Paginator fetches up to 5 pages x 100 = 500 models, filters

client-side to io:text-to-image in capabilities[]. Uses air identifier as

model id. Cache key bumped to v2 (prautoblogger_runware_model_cache_v2)

to invalidate v1 rows that used old taskType/requiresImage shape.

Failure cooldown: sync() records prautoblogger_runware_catalog_last_failure_at

on every error path. get_models() gates re-trigger via is_in_failure_cooldown()

which reads prautoblogger_runware_catalog_failure_cooldown_seconds (default

3600s). Success clears the timestamp. Caps cascade to ~24 errors/day.

300-line rule: fetching/normalization extracted to new companion class

PRAutoBlogger_Runware_Catalog_Fetcher (class-runware-catalog-fetcher.php,

205 lines). Catalog class: 261 lines. Autoloader picks up the new file.

Tests: normalize_models against real modelSearch fixture (redacted key);

cooldown behavior (failure->active->expired); sync clears timestamp; fallback

list always served when cache empty. 328/328 PHPUnit green.

Agent-Session: prab-v0183-20260612
This commit is contained in:
peptiderepo
2026-06-12 03:33:20 +00:00
committed by peptiderepo
parent eae0239b0c
commit f0dc1c4621
5 changed files with 805 additions and 244 deletions
Download Patch File Download Diff File Expand all files Collapse all files

211
includes/providers/class-runware-catalog-fetcher.php Normal file
View File

@@ -0,0 +1,211 @@
<?php
declare(strict_types=1);
/**
* phpcs:ignore WordPress.Files.FileName.InvalidClassFileName -- class naming convention differs from WordPress standard
*
* Runware modelSearch API fetcher — handles pagination and response normalization
* for the Runware model catalog sync.
*
* Extracted from PRAutoBlogger_Runware_Model_Catalog for the 300-line rule.
* Provides two public methods consumed by the catalog class:
* - fetch_all_text_to_image(): paginates modelSearch and returns raw results.
* - normalize_models(): converts raw results to Image_Model_Registry shape.
*
* API note (2026-06-12): Runware retired taskType:models. The replacement is
* taskType:modelSearch — requires auth+modelSearch tasks, returns paginated
* results with `air` identifiers and `capabilities[]`. Text-to-image filtering
* is client-side (no server-side capability filter is available). The catalog
* has 320k+ entries (mostly community checkpoints); we cap at PAGE_CAP pages
* of PAGE_SIZE results to bound request cost while covering curated t2i models.
*
* @see class-runware-model-catalog.php — Caller; owns caching, cooldown, and fallback.
* @see class-image-model-registry.php — Consumes the normalized model shape.
*/
class PRAutoBlogger_Runware_Catalog_Fetcher {
private const RUNWARE_API_URL = 'https://api.runware.ai/v1';
private const HTTP_TIMEOUT_SEC = 30;
/**
* Maximum pages to fetch per sync cycle.
* 5 pages × 100 results = 500 models inspected.
* Curated Runware-native text-to-image models number ~50 in the first 500.
*/
private const PAGE_CAP = 5;
private const PAGE_SIZE = 100;
/**
* Fetch all text-to-image model results via paginated modelSearch calls.
*
* Issues up to PAGE_CAP requests against the Runware /v1 endpoint, each
* sending an auth task + a modelSearch task with offset/limit. Stops early
* when all available results have been fetched. Returns the raw result
* objects (unfiltered — normalize_models() applies the capability filter).
*
* @param string $api_key Decrypted Runware API key.
* @return array<int, array<string, mixed>> Raw modelSearch result objects.
* @throws \RuntimeException On HTTP error or malformed response for any page.
*/
public function fetch_all_text_to_image( string $api_key ): array {
$all_results = array();
$offset = 0;
$pages_fetched = 0;
$total = PHP_INT_MAX; // Set after first page.
do {
$page = $this->fetch_page( $api_key, $offset, self::PAGE_SIZE );
if ( empty( $page['results'] ) ) {
break;
}
$all_results = array_merge( $all_results, $page['results'] );
$total = (int) $page['totalResults'];
$offset += self::PAGE_SIZE;
++$pages_fetched;
if ( count( $all_results ) >= $total ) {
break;
}
} while ( $pages_fetched < self::PAGE_CAP );
if ( $pages_fetched >= self::PAGE_CAP && count( $all_results ) < $total ) {
PRAutoBlogger_Logger::instance()->info(
sprintf(
'Runware catalog: reached page cap (%d pages, %d models fetched of %d total). '
. 'Increase PAGE_CAP if curated models are being missed.',
self::PAGE_CAP,
count( $all_results ),
$total
),
'runware-catalog'
);
}
return $all_results;
}
/**
* Normalize raw modelSearch result objects to the Image_Model_Registry shape.
*
* Filters to models with "io:text-to-image" in capabilities[].
* Uses the `air` field as the model id (e.g. "runware:100@1").
* Uses the `comment` field as the human-readable description.
* cost_per_image is always null here — merged by the catalog class.
*
* @param array<int, array<string, mixed>> $raw_models Raw modelSearch results.
* @return array<int, array<string, mixed>> Normalized models.
*/
public function normalize_models( array $raw_models ): array {
$normalized = array();
foreach ( $raw_models as $raw ) {
if ( ! is_array( $raw ) ) {
continue;
}
$capabilities = is_array( $raw['capabilities'] ?? null ) ? $raw['capabilities'] : array();
if ( ! in_array( 'io:text-to-image', $capabilities, true ) ) {
continue;
}
$air = (string) ( $raw['air'] ?? '' );
if ( '' === $air ) {
continue;
}
$normalized[] = array(
'id' => $air,
'name' => (string) ( $raw['name'] ?? $air ),
'provider' => 'runware',
'cost_per_image' => null,
'capabilities' => array( 'image_generation' ),
'description' => (string) ( $raw['comment'] ?? '' ),
);
}
return $normalized;
}
/**
* Fetch a single page of modelSearch results.
*
* Sends [authentication, modelSearch] task pair to /v1.
* A fresh auth task is required per request per Runware's WebSocket-based
* API contract (each HTTP POST is a stateless task array).
*
* @param string $api_key Decrypted Runware API key.
* @param int $offset Pagination offset (0-based).
* @param int $limit Page size.
* @return array{results: array<int, array<string, mixed>>, totalResults: int}
* @throws \RuntimeException On HTTP error or malformed response.
*/
private function fetch_page( string $api_key, int $offset, int $limit ): array {
$payload = array(
array(
'taskType' => 'authentication',
'apiKey' => $api_key,
),
array(
'taskType' => 'modelSearch',
'taskUUID' => wp_generate_uuid4(),
'offset' => $offset,
'limit' => $limit,
),
);
$response = wp_remote_post(
self::RUNWARE_API_URL,
array(
'timeout' => self::HTTP_TIMEOUT_SEC,
'headers' => array( 'Content-Type' => 'application/json' ),
'body' => wp_json_encode( $payload ),
)
);
if ( is_wp_error( $response ) ) {
throw new \RuntimeException(
sprintf( 'Runware modelSearch unreachable: %s', $response->get_error_message() )
);
}
$status = (int) wp_remote_retrieve_response_code( $response );
if ( 200 !== $status ) {
throw new \RuntimeException(
sprintf( 'Runware modelSearch returned HTTP %d', $status )
);
}
$raw = (string) wp_remote_retrieve_body( $response );
$decoded = json_decode( $raw, true );
if ( ! is_array( $decoded ) ) {
throw new \RuntimeException( 'Runware modelSearch response is not valid JSON.' );
}
if ( isset( $decoded['errors'] ) && is_array( $decoded['errors'] ) && ! empty( $decoded['errors'] ) ) {
$first_msg = '';
if ( ! empty( $decoded['errors'][0]['message'] ) ) {
$first_msg = ': ' . (string) $decoded['errors'][0]['message'];
}
throw new \RuntimeException( 'Runware modelSearch API error' . $first_msg );
}
$data = $decoded['data'] ?? array();
if ( ! is_array( $data ) || empty( $data ) ) {
return array(
'results' => array(),
'totalResults' => 0,
);
}
$item = $data[0];
$results = is_array( $item['results'] ?? null ) ? $item['results'] : array();
$total = isset( $item['totalResults'] ) ? (int) $item['totalResults'] : 0;
return array(
'results' => $results,
'totalResults' => $total,
);
}
}

231
includes/providers/class-runware-model-catalog.php
View File

@@ -4,18 +4,30 @@ declare(strict_types=1);
/**
* phpcs:ignore WordPress.Files.FileName.InvalidClassFileName -- class naming convention differs from WordPress standard
*
* Runware model catalog sync — fetches live model list via Runware's /v1 endpoint,
* filters to text-to-image tasks, caches normalized results, and falls back to
* hardcoded list on API failure.
* Runware model catalog sync — orchestrates periodic fetching, caching, failure
* cooldown, and fallback for the Runware model list.
*
* What: Syncs Runware's model catalog periodically (daily cron + on-demand AJAX),
* caches the results in WP options, and merges pricing data from the pricing
* class when Runware's API doesn't expose it.
* What: Syncs Runware's model catalog (daily cron + on-demand AJAX), caches
* normalized results in WP options (v2 schema key — see below), merges
* pricing, and enforces a per-failure cooldown to stop admin-page-load
* cascades when the API is broken or the key is misconfigured.
* Who triggers it: Daily cron (prautoblogger_sync_runware_models), AJAX "Sync now"
* button in PRAdmin, and lazy-load via PRAutoBlogger_Image_Model_Registry.
* Dependencies: PRAutoBlogger_Logger, PRAutoBlogger_Runware_Image_Pricing,
* PRAutoBlogger_Image_Model_Registry.
* Dependencies: PRAutoBlogger_Runware_Catalog_Fetcher, PRAutoBlogger_Logger,
* PRAutoBlogger_Runware_Image_Pricing, PRAutoBlogger_Image_Model_Registry.
*
* Cache schema note: option key is prautoblogger_runware_model_cache_v2 (bumped
* from v1) to cleanly invalidate cached rows that used the old taskType:models
* response shape (taskType/requiresImage fields). The v1 option is left in place
* and will be purged by the next WP options cleanup pass.
*
* Failure cooldown: prautoblogger_runware_catalog_last_failure_at records the
* last failure timestamp. is_in_failure_cooldown() checks it against
* prautoblogger_runware_catalog_failure_cooldown_seconds (default 3600s). This
* caps errors from admin page loads to ~24/day (24h / 1h cooldown) rather than
* 40+/day from every Settings/picker page load triggering a live sync.
*
* @see class-runware-catalog-fetcher.php — Pagination + normalize (extracted for 300-line rule).
* @see class-runware-image-pricing.php — Authoritative pricing source & fallback models.
* @see admin/class-image-model-registry.php — Caller; merges Runware + OpenRouter lists.
* @see class-prautoblogger.php — Registers daily cron + AJAX hook.
@@ -23,20 +35,27 @@ declare(strict_types=1);
*/
class PRAutoBlogger_Runware_Model_Catalog {
private const RUNWARE_API_URL = 'https://api.runware.ai/v1';
private const CACHE_TTL_SECONDS = 86400;
private const HTTP_TIMEOUT_SECONDS = 30;
/**
* Fetch the Runware model catalog, normalize to the Image_Model_Registry
* shape, and write to WP options cache. Returns true on success, false on
* API failure or parse error.
* Option key for the v2 normalized model cache (air-identifier schema).
* Bumped from v1 (prautoblogger_runware_model_cache) to force re-sync.
*/
private const CACHE_OPTION = 'prautoblogger_runware_model_cache_v2';
private const CACHE_TS_OPTION = 'prautoblogger_runware_model_cache_updated_at';
private const FAILURE_TS_OPTION = 'prautoblogger_runware_catalog_last_failure_at';
private const COOLDOWN_SETTING = 'prautoblogger_runware_catalog_failure_cooldown_seconds';
private const COOLDOWN_DEFAULT = 3600;
/**
* Fetch, normalize, merge pricing, and cache the Runware model catalog.
* On success: writes cache + clears failure timestamp. Returns true.
* On failure: writes failure timestamp for cooldown. Returns false.
*
* Side effects: makes HTTP request to Runware API, writes WP options.
* Error handling: logs via PRAutoBlogger_Logger, never throws, always
* returns bool to allow fallback to cached list.
* returns bool to allow fallback to cached/hardcoded list.
*
* @return bool True on successful fetch and cache update; false on API or parse error.
* @return bool True on successful fetch and cache update; false otherwise.
*/
public function sync(): bool {
try {
@@ -49,16 +68,19 @@ class PRAutoBlogger_Runware_Model_Catalog {
return false;
}
$raw_models = $this->fetch_models_from_api( $api_key );
$fetcher = new PRAutoBlogger_Runware_Catalog_Fetcher();
$raw_models = $fetcher->fetch_all_text_to_image( $api_key );
if ( empty( $raw_models ) ) {
PRAutoBlogger_Logger::instance()->warning(
'Runware model catalog fetch returned empty list. Using cached/fallback models.',
'runware-catalog'
);
$this->record_failure();
return false;
}
$normalized = $this->normalize_models( $raw_models );
$normalized = $fetcher->normalize_models( $raw_models );
$with_pricing = $this->merge_pricing( $normalized );
if ( empty( $with_pricing ) ) {
@@ -66,11 +88,13 @@ class PRAutoBlogger_Runware_Model_Catalog {
'Runware model catalog normalization resulted in empty list. Using cached/fallback models.',
'runware-catalog'
);
$this->record_failure();
return false;
}
update_option( 'prautoblogger_runware_model_cache', $with_pricing, false );
update_option( 'prautoblogger_runware_model_cache_updated_at', time(), false );
update_option( self::CACHE_OPTION, $with_pricing, false );
update_option( self::CACHE_TS_OPTION, time(), false );
delete_option( self::FAILURE_TS_OPTION );
PRAutoBlogger_Logger::instance()->info(
sprintf( 'Runware model catalog synced: %d models cached.', count( $with_pricing ) ),
@@ -82,38 +106,37 @@ class PRAutoBlogger_Runware_Model_Catalog {
sprintf( 'Runware model catalog sync failed: %s (%s)', $e->getMessage(), get_class( $e ) ),
'runware-catalog'
);
$this->record_failure();
return false;
}
}
/**
* Get the normalized model list, with smart caching logic:
* - If cache is fresh (< 24h), return it.
* - If cache is stale or absent, trigger a sync.
* - If sync fails, return the last-known-good cache.
* - If no cache exists, return the hardcoded fallback (never empty).
* Return the normalized model list, using smart cache + fallback logic:
* fresh cache → cached; stale + not in cooldown → sync; stale cache fallback;
* no cache → hardcoded fallback (never empty).
*
* @return array<int, array<string, mixed>> Normalized model list.
*/
public function get_models(): array {
if ( ! $this->is_stale() ) {
$cached = get_option( 'prautoblogger_runware_model_cache', array() );
$cached = get_option( self::CACHE_OPTION, array() );
if ( is_array( $cached ) && ! empty( $cached ) ) {
return $cached;
}
}
if ( $this->sync() ) {
$cached = get_option( 'prautoblogger_runware_model_cache', array() );
if ( ! $this->is_in_failure_cooldown() && $this->sync() ) {
$cached = get_option( self::CACHE_OPTION, array() );
if ( is_array( $cached ) && ! empty( $cached ) ) {
return $cached;
}
}
$cached = get_option( 'prautoblogger_runware_model_cache', array() );
$cached = get_option( self::CACHE_OPTION, array() );
if ( is_array( $cached ) && ! empty( $cached ) ) {
PRAutoBlogger_Logger::instance()->info(
'Using stale Runware model cache (live sync failed).',
'Using stale Runware model cache (live sync failed or suppressed by cooldown).',
'runware-catalog'
);
return $cached;
@@ -131,12 +154,12 @@ class PRAutoBlogger_Runware_Model_Catalog {
}
/**
* Get the Unix timestamp of the last successful sync, or null if never synced.
* Unix timestamp of the last successful sync, or null if never synced.
*
* @return int|null Unix timestamp, or null if never synced.
* @return int|null
*/
public function get_last_synced_at(): ?int {
$ts = get_option( 'prautoblogger_runware_model_cache_updated_at', null );
$ts = get_option( self::CACHE_TS_OPTION, null );
if ( null === $ts ) {
return null;
}
@@ -145,9 +168,23 @@ class PRAutoBlogger_Runware_Model_Catalog {
}
/**
* Check if the cache is stale (older than 24h) or absent.
* Unix timestamp of the last sync failure, or null if no failure on record.
*
* @return bool True if cache should be refreshed; false if still fresh.
* @return int|null
*/
public function get_last_failure_at(): ?int {
$ts = get_option( self::FAILURE_TS_OPTION, null );
if ( null === $ts ) {
return null;
}
$ts = (int) $ts;
return $ts > 0 ? $ts : null;
}
/**
* Whether the cache is stale (older than 24h) or absent.
*
* @return bool True if a refresh is warranted; false if still fresh.
*/
public function is_stale(): bool {
$updated_at = $this->get_last_synced_at();
@@ -158,125 +195,53 @@ class PRAutoBlogger_Runware_Model_Catalog {
}
/**
* Fetch the raw model list from Runware's /v1 endpoint via a models task.
* Whether a sync attempt should be suppressed due to a recent failure.
*
* @param string $api_key Decrypted Runware API key.
* @return array Raw model list (may be empty).
* @throws \RuntimeException On HTTP error or malformed response.
* The cooldown window is read from prautoblogger_runware_catalog_failure_cooldown_seconds
* (default 3600s). This prevents admin-page-load cascades (40+ errors/day)
* when the API endpoint or key is broken. A successful sync clears it.
*
* @return bool True if a sync should be suppressed; false if retry is permitted.
*/
private function fetch_models_from_api( string $api_key ): array {
$body = wp_json_encode(
array(
array(
'taskType' => 'models',
'apiKey' => $api_key,
),
)
);
$response = wp_remote_post(
self::RUNWARE_API_URL,
array(
'timeout' => self::HTTP_TIMEOUT_SECONDS,
'headers' => array( 'Content-Type' => 'application/json' ),
'body' => $body,
)
);
if ( is_wp_error( $response ) ) {
throw new \RuntimeException(
sprintf( 'Runware models endpoint unreachable: %s', $response->get_error_message() )
);
public function is_in_failure_cooldown(): bool {
$last_failure = $this->get_last_failure_at();
if ( null === $last_failure ) {
return false;
}
$status = (int) wp_remote_retrieve_response_code( $response );
if ( 200 !== $status ) {
$raw = wp_remote_retrieve_body( $response );
throw new \RuntimeException(
sprintf( 'Runware models endpoint returned HTTP %d', $status )
);
$cooldown = (int) get_option( self::COOLDOWN_SETTING, self::COOLDOWN_DEFAULT );
if ( $cooldown <= 0 ) {
$cooldown = self::COOLDOWN_DEFAULT;
}
$raw = (string) wp_remote_retrieve_body( $response );
$decoded = json_decode( $raw, true );
if ( ! is_array( $decoded ) ) {
throw new \RuntimeException( 'Runware models response is not valid JSON.' );
}
if ( isset( $decoded['errors'] ) && is_array( $decoded['errors'] ) && ! empty( $decoded['errors'] ) ) {
throw new \RuntimeException( 'Runware API returned an error.' );
}
$data = $decoded['data'] ?? array();
return is_array( $data ) ? $data : array();
return ( time() - $last_failure ) < $cooldown;
}
/**
* Normalize raw Runware model objects to the PRAutoBlogger_Image_Model_Registry
* shape: id, name, provider, cost_per_image, capabilities, description.
*
* Filters to taskType='imageInference' (text-to-image only), excluding
* inpainting (imageInference + requiresImage=true), img2img, video, upscalers.
*
* @param array<int, array<string, mixed>> $raw_models Raw API response.
* @return array<int, array<string, mixed>> Normalized models.
*/
private function normalize_models( array $raw_models ): array {
$normalized = array();
foreach ( $raw_models as $raw ) {
if ( ! is_array( $raw ) ) {
continue;
}
$task_type = $raw['taskType'] ?? '';
if ( 'imageInference' !== $task_type ) {
continue;
}
if ( isset( $raw['requiresImage'] ) && true === $raw['requiresImage'] ) {
continue;
}
$model_id = (string) ( $raw['id'] ?? '' );
if ( '' === $model_id ) {
continue;
}
$normalized[] = array(
'id' => $model_id,
'name' => (string) ( $raw['name'] ?? $model_id ),
'provider' => 'runware',
'cost_per_image' => null,
'capabilities' => array( 'image_generation' ),
'description' => (string) ( $raw['description'] ?? '' ),
);
}
return $normalized;
}
/**
* Merge pricing data from PRAutoBlogger_Runware_Image_Pricing into the
* normalized catalog. Models without pricing data get cost_per_image=null.
* Merge pricing from PRAutoBlogger_Runware_Image_Pricing into normalized models.
* Models without a pricing entry get cost_per_image=null.
*
* @param array<int, array<string, mixed>> $normalized Normalized models.
* @return array<int, array<string, mixed>> Models with pricing merged.
*/
private function merge_pricing( array $normalized ): array {
$pricing_table = PRAutoBlogger_Runware_Image_Pricing::get_model_costs();
foreach ( $normalized as &$model ) {
$model_id = $model['id'] ?? '';
if ( isset( $pricing_table[ $model_id ] ) ) {
$model['cost_per_image'] = (float) $pricing_table[ $model_id ];
}
}
return $normalized;
}
/**
* Record the current time as the last sync failure timestamp.
*
* @return void
*/
private function record_failure(): void {
update_option( self::FAILURE_TS_OPTION, time(), false );
}
/**
* Get the decrypted Runware API key from settings.
*
@@ -287,12 +252,10 @@ class PRAutoBlogger_Runware_Model_Catalog {
if ( '' === $stored ) {
return '';
}
if ( PRAutoBlogger_Encryption::is_encrypted( $stored ) ) {
$decrypted = PRAutoBlogger_Encryption::decrypt( $stored );
return '' === $decrypted ? '' : $decrypted;
}
return $stored;
}
}