aboutsummaryrefslogtreecommitdiff
path: root/webmentions_ssg/models.py
diff options
context:
space:
mode:
Diffstat (limited to '')
-rw-r--r--webmentions_ssg/models.py420
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()