Merge pull request #7 from getmarkus/cm-branch-6

feat: add issue command and transition state management

Author: getmarkus

.trunk/.gitignore

@@ -0,0 +1,9 @@
+*out
+*logs
+*actions
+*notifications
+*tools
+plugins
+user_trunk.yaml
+user.yaml
+tmp

.trunk/configs/.isort.cfg

@@ -0,0 +1,2 @@
+[settings]
+profile=black

.trunk/configs/.markdownlint.yaml

@@ -0,0 +1,2 @@
+# Prettier friendly markdownlint config (all formatting rules disabled)
+extends: markdownlint/style/prettier

.trunk/configs/ruff.toml

@@ -0,0 +1,5 @@
+# Generic, formatter-friendly config.
+select = ["B", "D3", "E", "F"]
+
+# Never enforce `E501` (line length violations). This should be handled by formatters.
+ignore = ["E501"]

.trunk/trunk.yaml

@@ -0,0 +1,30 @@
+# This file controls the behavior of Trunk: https://docs.trunk.io/cli
+# To learn more about the format of this file, see https://docs.trunk.io/reference/trunk-yaml
+version: 0.1
+cli:
+  version: 1.22.9
+# Trunk provides extensibility via plugins. (https://docs.trunk.io/plugins)
+plugins:
+  sources:
+    - id: trunk
+      ref: v1.6.6
+      uri: https://github.com/trunk-io/plugins
+# Many linters and tools depend on runtimes - configure them here. (https://docs.trunk.io/runtimes)
+runtimes:
+  enabled:
+    - [email protected]
+    - [email protected]
+# This is the section where you manage your linters. (https://docs.trunk.io/check/configuration)
+lint:
+  disabled:
+    - bandit
+  enabled:
+    - [email protected]
+    - [email protected]
+    - git-diff-check
+    - [email protected]
+    - [email protected]
+    - [email protected]
+    - [email protected]
+    - [email protected]
+    - [email protected]

config.py

@@ -21,7 +21,7 @@ class Settings(BaseSettings):
     # "http://localhost:8080", "http://local.dockertoolbox.tiangolo.com"]'
     backend_cors_origins: List[AnyHttpUrl] = []
 
-    model_config = SettingsConfigDict(env_file=".env")
+    model_config = SettingsConfigDict(env_file=".env", extra="allow")
     # `.env.prod` takes priority over `.env`
     #   env_file=('.env', '.env.prod')
 

main.py

@@ -1,6 +1,7 @@
-from contextlib import asynccontextmanager
 import datetime
 import os
+import uuid
+from contextlib import asynccontextmanager
 from typing import Annotated, Any, Dict, Optional
 
 from fastapi import Depends, FastAPI
@@ -106,13 +107,50 @@ def create_health_response(is_healthy: bool, check_name: str) -> JSONResponse:
 # Register global exception handler
 app.add_exception_handler(AppException, app_exception_handler)
 
+# middleware options
+# https://levelup.gitconnected.com/17-useful-middlewares-for-fastapi-that-you-should-know-about-951c2b0869c7
+# https://fastapi.tiangolo.com/tutorial/middleware/
+# https://http.dev/headers
+# CORS
+# Authorization and Authentication
+# Localization
+# Caching
+# Rate Limiting
+# Tracing
+# Dependency Injection
+# A/B testing
+# Metrics
+# Route security, ip address and user agent - TrustedHostMiddleware
+# gzip compression - GZipMiddleware
+# ssl enforcement - HTTPSRedirectMiddleware
+
+@app.middleware("http")
+async def add_request_id(request, call_next):
+    request_id = str(uuid.uuid4())
+    request.state.request_id = request_id
+    response = await call_next(request)
+    response.headers["X-Request-ID"] = request_id
+    logger.info(f"Request {request_id} to {request.url.path}")
+    return response
+
+@app.middleware("http")
+async def add_process_time_header(request, call_next):
+    import time
+    start_time = time.perf_counter()
+    response = await call_next(request)
+    process_time = time.perf_counter() - start_time
+    response.headers["X-Process-Time"] = str(process_time)
+    logger.info(f"Request to {request.url.path} took {process_time:.4f} seconds")
+    return response
+
 app.add_middleware(
     CORSMiddleware,
     allow_origins=["*"],  # Set this to lock down if applicable to your use case
     # allow_origins=[str(origin) for origin in settings.BACKEND_CORS_ORIGINS],
     allow_credentials=False,  # Must be false if all origins (*) is allowed
     allow_methods=["*"],
-    allow_headers=["X-Forwarded-For", "Authorization", "Content-Type"],
+    allow_headers=["X-Forwarded-For", "Authorization", "Content-Type", "X-Request-ID"],
+    expose_headers=["X-Process-Time", "X-Request-ID"]
 )
 
 

requirements.txt

@@ -0,0 +1,3 @@
+pytest==8.0.0
+pytest-cov==4.1.0
+pydantic==2.6.1

src/domain/issue.py

@@ -1,6 +1,8 @@
+from dataclasses import dataclass
 from datetime import datetime
-from enum import Enum
-from typing import Optional
+from enum import Enum, auto
+from types import MappingProxyType
+from typing import Any, Final, Optional
 
 from src.domain.aggregate_root import AggregateRoot, BaseCommand, BaseEvent
 
@@ -11,19 +13,20 @@
 # https://docs.github.com/en/rest/issues/timeline?apiVersion=2022-11-28
 # https://github.blog/open-source/maintainers/metrics-for-issues-pull-requests-and-discussions/
 
-class IssueState(Enum):
-    OPEN = "OPEN"
-    CLOSED = "CLOSED"
-
-    @property
-    def is_open(self):
-        return self == IssueState.OPEN
+### Enums ###
 
