Links Model

🔍 Overview

The Link model represents a URL managed by Link Switcher.

A link can be:

monitored for safety (Google Safe Browsing)
blocked/unblocked
automatically switched to a backup link
optionally rotated after a configured time window

Backup links are stored as separate Link records chained via MirrorRule, which also performs traffic switching in Voluum.

📑 Fields

Field	Type	Description
`root_domain`	str	Root domain extracted from `link` (stored for fast lookups).
`domain`	str	Domain extracted from `link` (stored for fast lookups).
`link`	URLField	Full URL (max 2048).
`tag`	str	Optional label for grouping/filters (max 255).
`with_rotation`	bool	Enables rotation logic for active links.
`rotation_interval_hours`	int	Interval in hours used by the rotation monitoring task.
`status`	str	Current status (`active`/`backup`/`blocked`/`unblocked`/`ignored`).
`owner`	Foreign Key User	Owner of the link.
`created_at`	datetime	Creation timestamp.
`updated_at`	datetime	Last update timestamp.
`active_started_at`	datetime	When the link became active (used when `with_rotation=True`).
`blocked_at`	datetime	When the link was blocked.
`reason`	str	Block reason (`UNKNOWN`, `DNS_NOT_RESOLVABLE`, Google Safe Browsing threat types, etc.).
`unblocked_at`	datetime	When the link was unblocked.
`changed_by`	str	Actor identifier (`system` / username / etc.).

🔒 Chain helpers

Property	Type	Description
`next_link`	Link (optional)	The next backup link in the chain (via `MirrorRule.main_link → mirror_link`).
`prev_link`	Link (optional)	The previous link in the chain (via `MirrorRule.mirror_link → main_link`).

🧩 Methods

Method	Description
`find_owners_by_domains(domains)`	Returns `{owner -> set(domains)}` for active links matching the given domains.
`find_owners_by_root_domains(root_domains)`	Returns `{owner -> set(root_domains)}` for active links matching the given root domains.
`get_domains_map(status="active", reason_exclude=None)`	Returns `{domain -> [Link...]}` for links matching the filters.
`get_root_domains_map(status="active", reason_exclude=None)`	Returns `{root_domain -> [Link...]}` for links matching the filters.
`get_blocked_by_google_domains_map()`	Returns `{root_domain -> [owners...]}` for links blocked by Google Safe Browsing reasons.
`get_active_links_with_rotation_expired()`	Returns active links where `active_started_at + rotation_interval_hours` is in the past.
`add_next_link(link, with_rotation=False, rotation_interval_hours=24, tag=None)`	Creates a BACKUP link and attaches it as `next_link` via `MirrorRule` (tag cascades to backups when provided).
`set_active(action_by="system")`	Promotes a BACKUP link to ACTIVE (and sets `active_started_at` when rotation is enabled).
`set_block(reason, with_switch=False, action_by="system")`	Sets BLOCKED status, sends Telegram notification, optionally triggers a switch to backup.
`set_unblock(with_return_to_work=False, action_by="system")`	Sets UNBLOCKED status and optionally returns the link back to work (see notes).
`set_ignored(with_next=False, action_by="system")`	Marks the link as IGNORED (optionally for the whole chain).
`update_with_rotation(with_rotation)`	Toggles rotation on the link and propagates it to `next_link`.
`return_unblocked_to_work(action_by="system")`	Re-attaches an unblocked link back into the active/backup chain and marks the old record IGNORED.

🏷 Statuses

Status	Description
`active`	The link is currently active and in use.
`backup`	Backup link (not serving traffic yet).
`blocked`	The link is blocked and cannot be used.
`unblocked`	The link was unblocked and can be returned to work.
`ignored`	Hidden/archived record (excluded from most workflows).

🔏 Block Reasons

Reason	Description
`UNKNOWN`	Default reason when blocking without a specific cause.
`DNS_NOT_RESOLVABLE`	Domain DNS resolution failed.
`BLOCKED_BY_USER`	Manual switch to backup initiated by a user.
`ROTATION`	Rotation system replaced the active link after the configured interval.
`MALWARE`	Google Safe Browsing threat type.
`SOCIAL_ENGINEERING`	Google Safe Browsing threat type.
`UNWANTED_SOFTWARE`	Google Safe Browsing threat type.
`POTENTIALLY_HARMFUL_APPLICATION`	Google Safe Browsing threat type.
`THREAT_TYPE_UNSPECIFIED`	Google Safe Browsing threat type.

💡 Notes

tag can be provided in Admin or XLSX import and is propagated to backup links when the chain is created.
When set_block(..., with_switch=True) is used, Link Switcher tries to switch traffic to next_link using MirrorRule.switch and Voluum.
When set_unblock(with_return_to_work=True) is used, the system returns the domain back into the chain only for specific reasons (Google Safe Browsing reasons + ROTATION).