chore(utils): refactor endpointrequest to make more sense

o-santi · o-santi · commit e161f53a75ae · 2026-01-28T17:03:58.000-03:00
rename classes with `endpoint` in their name. given that this is a
client, and not a server, these might not make sense

the initial idea was that these were supposed to hit a 'server
endpoint', but I think that the name is confusing after trying to use
it elsewhere

i've also split the one request class into multiple, because it makes
more sense in the context of the other packages
diff --git a/src/functions/src/supabase_functions/client.py b/src/functions/src/supabase_functions/client.py
@@ -1,15 +1,19 @@
 from typing import Dict, Generic, Literal, Optional, Union, overload
 from warnings import warn
 
-from httpx import AsyncClient, Client, Headers, Response
+from httpx import AsyncClient, Client, Headers, QueryParams, Response
 from supabase_utils.http import (
     AsyncExecutor,
-    EndpointRequest,
+    BytesRequest,
+    EmptyRequest,
     Executor,
     HTTPRequestMethod,
-    ServerEndpoint,
+    JSONRequest,
+    ResponseHandler,
     SyncExecutor,
-    http_endpoint,
+    TextRequest,
+    ToHttpxRequest,
+    http_request,
 )
 from supabase_utils.types import JSON
 from yarl import URL
@@ -79,42 +83,61 @@ def _invoke_options_to_request(
         region: Optional[FunctionRegion],
         headers: Optional[Dict[str, str]],
         method: Optional[HTTPRequestMethod],
-    ) -> EndpointRequest:
+    ) -> ToHttpxRequest:
         if not is_valid_str_arg(function_name):
             raise ValueError("function_name must a valid string value.")
 
-        request = EndpointRequest(
-            method="POST",
-            path=[function_name],
-            headers=Headers(self.headers),
-        )
+        method = method or "POST"
+        path = [function_name]
+        new_headers = Headers(self.headers)
+        query_params = QueryParams()
 
-        request.headers.update(headers or dict())
+        if headers:
+            new_headers.update(headers)
         if region and region != FunctionRegion.Any:
-            request.headers["x-region"] = region.value
+            new_headers["x-region"] = region.value
             # Add region as query parameter
-            request.query_param("forceFunctionRegion", region.value)
-
-        if method:
-            request.method = method
+            query_params = query_params.set("forceFunctionRegion", region.value)
 
         if isinstance(body, str):
-            request.plain_text(body)
+            return TextRequest(
+                text=body,
+                method=method,
+                path=path,
+                headers=new_headers,
+                query_params=query_params,
+            )
         elif isinstance(body, dict):
-            request.json(body)
+            return JSONRequest(
+                body=body,
+                method=method,
+                path=path,
+                headers=new_headers,
+                query_params=query_params,
+                exclude_none=False,
+            )
         elif isinstance(body, bytes):
-            request.bytes(body)
-        return request
+            return BytesRequest(
+                body=body,
+                method=method,
+                path=path,
+                headers=new_headers,
+                query_params=query_params,
+            )
+        else:
+            return EmptyRequest(
+                method=method, path=path, headers=new_headers, query_params=query_params
+            )
 
