1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
|
# SPDX-FileCopyrightText: 2026 Dennis Fink <me+coding@dennisfink.me>
#
# SPDX-License-Identifier: BSD-3-Clause
"""Incoming Webmention state and persistence."""
from datetime import UTC, datetime
from enum import StrEnum
from uuid import UUID
from sqlalchemy import (
DateTime,
Enum,
Index,
Integer,
String,
Text,
UniqueConstraint,
Uuid,
)
from sqlalchemy.orm import Mapped, mapped_column, validates
from ..extensions import Base
from .utils import source_target_digest, uuid7_to_datetime
class ReceivedWebmentionStatus(StrEnum):
"""Persisted lifecycle state of an incoming Webmention."""
RECEIVED = "received"
VERIFYING = "verifying"
VERIFIED = "verified"
FAILED = "failed"
SOURCE_REMOVED = "source_removed"
class ReceivedWebmention(Base):
"""Represent a Webmention received for verification."""
__tablename__ = "received_webmentions"
uuid: Mapped[UUID] = mapped_column(Uuid(as_uuid=True), primary_key=True)
source: Mapped[str] = mapped_column(Text(), nullable=False)
target: Mapped[str] = mapped_column(Text(), nullable=False)
source_target_digest: Mapped[str] = mapped_column(String(64), nullable=False)
@validates("source", "target")
def _refresh_url_digest(self, key: str, value: str) -> str:
source = value if key == "source" else self.__dict__.get("source")
target = value if key == "target" else self.__dict__.get("target")
if source is not None and target is not None:
self.source_target_digest = source_target_digest(source, target)
return value
status: Mapped[ReceivedWebmentionStatus] = mapped_column(
Enum(
ReceivedWebmentionStatus,
name="received_webmention_status",
values_callable=lambda enum_type: [member.value for member in enum_type],
native_enum=False,
),
nullable=False,
default=ReceivedWebmentionStatus.RECEIVED,
)
# Counts stale-row requeues, not Huey's bounded in-task retries. A fresh
# explicit submission resets this counter.
recovery_attempts: Mapped[int] = mapped_column(
Integer, nullable=False, default=0, server_default="0"
)
failure_reason: Mapped[str | None] = mapped_column(
Text(), nullable=True, default=None
)
updated_at: Mapped[datetime] = mapped_column(
DateTime(timezone=True),
default=lambda: datetime.now(UTC),
onupdate=lambda: datetime.now(UTC),
nullable=False,
)
notification_sent_at: Mapped[datetime | None] = mapped_column(
DateTime(timezone=True), nullable=True, default=None
)
__table_args__ = (
UniqueConstraint(
"source_target_digest", name="uq_webmention_source_target_digest"
),
Index("ix_received_webmentions_status_updated_at", "status", "updated_at"),
)
def __repr__(self) -> str:
"""Represent the received Webmention by source and target."""
return f"<ReceivedWebmention {self.source!r} -> {self.target!r}>"
@staticmethod
def reopen_verification_values(
*, at: datetime, recovery_attempts: int = 0
) -> dict[str, object]:
"""Return the columns to reset when verification is explicitly reopened.
:param at: Timestamp to record for the newly opened verification.
:param recovery_attempts: Number of stale-lease recovery attempts to retain.
:returns: Column values for resetting the verification state.
"""
return {
"status": ReceivedWebmentionStatus.RECEIVED,
"failure_reason": None,
"recovery_attempts": recovery_attempts,
"updated_at": at,
}
def reopen_verification(self) -> None:
"""Reopen an existing row for manual verification.
Clear the previous outcome and restore the received state with a fresh
timestamp.
"""
for key, value in self.reopen_verification_values(at=datetime.now(UTC)).items():
setattr(self, key, value)
@property
def verified(self) -> bool:
"""Return whether the Webmention has been successfully verified."""
return self.status == ReceivedWebmentionStatus.VERIFIED
@property
def created_at(self) -> datetime:
"""Return the creation time encoded in the Webmention UUID."""
return uuid7_to_datetime(self.uuid)
|