Skip to content
Open
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
4 changes: 4 additions & 0 deletions CHANGELOG.md
Original file line number Diff line number Diff line change
Expand Up @@ -7,6 +7,10 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0

## [Unreleased]

### Added

- Missing, cutoff, and upgrade settings gain `Tag Include` / `Tag Exclude` overrides; a blank one falls back to `Tag Filter · Include` / `Tag Filter · Exclude`. Schema v22 adds six columns with empty defaults. (#833)

---

## [1.13.3] - 2026-09-19
Expand Down
35 changes: 34 additions & 1 deletion src/houndarr/database.py
Original file line number Diff line number Diff line change
Expand Up @@ -16,7 +16,7 @@
# ---------------------------------------------------------------------------
# Schema version: bump when adding new migrations
# ---------------------------------------------------------------------------
SCHEMA_VERSION = 21
SCHEMA_VERSION = 22

# v20: per-instance tag-based include / exclude filter for *arr items.
# Column names are baked in here as constants so a future rename never
Expand All @@ -31,6 +31,17 @@
_V21_HOT_RETRY_WINDOW_COLUMN = "missing_hot_retry_window_hrs"
_V21_HOT_RETRY_INTERVAL_COLUMN = "missing_hot_retry_interval_hrs"

# v22: per-pass tag-filter overrides on top of the v20 instance-wide pair.
# Same version-locking discipline as v20 / v21.
_V22_TAG_FILTER_OVERRIDE_COLUMNS = (
"tag_filter_missing_include",
"tag_filter_missing_exclude",
"tag_filter_cutoff_include",
"tag_filter_cutoff_exclude",
"tag_filter_upgrade_include",
"tag_filter_upgrade_exclude",
)

# ---------------------------------------------------------------------------
# DDL
# ---------------------------------------------------------------------------
Expand Down Expand Up @@ -125,6 +136,12 @@
snapshot_refreshed_at TEXT NOT NULL DEFAULT '',
tag_filter_include TEXT NOT NULL DEFAULT '',
tag_filter_exclude TEXT NOT NULL DEFAULT '',
tag_filter_missing_include TEXT NOT NULL DEFAULT '',
tag_filter_missing_exclude TEXT NOT NULL DEFAULT '',
tag_filter_cutoff_include TEXT NOT NULL DEFAULT '',
tag_filter_cutoff_exclude TEXT NOT NULL DEFAULT '',
tag_filter_upgrade_include TEXT NOT NULL DEFAULT '',
tag_filter_upgrade_exclude TEXT NOT NULL DEFAULT '',
enabled INTEGER NOT NULL DEFAULT 1,
created_at TEXT NOT NULL DEFAULT (strftime('%Y-%m-%dT%H:%M:%fZ', 'now')),
updated_at TEXT NOT NULL DEFAULT (strftime('%Y-%m-%dT%H:%M:%fZ', 'now'))
Expand Down Expand Up @@ -364,6 +381,7 @@ async def init_db_migrations() -> None:
await _migrate_to_v19(db)
await _migrate_to_v20(db)
await _migrate_to_v21(db)
await _migrate_to_v22(db)
await _ensure_v3_indexes(db)
# PRAGMA optimize keeps the planner's sqlite_stat1 entries fresh as
# search_log grows. Cheap on healthy DBs, prevents silent index
Expand Down Expand Up @@ -427,6 +445,8 @@ async def _run_migrations(db: aiosqlite.Connection, from_version: int) -> None:
await _migrate_to_v20(db)
if from_version < 21:
await _migrate_to_v21(db)
if from_version < 22:
await _migrate_to_v22(db)

logger.info("Migrated database from schema version %d to %d", from_version, SCHEMA_VERSION)
await db.execute(
Expand Down Expand Up @@ -1497,6 +1517,19 @@ async def _migrate_to_v21(db: aiosqlite.Connection) -> None:
)


async def _migrate_to_v22(db: aiosqlite.Connection) -> None:
"""Add per-pass tag-filter override columns on the instances table.

Issue #833. Each column holds comma-separated tag labels for one
pass and direction. An empty override falls back to the v20
instance-wide column, so the empty defaults keep existing instances
filtering every pass exactly as before.
"""
for column in _V22_TAG_FILTER_OVERRIDE_COLUMNS:
if not await _column_exists(db, "instances", column):
await db.execute(f"ALTER TABLE instances ADD COLUMN {column} TEXT NOT NULL DEFAULT ''")


async def _column_exists(db: aiosqlite.Connection, table_name: str, column_name: str) -> bool:
"""Return whether *column_name* exists on *table_name*."""
async with db.execute( # nosec # nosem
Expand Down
122 changes: 70 additions & 52 deletions src/houndarr/engine/search_loop.py
Original file line number Diff line number Diff line change
Expand Up @@ -198,35 +198,55 @@ def _tag_filter_skip_reason(
return None


_TagFilterIds = tuple[frozenset[int] | None, frozenset[int] | None]


async def _resolve_tag_filter_ids(
instance: Instance,
adapter: AppAdapterProto,
*,
cycle_id: str,
cycle_trigger: CycleTrigger | str,
) -> tuple[frozenset[int] | None, frozenset[int] | None]:
"""Resolve the per-instance tag-label filter to numeric tag IDs.
) -> dict[SearchKind, _TagFilterIds]:
"""Resolve each pass's tag-label filter to numeric tag IDs.

Returns ``(include_ids, exclude_ids)`` where each side is:
Returns ``(include_ids, exclude_ids)`` for every
:class:`SearchKind`, where each side is:

- ``None`` when the operator has not enabled that direction
(empty list in settings), so the filter is a no-op for the pass.
- ``None`` when the pass has no labels for that direction (empty
per-pass override and empty instance-wide list), or when the pass
is disabled, so the filter is a no-op for the pass.
- ``None`` when the upstream ``/tag`` fetch fails: we log one info
row to ``search_log`` and degrade gracefully rather than blocking
the whole cycle on a transient *arr error.
- A possibly-empty ``frozenset[int]`` of resolved tag IDs. An
empty set for *include* means every operator-typed label was
unknown to the *arr; in that case no candidate can match.

The labels for each pass come from :meth:`TagFilterPolicy.for_pass`
(issue #833). All passes share one ``/tag`` GET, and the GET is
skipped entirely when no enabled pass has labels: a paused pass that
still carries a filter would otherwise burn one request per cycle
(and one info row on failure) for no behavioural benefit.

Labels that do not resolve against the *arr's current /tag list
are dropped silently for the cycle but recorded as an info row so
are dropped silently for the cycle but recorded as one info row so
the operator can see the typo without the loop failing on every
candidate.
"""
include = instance.tag_filter.include
exclude = instance.tag_filter.exclude
if not include and not exclude:
return None, None
pass_enabled = {
SearchKind.missing: instance.missing.missing_enabled,
SearchKind.cutoff: instance.cutoff.cutoff_enabled,
SearchKind.upgrade: instance.upgrade.upgrade_enabled,
}
pass_labels = {
kind: instance.tag_filter.for_pass(kind)
for kind, enabled in pass_enabled.items()
if enabled
}
resolved: dict[SearchKind, _TagFilterIds] = dict.fromkeys(SearchKind, (None, None))
if not any(include or exclude for include, exclude in pass_labels.values()):
return resolved

try:
async with adapter.make_client(instance) as client:
Expand All @@ -244,7 +264,7 @@ async def _resolve_tag_filter_ids(
reason="tag filter (fetch failed)",
message=message,
)
return None, None
return resolved

def _resolve(labels: tuple[str, ...]) -> tuple[frozenset[int], list[str]]:
ids: set[int] = set()
Expand All @@ -257,20 +277,22 @@ def _resolve(labels: tuple[str, ...]) -> tuple[frozenset[int], list[str]]:
ids.add(tag_id)
return frozenset(ids), unknown

include_ids: frozenset[int] | None = None
exclude_ids: frozenset[int] | None = None
all_unknown: list[str] = []
if include:
include_ids, unknown = _resolve(include)
all_unknown.extend(unknown)
if exclude:
exclude_ids, unknown = _resolve(exclude)
all_unknown.extend(unknown)
all_unknown: set[str] = set()
for kind, (include, exclude) in pass_labels.items():
include_ids: frozenset[int] | None = None
exclude_ids: frozenset[int] | None = None
if include:
include_ids, unknown = _resolve(include)
all_unknown.update(unknown)
if exclude:
exclude_ids, unknown = _resolve(exclude)
all_unknown.update(unknown)
resolved[kind] = (include_ids, exclude_ids)

if all_unknown:
message = (
f"tag filter: unknown label(s) on {instance.core.name}: "
f"{', '.join(sorted(set(all_unknown)))}"
f"{', '.join(sorted(all_unknown))}"
)
logger.info("[%s] %s", instance.core.name, message)
await _write_log(
Expand All @@ -284,7 +306,7 @@ def _resolve(labels: tuple[str, ...]) -> tuple[frozenset[int], list[str]]:
message=message,
)

return include_ids, exclude_ids
return resolved


# Download-queue check (issue #765)
Expand Down Expand Up @@ -1827,31 +1849,22 @@ async def _run_instance_search_impl(
exc_info=True,
)

# --- Tag-filter resolution (issue #637) ---
# Resolve the operator-typed labels to numeric tag IDs once at the top
# of the cycle so all three passes share one ``/tag`` GET. Falls back
# to ``(None, None)`` (filter disabled for this cycle) when the
# endpoint is unreachable; an info row in ``search_log`` records the
# fall-back so operators can debug.
#
# Skip the GET entirely when every search pass is disabled for this
# instance: a paused instance that still carries a tag-filter config
# would otherwise burn one ``/tag`` request per cycle (and one info
# row on failure) for no behavioural benefit.
any_pass_enabled = (
instance.missing.missing_enabled
or instance.cutoff.cutoff_enabled
or instance.upgrade.upgrade_enabled
# --- Tag-filter resolution (issues #637, #833) ---
# Resolve each pass's operator-typed labels to numeric tag IDs once at
# the top of the cycle so all three passes share one ``/tag`` GET.
# Falls back to ``(None, None)`` (filter disabled for this cycle) when
# the endpoint is unreachable; an info row in ``search_log`` records
# the fall-back so operators can debug. The resolver skips the GET
# when no enabled pass carries labels.
tag_filter_ids = await _resolve_tag_filter_ids(
instance,
adapter,
cycle_id=cycle_id_value,
cycle_trigger=cycle_trigger,
)
if any_pass_enabled:
tag_filter_include_ids, tag_filter_exclude_ids = await _resolve_tag_filter_ids(
instance,
adapter,
cycle_id=cycle_id_value,
cycle_trigger=cycle_trigger,
)
else:
tag_filter_include_ids, tag_filter_exclude_ids = None, None
missing_include_ids, missing_exclude_ids = tag_filter_ids[SearchKind.missing]
cutoff_include_ids, cutoff_exclude_ids = tag_filter_ids[SearchKind.cutoff]
upgrade_include_ids, upgrade_exclude_ids = tag_filter_ids[SearchKind.upgrade]

# --- Download-queue check (issue #765) ---
# One lazy lookup shared by all three passes: the *arr queue is read at
Expand Down Expand Up @@ -1891,8 +1904,8 @@ async def _run_instance_search_impl(
cycle_trigger=cycle_trigger,
start_page=instance.schedule.missing_page_offset,
total_fn=lambda: client.get_wanted_total("missing"),
tag_filter_include_ids=tag_filter_include_ids,
tag_filter_exclude_ids=tag_filter_exclude_ids,
tag_filter_include_ids=missing_include_ids,
tag_filter_exclude_ids=missing_exclude_ids,
missing_hot_retry_window_hrs=(
instance.missing.missing_hot_retry_window_hrs
),
Expand Down Expand Up @@ -1948,8 +1961,8 @@ async def _run_instance_search_impl(
cycle_trigger=cycle_trigger,
start_page=instance.schedule.cutoff_page_offset,
total_fn=lambda: cutoff_client.get_wanted_total("cutoff"),
tag_filter_include_ids=tag_filter_include_ids,
tag_filter_exclude_ids=tag_filter_exclude_ids,
tag_filter_include_ids=cutoff_include_ids,
tag_filter_exclude_ids=cutoff_exclude_ids,
in_queue_fn=in_queue_fn,
),
)
Expand Down Expand Up @@ -1987,8 +2000,8 @@ async def _run_instance_search_impl(
master_key,
cycle_id=cycle_id_value,
cycle_trigger=cycle_trigger,
tag_filter_include_ids=tag_filter_include_ids,
tag_filter_exclude_ids=tag_filter_exclude_ids,
tag_filter_include_ids=upgrade_include_ids,
tag_filter_exclude_ids=upgrade_exclude_ids,
in_queue_fn=in_queue_fn,
)
logger.info(
Expand All @@ -2010,6 +2023,11 @@ async def _run_instance_search_impl(
from houndarr.repositories.search_log import has_rows_for_cycle

if not await has_rows_for_cycle(cycle_id_value):
any_pass_enabled = (
instance.missing.missing_enabled
or instance.cutoff.cutoff_enabled
or instance.upgrade.upgrade_enabled
)
message = (
"Run now finished: no wanted items to evaluate"
if any_pass_enabled
Expand Down
32 changes: 30 additions & 2 deletions src/houndarr/repositories/instances.py
Original file line number Diff line number Diff line change
Expand Up @@ -218,6 +218,12 @@ def _row_to_instance(row: aiosqlite.Row, master_key: bytes) -> Instance:
tag_filter=TagFilterPolicy(
include=_parse_tag_labels(_optional_row_str(row, "tag_filter_include")),
exclude=_parse_tag_labels(_optional_row_str(row, "tag_filter_exclude")),
missing_include=_parse_tag_labels(_optional_row_str(row, "tag_filter_missing_include")),
missing_exclude=_parse_tag_labels(_optional_row_str(row, "tag_filter_missing_exclude")),
cutoff_include=_parse_tag_labels(_optional_row_str(row, "tag_filter_cutoff_include")),
cutoff_exclude=_parse_tag_labels(_optional_row_str(row, "tag_filter_cutoff_exclude")),
upgrade_include=_parse_tag_labels(_optional_row_str(row, "tag_filter_upgrade_include")),
upgrade_exclude=_parse_tag_labels(_optional_row_str(row, "tag_filter_upgrade_exclude")),
),
snapshot=RuntimeSnapshot(
monitored_total=_optional_row_int(row, "monitored_total"),
Expand Down Expand Up @@ -328,6 +334,13 @@ class InstanceInsert:
# Resolved to numeric tag IDs at engine-cycle time (issue #637).
tag_filter_include: str = ""
tag_filter_exclude: str = ""
# Per-pass overrides of the pair above; empty falls back to it (#833).
tag_filter_missing_include: str = ""
tag_filter_missing_exclude: str = ""
tag_filter_cutoff_include: str = ""
tag_filter_cutoff_exclude: str = ""
tag_filter_upgrade_include: str = ""
tag_filter_upgrade_exclude: str = ""


@dataclass(frozen=True, slots=True)
Expand Down Expand Up @@ -384,6 +397,12 @@ class InstanceUpdate:
search_order: SearchOrder | None = None
tag_filter_include: str | None = None
tag_filter_exclude: str | None = None
tag_filter_missing_include: str | None = None
tag_filter_missing_exclude: str | None = None
tag_filter_cutoff_include: str | None = None
tag_filter_cutoff_exclude: str | None = None
tag_filter_upgrade_include: str | None = None
tag_filter_upgrade_exclude: str | None = None
monitored_total: int | None = None
unreleased_count: int | None = None
snapshot_refreshed_at: str | None = None
Expand Down Expand Up @@ -478,10 +497,13 @@ async def insert_instance(payload: InstanceInsert, *, master_key: bytes) -> int:
upgrade_readarr_search_mode, upgrade_whisparr_v2_search_mode,
upgrade_series_window_size,
allowed_time_window, search_order,
tag_filter_include, tag_filter_exclude
tag_filter_include, tag_filter_exclude,
tag_filter_missing_include, tag_filter_missing_exclude,
tag_filter_cutoff_include, tag_filter_cutoff_exclude,
tag_filter_upgrade_include, tag_filter_upgrade_exclude
) VALUES (
?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?,
?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?
?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?
)
""",
(
Expand Down Expand Up @@ -520,6 +542,12 @@ async def insert_instance(payload: InstanceInsert, *, master_key: bytes) -> int:
payload.search_order.value,
payload.tag_filter_include,
payload.tag_filter_exclude,
payload.tag_filter_missing_include,
payload.tag_filter_missing_exclude,
payload.tag_filter_cutoff_include,
payload.tag_filter_cutoff_exclude,
payload.tag_filter_upgrade_include,
payload.tag_filter_upgrade_exclude,
),
)
await db.commit()
Expand Down
Loading
Loading