feat(client): add client management and registration functionality

- Introduced ClientManager for handling client registration and lookup.
- Added ClientModel schema for client representation.
- Updated settings to include client-specific configurations.
- Modified extension management to enable/disable extensions per client.
- Created migration for clients table and updated extensions schema.
- Enhanced API endpoints for enabling/disabling extensions for clients.

Author: xiaoland

.env.example

@@ -1,6 +1,9 @@
 # Server Configuration
 HOST=0.0.0.0
 PORT=8000
+CLIENT_ID=  # optional
+CLIENT_NAME=  # optional
+CLIENT_BASE_URL=  # required
 
 # JWT Authentication (Required)
 JWT_SECRET=your_jwt_secret_here

app/business/client/__init__.py

@@ -0,0 +1,5 @@
+from .main import ClientManager
+
+__all__ = [
+    "ClientManager",
+]

app/business/client/main.py

@@ -0,0 +1,67 @@
+__all__ = [
+  "ClientManager",
+]
+
+import sqlalchemy.dialects.postgresql
+import sqlmodel
+from app.engine import SessionLocal
+from app.settings import settings
+from app.schemas.client.main import ClientModel, ClientID
+from libs.obsrv.main import get_logger
+
+
+LOGGER = get_logger().getChild(__name__)
+
+
+class ClientManager:
+  """Manages client registration and lookup."""
+
+  @classmethod
+  def register_self(cls) -> ClientModel:
+    """Register or update the current client in the database.
+
+    Uses upsert to handle both initial registration and updates.
+    Called during application startup.
+    """
+    with SessionLocal() as db:
+      stmt = sqlalchemy.dialects.postgresql.insert(ClientModel).values(
+        id=settings.client_id,
+        name=settings.client_name,
+        rest_api_url=settings.client_base_url,
+      )
+      stmt = stmt.on_conflict_do_update(
+        index_elements=["id"],
+        set_=dict(
+          name=stmt.excluded.name,
+          rest_api_url=stmt.excluded.rest_api_url,
+        ),
+      )
+      db.exec(stmt)  # type: ignore
+      db.commit()
+
+      # Fetch and return the registered client
+      client = db.exec(
+        sqlmodel.select(ClientModel).where(ClientModel.id == settings.client_id)
+      ).one()
+
+      LOGGER.info(f"Client registered: {client.name} ({client.id})")
+      return client
+
+  @classmethod
+  def get_current_client_id(cls) -> ClientID:
+    """Get the current client's ID."""
+    return settings.client_id
+
+  @classmethod
+  def get(cls, client_id: ClientID) -> ClientModel | None:
+    """Get a client by ID."""
+    with SessionLocal() as db:
+      return db.exec(
+        sqlmodel.select(ClientModel).where(ClientModel.id == client_id)
+      ).first()
+
+  @classmethod
+  def get_all(cls) -> tuple[ClientModel, ...]:
+    """Get all registered clients."""
+    with SessionLocal() as db:
+      return tuple(db.exec(sqlmodel.select(ClientModel)).all())

app/business/extension/main.py

@@ -1,7 +1,9 @@
 import abc
+import uuid
 import typing
 import fastapi
 import sqlmodel
+import sqlalchemy
 import importlib
 import os
 import tomllib
@@ -95,9 +97,11 @@ class ExtensionManager:
 
   @classmethod
   def start_enabled(cls, app: fastapi.FastAPI):
-    """Start all enabled entensions."""
+    """Start all extensions enabled for the current client."""
+    from app.business.client import ClientManager
+
     cls.FASTAPI_APP = app
-    for extension in cls.get_installed():
+    for extension in cls.get_installed(enabled_only=True):
       cls.start(extension=extension)
 
   @classmethod
@@ -305,7 +309,7 @@ def download(cls, extid: str, version: Opt[str] = None) -> ExtensionModel:
       version=version or "0.0.0",
       nickname=nickname,
       config={},
-      disabled=True,
+      enabled=[],
     )
 
   @classmethod
@@ -329,8 +333,15 @@ def install(cls, extid: ExtensionID, version: Opt[str] = None) -> ExtensionModel
       return extension
 
   @classmethod
