Skip to content

DownlinkSlotRepository

Repository responsible for persistence and lifecycle management of downlink slots.

Responsibilities

  • Create slot records
  • Track ACTIVE/PENDING/DONE/MISSED lifecycle
  • Claim active slots
  • Query historical and future slots

API Reference

This class is for downlink_slot table required to monitor/log slots for downlink raw images, as and when they will be available.

create_indexes_sql()

Query to create index for downlink_slot table for faster accessbility while filtering on status and bot_utc

create_slot(slot)

Creates the slot details to a row in the table.

:param slot: DownlinkSlot domain object :return: True only if the number of created rows is 1

create_table_sql()

Query to create downlink_slot table timestamps are stored as ISO-8601 UTC strings

delete_completed_slots()

Deletes all slots whose status is DONE. :return: Number of rows deleted

delete_slot(slot)

Deletes a slot :param slot: Slot whose identity is used for lookup :return: True only if exactly one row was delete

exists(identity)

Checks if slot exists in the DB or not

:param identity: Natural identity of a slot :return: True if slot exists. False Otherwise

get_active_slot()

Fetch latest ACTIVE slot if present.

No state mutation is performed. This method is a pure read.

:return: Active DownlinkSlot if exists, else None.

get_future_slots(downlink_start_utc, downlink_end_utc)

Fetch upcoming slots within time window (downlink_start_utc, downlink_end_utc].

A slot is considered upcoming if: - status = PENDING - bot_utc > start - bot_utc <= end

:param downlink_start_utc: starting timestamp (ISO UTC) (expected to be current timestamp) :param downlink_end_utc: Upper bound timestamp (ISO UTC) :return: List of upcoming DownlinkSlot entities ordered by bot_utc

get_next_active_slot(now)

fetch the next upcoming PENDING slot where start time is in the future.

A slot is considered: - upcoming if status = PENDING and bot_utc > now - earliest such slot will be returned

:param now: current timestamp in ISO UTC format :return: next upcoming DownlinkSlot or None if not found

get_next_claimable_slot(now)

Fetch the next eligible PENDING slot that can be activated.

A slot is considered claimable if: - its status is PENDING - its time window includes the current timestamp (bot_utc <= now <= eot_utc)

Among all eligible slots, the earliest slot (based on bot_utc) is selected to ensure deterministic and sequential processing.

This method performs a read-only operation and does not mutate state.

:param now: Current timestamp in ISO UTC format. :return: Next claimable DownlinkSlot if available, else None.

get_past_slots(downlink_start_utc, downlink_end_utc)

Fetch slots overlapping the time window [start, end], excluding future or not-yet-activated (PENDING) slots.

This method returns slots whose time window intersects with the given interval and are already ACTIVE, DONE, or MISSED. It avoids returning future scheduled (PENDING) slots.

:param downlink_start_utc: Lower bound timestamp (inclusive) in ISO UTC format. :param downlink_end_utc: upper bound timestamp (inclusive) in ISO UTC format. expected to be current timestamp, but could be anything :return: List of DownlinkSlot domain entities ordered by bot_utc.

mark_expired_active_as_missed(now)

Mark all expired ACTIVE slots as MISSED.

A slot is considered expired if its eot_utc is earlier than the provided timestamp. Only slots currently in ACTIVE state are transitioned to MISSED. This is typically used during system startup or synchronization to recover from crashes or incomplete lifecycle transitions.

This ensures that stale ACTIVE slots (which were not marked DONE due to interruptions) do not remain indefinitely ACTIVE.

:param now: Current timestamp in ISO UTC format. :return: Number of slots updated.

mark_expired_pending_as_missed(now)

Marks all expired PENDING slots as MISSED.

A slot is considered expired if its eot_utc is earlier than the provided timestamp. Only slots in PENDING state are transitioned, ensuring that ACTIVE and DONE slots are not affected.

This method is typically invoked during synchronization or scheduler initialization to clean up stale, unclaimed slots.

:param now: Current timestamp (UTC, ISO format) used as cutoff. :return: Number of rows updated (slots marked as MISSED).

update_status(newStatus, slot)

Updates slot status for a single slot, using its domain identity

:param newStatus: New status of the slot :param slot: Slot whose identity is used for lookup :return: updated slot domain entity (with updated slot) if successful