fix: standardize API datetime formats and use UTC-aware objects

[Rerowros]

Description

This PR addresses the inconsistency in datetime formats across the API. Previously, some endpoints returned ISO strings without the Z (UTC) suffix.

Summary by CodeRabbit

• Improvements
  • Enhanced timezone consistency across the system by normalizing all date and time fields
  • Improved timestamp processing accuracy for user notifications, subscriptions, and usage statistics
  • Updated authentication token generation to use properly formatted timezone-aware timestamps
  • Ensured consistent datetime handling across core system models and data responses

_{✏️ Tip: You can customize this high-level summary in your review settings.}

[coderabbitai]

Walkthrough

Datetime field validators are added across multiple model files to normalize timezones using fix_datetime_timezone before validation. The JWT token generation is updated to use timezone-aware datetime.now(timezone.utc) instead of datetime.utcnow().

Changes

Cohort / File(s)	Summary
Datetime Validators in Models app/models/core.py, app/models/stats.py, app/models/user.py	Added validator_date methods to normalize timezone for datetime fields via fix_datetime_timezone. Validators are applied to created_at (CoreResponse), start/end (StatList), period_start (UserUsageStat, NodeUsageStat, NodeStats), and created_at/edit_at/online_at (UserNotificationResponse, UserSubscriptionUpdateSchema).
JWT Token Generation app/utils/jwt.py	Updated create_admin_token to generate "iat" timestamp using timezone-aware datetime.now(timezone.utc) instead of naive datetime.utcnow().

Estimated code review effort

🎯 2 (Simple) | ⏱️ ~10 minutes

Poem

🐰 Hopping through timezones with care,
Normalizing dates everywhere!
From UTC's dawn to handlers anew,
Every timestamp gets its rightful hue. ✨

🚥 Pre-merge checks | ✅ 2 | ❌ 1

❌ Failed checks (1 warning)

Check name	Status	Explanation	Resolution
Docstring Coverage	⚠️ Warning	Docstring coverage is 0.00% which is insufficient. The required threshold is 80.00%.	Write docstrings for the functions missing them to satisfy the coverage threshold.

✅ Passed checks (2 passed)

Check name	Status	Explanation
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title check	✅ Passed	The title accurately and concisely summarizes the main objective of the changeset: standardizing datetime formats and ensuring UTC-aware objects are used across multiple models and utilities.

_{✏️ Tip: You can configure your own custom pre-merge checks in the settings.}

✨ Finishing touches

• 📝 Generate docstrings

---

🧹 Recent nitpick comments

app/models/user.py (1)

150-155: Consider extracting the repeated validator pattern to reduce duplication.

This exact validator implementation is duplicated across CoreResponse, StatList, UserUsageStat, NodeUsageStat, NodeStats, UserNotificationResponse, and UserSubscriptionUpdateSchema.

You could extract this into a reusable validator in validators.py:

♻️ Suggested refactor

In app/models/validators.py:

from app.utils.helpers import fix_datetime_timezone

class DatetimeValidatorMixin:
    `@classmethod`
    def normalize_timezone(cls, v):
        if not v:
            return v
        return fix_datetime_timezone(v)

Then in each model:

from .validators import DatetimeValidatorMixin

`@field_validator`("created_at", mode="before")
`@classmethod`
def validator_date(cls, v):
    return DatetimeValidatorMixin.normalize_timezone(v)

Or use a functional approach with Annotated types for Pydantic v2.

app/models/stats.py (1)

34-43: Minor style inconsistency with existing validators.

The new validator_date method uses @classmethod (line 39), but the existing cast_to_int (line 35) does not. Both work in Pydantic v2, but for consistency, consider adding @classmethod to cast_to_int as well—or follow the existing style by omitting it from new validators.

---

📜 Recent review details

Configuration used: Organization UI

Review profile: CHILL

Plan: Pro

📥 Commits

Reviewing files that changed from the base of the PR and between b9babc5 and 31cbbfd.

📒 Files selected for processing (4)

• app/models/core.py
• app/models/stats.py
• app/models/user.py
• app/utils/jwt.py

🧰 Additional context used

🧬 Code graph analysis (3)

app/models/core.py (1)

app/utils/helpers.py (1)

• fix_datetime_timezone (33-45)

app/models/stats.py (2)

app/utils/helpers.py (1)

• fix_datetime_timezone (33-45)

app/models/user.py (2)

• validator_date (114-117)
• validator_date (152-155)

app/models/user.py (2)

app/models/stats.py (4)

• validator_date (24-27)
• validator_date (40-43)
• validator_date (61-64)
• validator_date (99-102)

app/utils/helpers.py (1)

• fix_datetime_timezone (33-45)

⏰ Context from checks skipped due to timeout of 90000ms. You can increase the timeout in your CodeRabbit configuration to a maximum of 15 minutes (900000ms). (2)

• GitHub Check: Agent
• GitHub Check: CodeQL analysis (python)

🔇 Additional comments (5)

app/utils/jwt.py (1)

22-22: LGTM! Correct migration to timezone-aware datetime.

Using datetime.now(timezone.utc) instead of the deprecated datetime.utcnow() is the right approach. This ensures the iat claim is timezone-aware and consistent with how expire is calculated on line 24.

app/models/core.py (1)

50-55: Implementation looks correct.

The validator properly normalizes timezone for created_at using the helper. The if not v: guard allows Pydantic to handle validation of missing/null values for required fields.

app/models/user.py (1)

112-117: Validator correctly handles both required and optional fields.

The single validator method properly covers all three datetime fields. Optional fields (edit_at, online_at) will pass through None unchanged, while non-null values get timezone-normalized.

app/models/stats.py (2)

22-27: LGTM! Validator correctly normalizes both start and end fields.

The implementation is consistent with the pattern used across the PR.

---

59-64: Validators for NodeUsageStat and NodeStats are correctly implemented.

Both follow the established pattern and properly normalize period_start timezone.

Also applies to: 97-102

_{✏️ Tip: You can disable this entire section by setting review_details to false in your review settings.}

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands and usage tips.}

[Copilot]

Pull request overview

This PR standardizes datetime handling across the API by ensuring all datetime objects are UTC-aware and formatted consistently. The changes replace deprecated datetime.utcnow() usage and add validators to ensure all datetime fields returned by the API have proper timezone information.

Changes:

• Replaced datetime.utcnow() with datetime.now(timezone.utc) in JWT token creation
• Added field validators to all response models containing datetime fields to ensure UTC-aware datetime objects
• Applied the fix_datetime_timezone helper consistently across all models

Reviewed changes

Copilot reviewed 4 out of 4 changed files in this pull request and generated no comments.

File	Description
app/utils/jwt.py	Updated JWT token creation to use UTC-aware datetime objects
app/models/user.py	Added field validators for created_at, edit_at, and online_at fields
app/models/stats.py	Added field validators for start, end, and period_start datetime fields
app/models/core.py	Added field validator for created_at field

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.