-  async def set_disabled(cls, extid: ExtensionID, disabled: bool) -> ExtensionModel:
-    """Enable or disable an extension."""
+  async def enable(cls, extid: ExtensionID) -> ExtensionModel:
+    """Enable an extension for the current client.
+
+    Adds the current client ID to the extension's enabled list and starts it.
+    """
+    from app.business.client import ClientManager
+
+    client_id = ClientManager.get_current_client_id()
+
     with SessionLocal() as db:
       extension = db.exec(
         sqlmodel.select(ExtensionModel).where(ExtensionModel.id == extid)
@@ -339,32 +350,76 @@ async def set_disabled(cls, extid: ExtensionID, disabled: bool) -> ExtensionMode
       if not extension:
         raise ValueError(f"Extension with id {extid} not found.")
 
-      extension.disabled = disabled
-      db.add(extension)
-      db.commit()
-      db.refresh(extension)
+      # Add client to enabled list if not already present
+      current_enabled = set(extension.enabled)
+      if client_id not in current_enabled:
+        current_enabled.add(client_id)
+        extension.enabled = list(current_enabled)
+        db.add(extension)
+        db.commit()
+        db.refresh(extension)
+
+      # Start extension if not already running
+      if extid not in cls.RUNNING_EXTENSIONS:
+        cls.start(extid)
+
+      return extension
+
+  @classmethod
+  async def disable(cls, extid: ExtensionID) -> ExtensionModel:
+    """Disable an extension for the current client.
+
+    Removes the current client ID from the extension's enabled list and stops it.
+    """
+    from app.business.client import ClientManager
+
+    client_id = ClientManager.get_current_client_id()
 
-      if disabled:
+    with SessionLocal() as db:
+      extension = db.exec(
+        sqlmodel.select(ExtensionModel).where(ExtensionModel.id == extid)
+      ).first()
+
+      if not extension:
+        raise ValueError(f"Extension with id {extid} not found.")
+
+      # Remove client from enabled list
+      current_enabled = set(extension.enabled)
+      if client_id in current_enabled:
+        current_enabled.discard(client_id)
+        extension.enabled = list(current_enabled)
+        db.add(extension)
+        db.commit()
+        db.refresh(extension)
+
+      # Close extension if running
+      if extid in cls.RUNNING_EXTENSIONS:
         await cls.close(extid)
-      else:
-        cls.start(extid)
 
       return extension
 
   @classmethod
-  def get_installed(cls, disabled: Opt[bool] = False) -> tuple[ExtensionModel, ...]:
+  def get_installed(
+    cls,
+    enabled_only: bool = False,
+  ) -> tuple[ExtensionModel, ...]:
     """Get installed extensions.
 
-    :param disabled: If True, include disabled extensions; otherwise, only enabled ones.
+    :param enabled_only: If True, only return extensions enabled for the current client.
     """
+    from app.business.client import ClientManager
+
     with SessionLocal() as db:
-      return tuple(
-        db.exec(
-          sqlmodel.select(ExtensionModel).where(
-            disabled is None or ExtensionModel.disabled == disabled
-          )
-        ).all()
-      )
+      query = sqlmodel.select(ExtensionModel)
+
+      if enabled_only:
+        client_id = ClientManager.get_current_client_id()
+        # Filter: client_id must be in the enabled array
+        query = query.where(
+          ExtensionModel.enabled.any(client_id, operator=sqlalchemy.sql.operators.eq)
+        )
+
+      return tuple(db.exec(query).all())
 
   @classmethod
   def get(cls, extid: ExtensionID) -> Opt[ExtensionModel]:
@@ -460,7 +515,7 @@ def sync(cls):
                 id=ext_id,
                 version=version,
                 nickname=nickname,
-                disabled=True,
+                enabled=[],
               )
               db.add(new_ext)
               new_count += 1

app/routes/extension.py

@@ -16,7 +16,7 @@
 @ROUTER.get("")
 def get_extensions() -> tuple[ExtensionModel, ...]:
   """List all installed extensions"""
-  return ExtensionManager.get_installed(disabled=None)
+  return ExtensionManager.get_installed()
 
 
 @ROUTER.post("/{extid}")
