feat(subscription): add IP address support to user subscription updates

Author: ImMohammad20000

app/db/crud/user.py

@@ -39,6 +39,7 @@
 from .group import get_groups_by_ids
 
 _USER_AGENT_MAX_LEN = UserSubscriptionUpdate.__table__.columns.user_agent.type.length or 512
+_SUBSCRIPTION_UPDATE_IP_MAX_LEN = UserSubscriptionUpdate.__table__.columns.ip.type.length or 64
 
 
 def _build_user_select_stmt(
@@ -1140,19 +1141,21 @@ async def bulk_revoke_user_sub(db: AsyncSession, users: list[User]) -> list[User
     return users
 
 
-async def user_sub_update(db: AsyncSession, user_id: User, user_agent: str) -> User:
+async def user_sub_update(db: AsyncSession, user_id: int, user_agent: str, ip: str | None = None) -> None:
     """
     Updates the user's subscription details.
 
     Args:
         db (AsyncSession): Database session.
-        user_id (User): The user id whose subscription is to be updated.
+        user_id (int): The user id whose subscription is to be updated.
         user_agent (str): The user agent string.
+        ip (str | None): The client IP address.
 
     """
     # Clamp to column length; some clients send very long strings (e.g. encoded configs) as User-Agent.
     sanitized_user_agent = (user_agent or "")[:_USER_AGENT_MAX_LEN]
-    agent = UserSubscriptionUpdate(user_id=user_id, user_agent=sanitized_user_agent)
+    sanitized_ip = (ip or "")[:_SUBSCRIPTION_UPDATE_IP_MAX_LEN] or None
+    agent = UserSubscriptionUpdate(user_id=user_id, user_agent=sanitized_user_agent, ip=sanitized_ip)
     db.add(agent)
     await db.commit()
 

app/db/migrations/versions/73c78c6a9b24_add_ip_to_user_subscription_updates.py

@@ -0,0 +1,25 @@
+"""add ip to user subscription updates
+
+Revision ID: 73c78c6a9b24
+Revises: af2d644dda44
+Create Date: 2026-05-06 00:00:00.000000
+
+"""
+
+from alembic import op
+import sqlalchemy as sa
+
+
+revision = "73c78c6a9b24"
+down_revision = "af2d644dda44"
+branch_labels = None
+depends_on = None
+
+
+def upgrade() -> None:
+    op.add_column("user_subscription_updates", sa.Column("ip", sa.String(length=64), nullable=True))
+
+
+def downgrade() -> None:
+    with op.batch_alter_table("user_subscription_updates", schema=None) as batch_op:
+        batch_op.drop_column("ip")

app/db/models.py

@@ -331,6 +331,7 @@ class UserSubscriptionUpdate(Base):
     user: Mapped["User"] = relationship(back_populates="subscription_updates", init=False)
     created_at: Mapped[dt] = mapped_column(DateTime(timezone=True), default_factory=lambda: dt.now(tz.utc), init=False)
     user_agent: Mapped[str] = mapped_column(String(512))
+    ip: Mapped[Optional[str]] = mapped_column(String(64), nullable=True, default=None)
 
 
 template_group_association = Table(

app/models/user.py

@@ -132,6 +132,7 @@ class SubscriptionUserResponse(UserResponse):
     note: str | None = Field(None, exclude=True)
     auto_delete_in_days: int | None = Field(None, exclude=True)
     subscription_url: str | None = Field(None, exclude=True)
+    ip: str | None = Field(default=None)
     model_config = ConfigDict(from_attributes=True)
 
 
@@ -164,6 +165,7 @@ class UsersSimpleResponse(BaseModel):
 class UserSubscriptionUpdateSchema(BaseModel):
     created_at: dt
     user_agent: str
+    ip: str | None = Field(default=None)
 
     model_config = ConfigDict(from_attributes=True)
 

app/operation/subscription.py

@@ -253,6 +253,7 @@ async def user_subscription(
         token: str,
         accept_header: str = "",
         user_agent: str = "",
+        ip: str | None = None,
         request_url: str = "",
     ):
         """
@@ -301,7 +302,7 @@ async def user_subscription(
                 await self.raise_error(message="Client not supported", code=406)
 
             # Update user subscription info
-            await user_sub_update(db, db_user.id, user_agent)
+            await user_sub_update(db, db_user.id, user_agent, ip=ip)
             conf, media_type = await self.fetch_config(user, client_type)
 
             # If disable_sub_template is True and it's a browser request, use inline to view instead of download
@@ -397,7 +398,9 @@ async def user_subscription_by_id(
         db_user = await self.get_validated_user_by_id(db, user_id, admin)
         return await self.user_subscription_by_user(db_user, client_type, request_url)
 
-    async def user_subscription_info(self, db: AsyncSession, token: str) -> tuple[SubscriptionUserResponse, dict]:
+    async def user_subscription_info(
+        self, db: AsyncSession, token: str, ip: str | None = None
+    ) -> tuple[SubscriptionUserResponse, dict]:
         """Retrieves detailed information about the user's subscription."""
         sub_settings: SubSettings = await subscription_settings()
         db_user = await self.get_validated_sub(db, token=token)
@@ -409,6 +412,7 @@ async def user_subscription_info(self, db: AsyncSession, token: str) -> tuple[Su
         except ValueError as exc:
             await self.raise_error(message=str(exc), code=400)
         user_response = SubscriptionUserResponse.model_validate(db_user)
+        user_response.ip = ip
 
         return user_response, response_headers
 

app/routers/subscription.py

@@ -15,6 +15,15 @@
 subscription_operator = SubscriptionOperation(operator_type=OperatorType.API)
 
 
+def get_client_ip(request: Request) -> str | None:
+    forwarded_for = request.headers.get("X-Forwarded-For")
+    if forwarded_for:
+        return forwarded_for.split(",")[0].strip()
+    if request.client:
+        return request.client.host
+    return None
+
+
 @router.get("/{token}/")
 @router.get("/{token}", include_in_schema=False)
 async def user_subscription(
@@ -29,14 +38,17 @@ async def user_subscription(
         token=token,
         accept_header=request.headers.get("Accept", ""),
         user_agent=user_agent,
+        ip=get_client_ip(request),
         request_url=str(request.url),
     )
 
 
 @router.get("/{token}/info", response_model=SubscriptionUserResponse)
 async def user_subscription_info(request: Request, token: str, db: AsyncSession = Depends(get_db)):
     """Retrieves detailed information about the user's subscription."""
-    user_data, response_headers = await subscription_operator.user_subscription_info(db, token=token)
+    user_data, response_headers = await subscription_operator.user_subscription_info(
+        db, token=token, ip=get_client_ip(request)
+    )
     return JSONResponse(content=user_data.model_dump(mode="json"), headers=response_headers)
 
 

tests/api/test_user.py

@@ -308,13 +308,32 @@ def test_user_sub_update_user_agent(access_token):
     try:
         url = user["subscription_url"]
         user_agent = "v2rayNG/1.9.46 This is PasarGuard Test"
-        client.get(url, headers={"User-Agent": user_agent})
+        ip = "203.0.113.10"
+        client.get(url, headers={"User-Agent": user_agent, "X-Forwarded-For": ip})
         response = client.get(
             f"/api/user/{user['username']}/sub_update",
             headers={"Authorization": f"Bearer {access_token}"},
         )
         assert response.status_code == status.HTTP_200_OK
         assert response.json()["updates"][0]["user_agent"] == user_agent
+        assert response.json()["updates"][0]["ip"] == ip
+    finally:
+        delete_user(access_token, user["username"])
+        cleanup_groups(access_token, core, groups)
+
+
+def test_user_subscription_info_returns_request_ip(access_token):
+    core, groups = setup_groups(access_token, 1)
+    user = create_user(
+        access_token,
+        group_ids=[groups[0]["id"]],
+        payload={"username": unique_name("test_subscription_info_ip")},
+    )
+    try:
+        ip = "198.51.100.7"
+        response = client.get(f"{user['subscription_url']}/info", headers={"X-Forwarded-For": ip})
+        assert response.status_code == status.HTTP_200_OK
+        assert response.json()["ip"] == ip
     finally:
         delete_user(access_token, user["username"])
         cleanup_groups(access_token, core, groups)