-class IssueStateTransition(Enum):
+class IssueTransitionState(Enum):
     COMPLETED = "COMPLETED"
     NOT_PLANNED = "NOT_PLANNED"
     REOPENED = "REOPENED"
 
+
+class IssueTransitionType(Enum):
+    CLOSE_AS_COMPLETE = auto()
+    CLOSE_AS_NOT_PLANNED = auto()
+    REOPEN = auto()
+
+
 class IssueEventType(Enum):
     OPENED = "OPENED"
     EDITED = "EDITED"
@@ -34,15 +37,94 @@ class IssueEventType(Enum):
     LABLED = "LABLED"
     UNLABLED = "UNLABLED"
 
+
+# https://github.com/pytransitions/transitions?tab=readme-ov-file#transitions
+# https://python-statemachine.readthedocs.io/en/latest/auto_examples/persistent_model_machine.html
+# important features of state machines:
+# States, Transistions, Events, Actions(state, transition), Conditions, Validators (guard), Listeners
+# State Actions: on_enter, on_exit
+# Transition Actions: before, on, after
+
+
+@dataclass(frozen=True)
+class StateTransition:
+    """Represents a valid transition between states"""
+
+    from_state: "IssueState"
+    to_state: "IssueState"
+
+
+class IssueState(Enum):
+    OPEN = "OPEN"
+    CLOSED = "CLOSED"
+
+    @classmethod
+    def transitions(cls) -> dict[IssueTransitionType, StateTransition]:
+        """Get the valid state transitions"""
+        return _ISSUE_STATE_TRANSITIONS
+
+    @property
+    def is_open(self) -> bool:
+        return self == IssueState.OPEN
+
+    def transition(self, transition_type: IssueTransitionType) -> "IssueState":
+        """
+        Change the state based on the given transition type, enforcing valid transitions.
+        Args:
+            transition_type: The type of transition to perform
+        Returns:
+            The new IssueState after the transition
+        Raises:
+            ValueError: If the transition is not valid for the current state
+        """
+        if not isinstance(transition_type, IssueTransitionType):
+            raise ValueError(f"Unknown transition type: {transition_type}")
+
+        try:
+            transition = self.transitions()[transition_type]
+        except KeyError as err:
+            raise ValueError(f"Unknown transition type: {transition_type}") from err
+
+        if self != transition.from_state:
+            raise ValueError(
+                f"Cannot perform {transition_type.name} transition from state {self.value}"
+            )
+
+        return transition.to_state
+
+
+# Define valid transitions using the type-safe StateTransition class
+_ISSUE_STATE_TRANSITIONS: Final[dict[IssueTransitionType, StateTransition]] = (
+    MappingProxyType(
+        {
+            IssueTransitionType.CLOSE_AS_COMPLETE: StateTransition(
+                IssueState.OPEN, IssueState.CLOSED
+            ),
+            IssueTransitionType.CLOSE_AS_NOT_PLANNED: StateTransition(
+                IssueState.OPEN, IssueState.CLOSED
+            ),
+            IssueTransitionType.REOPEN: StateTransition(
+                IssueState.CLOSED, IssueState.OPEN
+            ),
+        }
+    )
+)
+
+
+### Exceptions ###
+
+### Value Objects ###
+
+
 ### Events ###
 class IssueEvent(BaseEvent):
     event_id: str
     timestamp: datetime
     issue_number: int
     issue_state: IssueState
-    issue_state_transition: IssueStateTransition
+    issue_state_transition: IssueTransitionState
     issue_event_type: IssueEventType
-    changes: dict[str, any]
+    changes: dict[str, Any]
     previous_title: str
     previous_body: str
     assignee: Optional[str]
@@ -54,13 +136,13 @@ def __init__(
         timestamp: datetime,
         issue_number: int,
         issue_state: IssueState,
-        issue_state_transition: IssueStateTransition,
+        issue_state_transition: IssueTransitionState,
         issue_event_type: IssueEventType,
-        changes: dict[str, any],
+        changes: dict[str, Any],
         previous_title: str,
         previous_body: str,
         assignee: Optional[str] = None,
-        label: Optional[str] = None
+        label: Optional[str] = None,
     ):
         super().__init__()
         self.event_id = event_id
@@ -75,6 +157,7 @@ def __init__(
         self.assignee = assignee
         self.label = label
 
+
 ## potential sub-events
 # - connected
 # - disconnected
@@ -95,19 +178,11 @@ def __init__(
 # - user_blocked
 # - commented OR IssueCommentEvent
 
-### Commands ###
-class IssueCommand(BaseCommand):
-    command_id: str
-    timestamp: datetime
-    issue_number: int
-
-    # might need specification pattern here
-    def validate(self) -> bool:
-        return True
 
 ### Entitites ###
 class Issue(AggregateRoot):
     issue_number: int
+    issue_state: IssueState = IssueState.OPEN
 
     def process(self, command: BaseCommand) -> list[BaseEvent]:
         if command.validate():
@@ -120,6 +195,13 @@ def apply(self, event: BaseEvent) -> None:
 
     # likely need a handler method here for 'domain' events and not aggregate events
 
-### Exceptions ###
 
-### Value Objects ###
+### Commands ###
+class IssueCommand(BaseCommand):
+    command_id: str
+    timestamp: datetime
+    issue: Issue
+
+    # might need specification pattern here
+    def validate(self) -> bool:
+        return True

src/resource_adapters/persistence/in_memory/issues.py

@@ -1,4 +1,4 @@
-from typing import Callable, Iterable, List
+from typing import Callable, List
 
 from loguru import logger