@@ -29,11 +29,23 @@ def install_extension(
   return ExtensionManager.install(extid, version=version)
 
 
-@ROUTER.put("/{extid}/disabled/{disabled}")
-async def toggle_extension(extid: ExtensionID, disabled: bool) -> ExtensionModel:
-  """启用/禁用插件 (Enable/Disable extension)"""
+@ROUTER.post("/{extid}/enable")
+async def enable_extension(extid: ExtensionID) -> ExtensionModel:
+  """启用插件 (Enable extension for current client)"""
   try:
-    return await ExtensionManager.set_disabled(extid, disabled)
+    return await ExtensionManager.enable(extid)
+  except ValueError:
+    raise fastapi.HTTPException(
+      status_code=fastapi.status.HTTP_404_NOT_FOUND,
+      detail=f"Extension with id {extid} not found.",
+    )
+
+
+@ROUTER.post("/{extid}/disable")
+async def disable_extension(extid: ExtensionID) -> ExtensionModel:
+  """禁用插件 (Disable extension for current client)"""
+  try:
+    return await ExtensionManager.disable(extid)
   except ValueError:
     raise fastapi.HTTPException(
       status_code=fastapi.status.HTTP_404_NOT_FOUND,

app/schemas/__init__.py

@@ -9,6 +9,7 @@
   "ExtensionModel",
   "RelationEmbeddingModel",
   "BlockEmbeddingModel",
+  "ClientModel",
 ]
 
 import sqlalchemy.orm
@@ -23,3 +24,4 @@
 from .source import SourceModel, SourceCollectJobModel
 from .extension.main import ExtensionModel
 from .sink import RelationEmbeddingModel, BlockEmbeddingModel
+from .client.main import ClientModel

app/schemas/client/__init__.py

@@ -0,0 +1,6 @@
+from .main import ClientModel, ClientID
+
+__all__ = [
+    "ClientModel",
+    "ClientID",
+]

app/schemas/client/main.py

@@ -0,0 +1,50 @@
+import datetime
+import uuid
+import sqlalchemy
+import sqlalchemy.dialects.postgresql
+import sqlmodel
+import typing
+from typing import Optional as Opt
+
+
+ClientID: typing.TypeAlias = uuid.UUID
+
+
+class ClientModel(sqlmodel.SQLModel, table=True):
+    """Client registration model.
+
+    Represents a client instance that connects to this InKCre deployment.
+    All clients are equal peers in the network.
+    """
+
+    __tablename__: str = "clients"  # type: ignore
+
+    id: ClientID = sqlmodel.Field(
+        sa_column=sqlalchemy.Column(
+            sqlalchemy.dialects.postgresql.UUID(as_uuid=True),
+            primary_key=True,
+            default=uuid.uuid4,
+        )
+    )
+    name: str = sqlmodel.Field(
+        sa_column=sqlalchemy.Column(sqlalchemy.Text, nullable=False)
+    )
+    labels: list[str] = sqlmodel.Field(
+        default_factory=list,
+        sa_column=sqlalchemy.Column(
+            sqlalchemy.dialects.postgresql.ARRAY(sqlalchemy.Text),
+            server_default=sqlalchemy.text("'{}'::text[]"),
+        ),
+    )
+    rest_api_url: Opt[str] = sqlmodel.Field(
+        default=None,
+        sa_column=sqlalchemy.Column(sqlalchemy.Text, nullable=True),
+    )
+    """REST API base URL. Nullable since not all clients are reachable (e.g., client-web)."""
+    created_at: datetime.datetime = sqlmodel.Field(
+        default_factory=datetime.datetime.now,
+        sa_column=sqlalchemy.Column(
+            sqlalchemy.TIMESTAMP(timezone=True),
+            server_default=sqlalchemy.text("CURRENT_TIMESTAMP"),
+        ),
+    )

app/schemas/extension/main.py

@@ -1,3 +1,4 @@
+import uuid
 import sqlalchemy
 import sqlalchemy.dialects.postgresql
 import sqlmodel
@@ -24,7 +25,20 @@ class ExtensionModel(sqlmodel.SQLModel, table=True):
     
     format: `major.minor.patch`.
     """
-  disabled: bool = sqlmodel.Field(default=False)
+  enabled: list[uuid.UUID] = sqlmodel.Field(
+    default_factory=list,
+    sa_column=sqlmodel.Column(
+      sqlalchemy.dialects.postgresql.ARRAY(
+        sqlalchemy.dialects.postgresql.UUID(as_uuid=True)
+      ),
+      server_default=sqlalchemy.text("'{}'::uuid[]"),
+      nullable=False,
+    ),
+  )
+  """List of client IDs for which this extension is enabled.
+
+  Empty array means disabled for all clients.
+  """
   nickname: Opt[str] = sqlmodel.Field(default=None)
   config: dict = sqlmodel.Field(
     default_factory=dict,