-    @http_endpoint
+    @http_request
     def invoke(
         self,
         function_name: str,
         body: Union[bytes, str, Dict[str, JSON], None] = None,
         region: Optional[FunctionRegion] = None,
         headers: Optional[Dict[str, str]] = None,
         method: Optional[HTTPRequestMethod] = None,
-    ) -> ServerEndpoint[Response, Union[FunctionsHttpError, FunctionsRelayError]]:
+    ) -> ResponseHandler[Response, Union[FunctionsHttpError, FunctionsRelayError]]:
         """Invokes a function
 
         Parameters
@@ -128,7 +151,7 @@ def invoke(
         request = self._invoke_options_to_request(
             function_name, body, region, headers, method
         )
-        return ServerEndpoint(
+        return ResponseHandler(
             request=request,
             on_success=lambda response: response,
             on_failure=on_error_response,
diff --git a/src/utils/pyproject.toml b/src/utils/pyproject.toml
@@ -28,7 +28,6 @@ documentation = "https://github.com/supabase/supabase-py/tree/main/src/utils"
 changelog = "https://github.com/supabase/supabase-py/tree/main/CHANGELOG.md"
 
 [tool.mypy]
-python_version = "3.9"
 check_untyped_defs = true
 allow_redefinition = true
 follow_untyped_imports = true # for deprecation module that does not have stubs
diff --git a/src/utils/src/supabase_utils/http.py b/src/utils/src/supabase_utils/http.py
@@ -19,9 +19,11 @@
     Headers,
     HTTPStatusError,
     QueryParams,
-    Request,
     Response,
 )
+from httpx import (
+    Request as HttpxRequest,
+)
 from pydantic import BaseModel, TypeAdapter
 from typing_extensions import Concatenate, ParamSpec
 from yarl import URL
@@ -32,51 +34,77 @@
 
 
 @dataclass
-class EndpointRequest:
-    method: HTTPRequestMethod
+class EmptyRequest:
     path: List[str]
-    body: Optional[bytes] = None
-    headers: Headers = field(default_factory=Headers)
-    query_params: QueryParams = field(default_factory=QueryParams)
+    method: HTTPRequestMethod
+    headers: Headers = field(default_factory=Headers, kw_only=True)
+    query_params: QueryParams = field(default_factory=QueryParams, kw_only=True)
+
+    def to_request(self, base_url: URL) -> HttpxRequest:
+        return HttpxRequest(
+            method=self.method,
+            url=str(base_url.joinpath(*self.path)),
+            headers=self.headers,
+            params=self.query_params,
+        )
+
+
+@dataclass
+class BytesRequest(EmptyRequest):
+    body: bytes
 
-    def bytes(self, bs: bytes) -> "EndpointRequest":
+    def to_request(self, base_url: URL) -> HttpxRequest:
         self.headers["Content-Type"] = "application/octet-stream"
-        self.body = bs
-        return self
+        return HttpxRequest(
+            method=self.method,
+            url=str(base_url.joinpath(*self.path)),
+            headers=self.headers,
+            params=self.query_params,
+            content=self.body,
+        )
 
-    def plain_text(self, text: str) -> "EndpointRequest":
-        self.headers["Content-Type"] = "text/plain; charset=utf-8"
-        self.body = text.encode("utf-8")
-        return self
 
-    def model(self, model: BaseModel) -> "EndpointRequest":
+@dataclass
+class JSONRequest(EmptyRequest):
+    body: Union[JSON, BaseModel]
+    exclude_none: bool = True
+
+    def to_request(self, base_url: URL) -> HttpxRequest:
+        if isinstance(self.body, BaseModel):
+            content = self.body.__pydantic_serializer__.to_json(
+                self.body, exclude_none=self.exclude_none
+            )
+        else:
+            content = JSONParser.dump_json(self.body)
         self.headers["Content-Type"] = "application/json"
-        self.body = model.__pydantic_serializer__.to_json(model)
-        return self
+        return HttpxRequest(
+            method=self.method,
+            url=str(base_url.joinpath(*self.path)),
+            headers=self.headers,
+            params=self.query_params,
+            content=content,
+        )
 
-    def json(self, json: JSON) -> "EndpointRequest":
-        self.headers["Content-Type"] = "application/json"
-        self.body = JSONParser.dump_json(json)
-        return self
 
-    def query_param(self, key: str, value: str) -> "EndpointRequest":
-        self.query_params = self.query_params.set(key, value)
-        return self
+@dataclass
+class TextRequest(EmptyRequest):
+    text: str
 
-    def to_request(self, base_url: URL) -> Request:
-        return Request(
+    def to_request(self, base_url: URL) -> HttpxRequest:
+        self.headers["Content-Type"] = "text/plain; charset=utf-8"
+        return HttpxRequest(
             method=self.method,
             url=str(base_url.joinpath(*self.path)),
             headers=self.headers,
             params=self.query_params,
-            content=self.body,
+            content=self.text.encode("utf-8"),
         )
 
 
 T = TypeVar("T", covariant=True)
 
 
-class FromHTTPResponse(Protocol[T]):
+class FromHttpxResponse(Protocol[T]):
     def __call__(self, response: Response) -> T: ...
 
 
@@ -86,7 +114,7 @@ def __call__(self, response: Response) -> T: ...
 Model = TypeVar("Model", bound=BaseModel)
 
 
-def validate_model(model: type[Model]) -> FromHTTPResponse[Model]:
+def validate_model(model: type[Model]) -> FromHttpxResponse[Model]:
     def from_response(response: Response) -> Model:
         return model.model_validate_json(response.content)
 
@@ -96,49 +124,53 @@ def from_response(response: Response) -> Model:
 Inner = TypeVar("Inner")
 
 
-def validate_adapter(adapter: TypeAdapter[Inner]) -> FromHTTPResponse[Inner]:
+def validate_adapter(adapter: TypeAdapter[Inner]) -> FromHttpxResponse[Inner]:
     def from_response(response: Response) -> Inner:
         return adapter.validate_json(response.content)
 
     return from_response
 
 
+class ToHttpxRequest(Protocol):
+    def to_request(self, base_url: URL) -> HttpxRequest: ...
+
+
 @dataclass
-class ServerEndpoint(Generic[Success, Failure]):
-    request: EndpointRequest
-    on_success: FromHTTPResponse[Success]
-    on_failure: FromHTTPResponse[Failure]
+class ResponseHandler(Generic[Success, Failure]):
+    request: ToHttpxRequest
+    on_success: FromHttpxResponse[Success]
+    on_failure: FromHttpxResponse[Failure]
 
 
 class SyncExecutor:
     def __init__(self, session: Client) -> None:
         self.session = session
 
     def communicate(
-        self, base_url: URL, endpoint: ServerEndpoint[Success, Failure]
+        self, base_url: URL, handler: ResponseHandler[Success, Failure]
     ) -> Success:
-        response = self.session.send(endpoint.request.to_request(base_url))
+        response = self.session.send(handler.request.to_request(base_url))
         try:
             response.raise_for_status()
-            return endpoint.on_success(response)
+            return handler.on_success(response)
         except HTTPStatusError:
-            raise endpoint.on_failure(response) from None
+            raise handler.on_failure(response) from None
 
 
 class AsyncExecutor:
     def __init__(self, session: AsyncClient) -> None:
         self.session = session
 
     async def communicate(
-        self, base_url: URL, endpoint: ServerEndpoint[Success, Failure]
+        self, base_url: URL, handler: ResponseHandler[Success, Failure]
     ) -> Success:
-        request = endpoint.request.to_request(base_url)
+        request = handler.request.to_request(base_url)
         response = await self.session.send(request)
         try:
             response.raise_for_status()
-            return endpoint.on_success(response)
+            return handler.on_success(response)
         except HTTPStatusError:
-            raise endpoint.on_failure(response) from None
+            raise handler.on_failure(response) from None
 
 
 Params = ParamSpec("Params")
@@ -151,8 +183,8 @@ class HasExecutor(Protocol[Executor]):
 
 
 @dataclass
-class http_endpoint(Generic[Params, Success, Failure]):
-    method: Callable[Concatenate[Any, Params], ServerEndpoint[Success, Failure]]
+class http_request(Generic[Params, Success, Failure]):
+    method: Callable[Concatenate[Any, Params], ResponseHandler[Success, Failure]]
 
     @overload
     def __get__(
