64 lines
2.7 KiB
Markdown
64 lines
2.7 KiB
Markdown
## Purpose
|
|
|
|
Canonical specification for image-provider-fallback-chain requirements synced from OpenSpec change deltas.
|
|
|
|
## Requirements
|
|
|
|
### Requirement: Configurable provider priority
|
|
The system SHALL support configuring image provider order via `ROYALTY_IMAGE_PROVIDERS` environment variable.
|
|
|
|
#### Scenario: Custom provider order
|
|
- **WHEN** `ROYALTY_IMAGE_PROVIDERS=unsplash,pexels,pixabay,wikimedia,picsum`
|
|
- **THEN** system tries providers in order: Unsplash → Pexels → Pixabay → Wikimedia → Picsum
|
|
|
|
#### Scenario: Default provider order
|
|
- **WHEN** `ROYALTY_IMAGE_PROVIDERS` is not set or empty
|
|
- **THEN** system uses default order: `pixabay,unsplash,pexels,wikimedia,picsum`
|
|
|
|
#### Scenario: Single provider configured
|
|
- **WHEN** `ROYALTY_IMAGE_PROVIDERS=pexels`
|
|
- **THEN** system only tries Pexels provider
|
|
- **AND** returns `(None, None)` if Pexels fails or is not configured
|
|
|
|
### Requirement: Sequential fallback execution
|
|
The system SHALL try providers sequentially until one returns a valid image.
|
|
|
|
#### Scenario: First provider succeeds
|
|
- **WHEN** provider chain is `pixabay,unsplash,pexels` AND Pixabay returns valid image
|
|
- **THEN** system returns Pixabay image immediately
|
|
- **AND** does NOT call Unsplash or Pexels APIs
|
|
|
|
#### Scenario: First provider fails, second succeeds
|
|
- **WHEN** provider chain is `pixabay,unsplash,pexels` AND Pixabay returns no results AND Unsplash returns valid image
|
|
- **THEN** system returns Unsplash image
|
|
- **AND** does NOT call Pexels API
|
|
|
|
#### Scenario: All providers fail
|
|
- **WHEN** all configured providers return `(None, None)`
|
|
- **THEN** system returns `(None, None)` as final result
|
|
- **AND** caller handles fallback to article image or placeholder
|
|
|
|
### Requirement: MCP endpoint override
|
|
The existing `ROYALTY_IMAGE_MCP_ENDPOINT` SHALL take priority over the provider chain when configured.
|
|
|
|
#### Scenario: MCP endpoint configured
|
|
- **WHEN** `ROYALTY_IMAGE_MCP_ENDPOINT` is set to valid URL
|
|
- **THEN** system tries MCP endpoint first before provider chain
|
|
- **AND** falls back to provider chain only if MCP endpoint fails
|
|
|
|
#### Scenario: MCP endpoint not configured
|
|
- **WHEN** `ROYALTY_IMAGE_MCP_ENDPOINT` is empty or unset
|
|
- **THEN** system skips MCP endpoint and proceeds directly to provider chain
|
|
|
|
### Requirement: Provider skip on missing credentials
|
|
Providers without required API keys SHALL be skipped silently.
|
|
|
|
#### Scenario: Skip unconfigured provider
|
|
- **WHEN** provider chain includes `pixabay` AND `PIXABAY_API_KEY` is not set
|
|
- **THEN** Pixabay is skipped without error
|
|
- **AND** chain continues to next provider
|
|
|
|
#### Scenario: All providers skipped
|
|
- **WHEN** no providers in chain have valid API keys configured
|
|
- **THEN** system falls back to Wikimedia (no key required) or Picsum (always available)
|