diff options
Diffstat (limited to '')
| -rw-r--r-- | webmentions_ssg/models.py | 420 |
1 files changed, 0 insertions, 420 deletions
diff --git a/webmentions_ssg/models.py b/webmentions_ssg/models.py deleted file mode 100644 index 2304788..0000000 --- a/webmentions_ssg/models.py +++ /dev/null @@ -1,420 +0,0 @@ -# SPDX-FileCopyrightText: 2026 Dennis Fink <me+coding@dennisfink.me> -# -# SPDX-License-Identifier: BSD-3-Clause - -"""Define database models for users and incoming and outgoing Webmentions.""" - -import json -from datetime import UTC, datetime -from enum import StrEnum -from hashlib import sha256 -from typing import Never -from uuid import UUID, uuid7 - -import sqlalchemy as sa -from flask_login import UserMixin -from sqlalchemy import ( - Boolean, - DateTime, - Enum, - ForeignKey, - Index, - Integer, - String, - Text, - UniqueConstraint, - Uuid, -) -from sqlalchemy.ext.hybrid import hybrid_property -from sqlalchemy.orm import Mapped, mapped_column, relationship, validates -from werkzeug.security import check_password_hash, generate_password_hash - -from .extensions import Base - - -class ReceivedWebmentionStatus(StrEnum): - """Persisted lifecycle state of an incoming Webmention.""" - - RECEIVED = "received" - VERIFYING = "verifying" - VERIFIED = "verified" - FAILED = "failed" - SOURCE_REMOVED = "source_removed" - - -class SentWebmentionStatus(StrEnum): - """Represent the outcome of a Webmention send attempt.""" - - SENT = "sent" - NO_ENDPOINT = "no_endpoint" - FAILED = "failed" - - -class User(UserMixin, Base): - """Represent an authenticated application user.""" - - __tablename__ = "users" - - id: Mapped[int] = mapped_column(primary_key=True) - username: Mapped[str] = mapped_column(Text(), index=True, unique=True) - password_hash: Mapped[str] = mapped_column(Text(), nullable=False) - - def __repr__(self) -> str: - """Represent the user by username.""" - return f"<User {self.username}>" - - @property - def password(self) -> Never: - """Prevent access to the user's plain-text password. - - :raises AttributeError: Always, because the password is write-only. - """ - raise AttributeError("Password is write-only") - - @password.setter - def password(self, password: str) -> None: - """Hash and store a new password. - - :param password: Plain-text password to hash. - """ - self.password_hash = generate_password_hash(password) - - def get_id(self) -> str: - """Bind the login session to the current stored password hash. - - Only a one-way fingerprint is placed in Flask's signed cookie, never - the password hash itself. Rehashing the password invalidates all - previously issued session identifiers without a schema change. - - :returns: Session identifier combining the user ID and password-hash - fingerprint. - """ - fingerprint = sha256(self.password_hash.encode("utf-8")).hexdigest() - return f"{self.id}:{fingerprint}" - - def check_password(self, password: str) -> bool: - """Check a plain-text password against the stored password hash. - - :param password: Plain-text password to check. - :returns: Whether the password matches the stored hash. - """ - return check_password_hash(self.password_hash, password) - - -class BlockedSource(Base): - """A source domain denied before verification or outbound fetching.""" - - __tablename__ = "blocked_sources" - - id: Mapped[int] = mapped_column(primary_key=True) - domain: Mapped[str] = mapped_column(Text(), nullable=False, unique=True) - - -class AllowedSource(Base): - """A source domain accepted when allowlist mode is enabled.""" - - __tablename__ = "allowed_sources" - - id: Mapped[int] = mapped_column(primary_key=True) - domain: Mapped[str] = mapped_column(Text(), nullable=False, unique=True) - - -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) - - -class SourceDocument(Base): - """Represent a generated source document containing outgoing Webmentions.""" - - __tablename__ = "source_documents" - - uuid: Mapped[UUID] = mapped_column( - Uuid(as_uuid=True), primary_key=True, default=uuid7 - ) - - path: Mapped[str] = mapped_column(Text(), nullable=False, unique=True) - url: Mapped[str] = mapped_column(Text(), nullable=False, unique=True) - - content_hash: Mapped[str] = mapped_column(String(32), nullable=False) - revision: Mapped[int] = mapped_column(Integer(), nullable=False, default=1) - - last_seen_at: Mapped[datetime] = mapped_column( - DateTime(timezone=True), nullable=False - ) - revised_at: Mapped[datetime] = mapped_column( - DateTime(timezone=True), nullable=False - ) - deleted_at: Mapped[datetime | None] = mapped_column( - DateTime(timezone=True), nullable=True, default=None - ) - - sent_webmentions: Mapped[list[SentWebmention]] = relationship( - back_populates="source", cascade="all, delete-orphan" - ) - - def __repr__(self) -> str: - """Represent the source by its public URL.""" - return f"<SourceDocument {self.url!r}>" - - @property - def created_at(self) -> datetime: - """Return the creation time encoded in the source UUID.""" - return uuid7_to_datetime(self.uuid) - - -class SentWebmention(Base): - """Represent an outgoing Webmention associated with a source.""" - - __tablename__ = "sent_webmentions" - - uuid: Mapped[UUID] = mapped_column( - Uuid(as_uuid=True), primary_key=True, default=uuid7 - ) - - source_uuid: Mapped[UUID] = mapped_column( - Uuid(as_uuid=True), - ForeignKey("source_documents.uuid", ondelete="CASCADE"), - nullable=False, - index=True, - ) - - target: Mapped[str] = mapped_column(Text(), nullable=False) - target_digest: Mapped[str] = mapped_column(String(64), nullable=False) - - @validates("target") - def _update_target_digest(self, key: str, value: str) -> str: - self.target_digest = target_digest(value) - return value - - linked: Mapped[bool] = mapped_column(Boolean(), nullable=False, default=True) - - desired_revision: Mapped[int] = mapped_column(Integer(), nullable=False) - processed_revision: Mapped[int | None] = mapped_column( - Integer(), nullable=True, default=None - ) - sent_revision: Mapped[int | None] = mapped_column( - Integer(), nullable=True, default=None - ) - - status: Mapped[SentWebmentionStatus | None] = mapped_column( - Enum( - SentWebmentionStatus, - name="sent_webmention_status", - values_callable=lambda enum_type: [member.value for member in enum_type], - native_enum=False, - ), - nullable=True, - default=None, - ) - - failure_reason: Mapped[str | None] = mapped_column( - Text(), nullable=True, default=None - ) - - webmention_endpoint: Mapped[str | None] = mapped_column( - Text(), nullable=True, default=None - ) - endpoint_response_status: Mapped[int | None] = mapped_column( - Integer(), nullable=True, default=None - ) - status_url: Mapped[str | None] = mapped_column(Text(), nullable=True, default=None) - - # Retry state belongs to the desired revision, not to the target forever. - attempt_count: Mapped[int] = mapped_column(Integer(), nullable=False, default=0) - next_retry_at: Mapped[datetime | None] = mapped_column( - DateTime(timezone=True), nullable=True, default=None - ) - - last_attempted_at: Mapped[datetime | None] = mapped_column( - DateTime(timezone=True), nullable=True, default=None - ) - last_sent_at: Mapped[datetime | None] = mapped_column( - DateTime(timezone=True), nullable=True, default=None - ) - - source: Mapped[SourceDocument] = relationship(back_populates="sent_webmentions") - - __table_args__ = ( - UniqueConstraint( - "source_uuid", - "target_digest", - name="uq_sent_webmention_source_uuid_target_digest", - ), - ) - - def __repr__(self) -> str: - """Represent the sent Webmention by its target URL.""" - return f"<SentWebmention {self.target!r}>" - - def reset_for_revision(self, revision: int, linked: bool) -> None: - """Reopen delivery for a revision while preserving send history. - - :param revision: Source revision to make the desired delivery revision. - :param linked: Whether the target still appears in the current source. - """ - self.desired_revision = revision - self.linked = linked - self.attempt_count = 0 - self.next_retry_at = None - - def clear_result_for_resend(self) -> None: - """Retry the current revision, clearing its previous delivery result. - - Reset attempt and response state without changing the desired source revision. - """ - self.reset_for_revision(self.desired_revision, self.linked) - self.processed_revision = None - self.status = None - self.failure_reason = None - self.webmention_endpoint = None - self.endpoint_response_status = None - self.status_url = None - - @hybrid_property - def awaiting_processing(self) -> bool: - """Return whether the Webmention has an unprocessed source revision.""" - return ( - self.processed_revision is None - or self.processed_revision < self.desired_revision - ) - - @awaiting_processing.inplace.expression - @classmethod - def _awaiting_processing_expression(cls) -> sa.ColumnElement[bool]: - """Express pending-revision status in database queries. - - :returns: SQLAlchemy expression selecting unprocessed source revisions. - """ - return sa.or_( - cls.processed_revision.is_(None), - cls.processed_revision < cls.desired_revision, - ) - - @property - def created_at(self) -> datetime: - """Return the creation time encoded in the Webmention UUID.""" - return uuid7_to_datetime(self.uuid) - - -def uuid7_to_datetime(identifier: UUID) -> datetime: - """Convert a UUID version 7 timestamp to a datetime. - - :param identifier: UUID whose embedded timestamp should be converted. - :returns: Timestamp as a timezone-aware UTC datetime. - """ - return datetime.fromtimestamp(identifier.time / 1000, tz=UTC) - - -def source_target_digest(source: str, target: str) -> str: - """Fingerprint an unambiguous, ordered source/target pair. - - :param source: Webmention source URL. - :param target: Webmention target URL. - :returns: SHA-256 hexadecimal digest of the ordered URL pair. - """ - encoded = json.dumps( - [source, target], ensure_ascii=False, separators=(",", ":") - ).encode("utf-8") - return sha256(encoded).hexdigest() - - -def target_digest(target: str) -> str: - """Fingerprint an outgoing target (unique within each source ID). - - :param target: Outgoing Webmention target URL. - :returns: SHA-256 hexadecimal digest of the target URL. - """ - return sha256(target.encode("utf-8")).hexdigest() |
