From c8dd59768acd1f73936d85b97657db3e26ac34eb Mon Sep 17 00:00:00 2001 From: Fanis Tharropoulos Date: Fri, 20 Nov 2026 13:32:36 +0200 Subject: [PATCH 1/2] feat(documents): add a streaming document export --- src/typesense/async_/api_call.py | 181 +++- src/typesense/async_/documents.py | 34 + src/typesense/async_/stream.py | 198 ++++- src/typesense/configuration.py | 23 +- src/typesense/jsonl.py | 65 ++ src/typesense/sync/api_call.py | 181 +++- src/typesense/sync/documents.py | 34 + src/typesense/sync/stream.py | 198 ++++- src/typesense/types/document.py | 2 + tests/export_stream_async_test.py | 1033 +++++++++++++++++++++++ tests/export_stream_integration_test.py | 143 ++++ tests/export_stream_test.py | 895 ++++++++++++++++++++ tests/jsonl_test.py | 76 ++ tests/stream_async_test.py | 24 + tests/stream_test.py | 28 + tests/utils/backends.py | 129 +++ tests/utils/streaming.py | 4 + utils/run-unasync.py | 2 + 18 files changed, 3179 insertions(+), 71 deletions(-) create mode 100644 src/typesense/jsonl.py create mode 100644 tests/export_stream_async_test.py create mode 100644 tests/export_stream_integration_test.py create mode 100644 tests/export_stream_test.py create mode 100644 tests/jsonl_test.py create mode 100644 tests/utils/backends.py diff --git a/src/typesense/async_/api_call.py b/src/typesense/async_/api_call.py index 73b7c3f..43c9e94 100644 --- a/src/typesense/async_/api_call.py +++ b/src/typesense/async_/api_call.py @@ -59,7 +59,7 @@ backend_errors, verify_option, ) -from .stream import AsyncSearchStream +from .stream import AsyncExportStream, AsyncSearchStream from typesense.node_manager import NodeManager from typesense.request_handler import RequestHandler, _QueryParams @@ -69,6 +69,7 @@ import typing_extensions as typing TEntityDict = typing.TypeVar("TEntityDict") +TStream = typing.TypeVar("TStream") TParams = typing.TypeVar("TParams", bound=typing.Mapping[str, object]) TBody = typing.TypeVar( "TBody", bound=typing.Union[str, bytes, typing.Mapping[str, typing.Any]] @@ -184,6 +185,7 @@ def __init__( config.max_concurrent_requests, ) self._owns_client = http_client is None + self._export_limit = AsyncConcurrencyLimit(self._max_open_exports(config)) if http_client is not None: if not isinstance(http_client, ASYNC_CLIENT_TYPES): raise TypeError( @@ -203,6 +205,25 @@ def __init__( verify=verify_option(config.verify), ) + def _max_open_exports(self, config: Configuration) -> typing.Optional[int]: + """ + Return how many exports may be open at once, or ``None`` for no limit. + + An open export keeps a connection but not a concurrency slot, so exports + get the connections the slots cannot use. There is no limit without + ``max_concurrent_requests``, or when the pool is unlimited or belongs to a + client passed in by the caller. When the slots alone can fill the pool, one + export at a time is still allowed, which can leave a request short of a + connection. + """ + max_concurrent_requests = config.max_concurrent_requests + max_connections = config.max_connections + if max_concurrent_requests is None or max_connections is None: + return None + if not self._owns_client: + return None + return max(max_connections - max_concurrent_requests, 1) + async def __aenter__(self) -> "AsyncApiCall": """Async context manager entry.""" return self @@ -588,22 +609,62 @@ async def stream( AsyncSearchStream[TEntityDict]: The open stream. """ return await self._execute_stream_request( - method, endpoint, - entity_type, + lambda node, url, request_kwargs: self._open_search_stream( + method, + node, + url, + entity_type, + **request_kwargs, + ), params=params, data=body, ) + async def export_stream( + self, + endpoint: str, + params: typing.Union[TParams, None] = None, + *, + compress: bool = False, + ) -> AsyncExportStream: + """ + Open a document export as a stream. + + Failing nodes are retried like any other request until the response + headers arrive. Errors after that are raised while reading the stream and + are not retried, since part of the export has already been read. + + Args: + endpoint (str): The export endpoint to call. + params (Union[TParams, None], optional): Query parameters for the request. + compress (bool): Whether to let the server compress the response. + + Returns: + AsyncExportStream: The open stream. + """ + return await self._execute_stream_request( + endpoint, + lambda node, url, request_kwargs: self._open_export_stream( + node, + url, + compress, + **request_kwargs, + ), + params=params, + ) + async def _execute_stream_request( self, - method: str, endpoint: str, - entity_type: typing.Type[TEntityDict], + open_stream: typing.Callable[ + [Node, str, SessionFunctionKwargs[TParams, TBody]], + typing.Awaitable[TStream], + ], last_exception: typing.Union[None, Exception] = None, num_retries: int = 0, **kwargs: typing.Unpack[SessionFunctionKwargs[TParams, TBody]], - ) -> AsyncSearchStream[TEntityDict]: + ) -> TStream: """Open a streaming request, failing over to other nodes like ``_execute_request``.""" if num_retries > self.config.num_retries: if last_exception: @@ -613,9 +674,7 @@ async def _execute_stream_request( node, url, request_kwargs = self._prepare_request_params(endpoint, **kwargs) try: - return await self._open_stream( - method, node, url, entity_type, **request_kwargs - ) + return await open_stream(node, url, request_kwargs) except _CLIENT_ERRORS: raise except _SERVER_ERRORS as server_error: @@ -623,15 +682,14 @@ async def _execute_stream_request( if num_retries < self.config.num_retries: await asyncio.sleep(self.config.retry_interval_seconds) return await self._execute_stream_request( - method, endpoint, - entity_type, + open_stream, last_exception=server_error, num_retries=num_retries + 1, **kwargs, ) - async def _open_stream( + async def _open_search_stream( self, method: str, node: Node, @@ -640,15 +698,79 @@ async def _open_stream( **kwargs: typing.Unpack[SessionFunctionKwargs[TParams, TBody]], ) -> AsyncSearchStream[TEntityDict]: """ - Send a streaming request to `node` and return the stream once headers arrive. + Send a streaming search to `node` and return the stream once headers arrive. The stream holds a concurrency slot until it is closed. Reads use ``stream_read_timeout_seconds``, since the first piece of an answer only arrives once the LLM starts generating it. """ request_kwargs = self.request_handler.build_request_kwargs(**kwargs) - headers = request_kwargs.get("headers", {}) - headers["Accept"] = "text/event-stream" + request_kwargs.setdefault("headers", {})["Accept"] = "text/event-stream" + response_context = self._stream_context(method, url, request_kwargs) + + # Owns the concurrency slot and the response until the stream is closed. + exit_stack = AsyncExitStack() + await self._concurrency_limit.acquire() + exit_stack.callback(self._concurrency_limit.release) + try: + response = await self._enter_stream(exit_stack, response_context) + except BaseException: + await exit_stack.aclose() + raise + + self.node_manager.set_node_health(node, is_healthy=True) + return AsyncSearchStream(response, exit_stack) + + async def _open_export_stream( + self, + node: Node, + url: str, + compress: bool, + **kwargs: typing.Unpack[SessionFunctionKwargs[TParams, TBody]], + ) -> AsyncExportStream: + """ + Send an export request to `node` and return the stream once headers arrive. + + The concurrency slot is held only while opening, so that a request made + while reading the export does not have to wait for the export to finish. + The stream keeps its place among the open exports until it is closed. + + Unless ``compress`` is set the export is requested uncompressed, because + the server compresses on the thread that handles every other request. An + ``Accept-Encoding`` in ``additional_headers`` is left as it is. + """ + request_kwargs = self.request_handler.build_request_kwargs(**kwargs) + headers = request_kwargs.setdefault("headers", {}) + if not compress and "accept-encoding" not in map(str.lower, headers): + headers["Accept-Encoding"] = "identity" + response_context = self._stream_context("GET", url, request_kwargs) + + # Closes the response, then gives back the export's place. + export = AsyncExitStack() + await self._export_limit.acquire() + export.callback(self._export_limit.release) + try: + async with self._concurrency_limit: + response = await self._enter_stream(export, response_context) + except BaseException: + await export.aclose() + raise + + # A single entry, so that a second close cannot give back the place while + # the first is still closing the response. + exit_stack = AsyncExitStack() + await exit_stack.enter_async_context(export) + + self.node_manager.set_node_health(node, is_healthy=True) + return AsyncExportStream(response, exit_stack) + + def _stream_context( + self, + method: str, + url: str, + request_kwargs: SessionFunctionKwargs[TParams, TBody], + ) -> typing.AsyncContextManager[ResponseType]: + """Return the context manager that sends a streaming request.""" timeout = self._client.timeout # Annotated so httpx and httpx2 responses unify as ``ResponseType``. response_context: typing.AsyncContextManager[ResponseType] = ( @@ -660,7 +782,7 @@ async def _open_stream( request_kwargs.get("params"), ), content=request_kwargs.get("content"), - headers=headers, + headers=request_kwargs.get("headers"), timeout=( timeout.connect, self.config.stream_read_timeout_seconds, @@ -669,22 +791,19 @@ async def _open_stream( ), ) ) + return response_context - # Owns the concurrency slot and the response until the stream is closed. - exit_stack = AsyncExitStack() - await self._concurrency_limit.acquire() - exit_stack.callback(self._concurrency_limit.release) - try: - response = await exit_stack.enter_async_context(response_context) - if response.status_code < 200 or response.status_code >= 300: - await response.aread() - self.request_handler.raise_for_status(response) - except BaseException: - await exit_stack.aclose() - raise - - self.node_manager.set_node_health(node, is_healthy=True) - return AsyncSearchStream(response, exit_stack) + async def _enter_stream( + self, + exit_stack: AsyncExitStack, + response_context: typing.AsyncContextManager[ResponseType], + ) -> ResponseType: + """Send the request, raising the matching error for a non-2xx response.""" + response = await exit_stack.enter_async_context(response_context) + if response.status_code < 200 or response.status_code >= 300: + await response.aread() + self.request_handler.raise_for_status(response) + return response def _prepare_request_params( self, diff --git a/src/typesense/async_/documents.py b/src/typesense/async_/documents.py index 2b91cd5..2f155ad 100644 --- a/src/typesense/async_/documents.py +++ b/src/typesense/async_/documents.py @@ -22,6 +22,7 @@ from .api_call import AsyncApiCall from .document import AsyncDocument from .stream import ( + AsyncExportStream, AsyncSearchStream, consume_stream, notify_error, @@ -362,6 +363,39 @@ async def export( ) return api_response + async def export_stream( + self, + export_parameters: typing.Union[DocumentExportParameters, None] = None, + *, + compress: bool = False, + ) -> AsyncExportStream: + """ + Export documents from the collection without loading them all into memory. + + Iterate over the returned stream for the raw JSONL lines, or call its + ``aiter_bytes`` for the bytes. Use the stream as a context manager so the + connection is released if you stop early. + + Failing nodes are retried only until the response headers arrive. After + that, errors are raised from httpx or httpx2 while reading, and the export + has to be started again. + + Args: + export_parameters (Union[DocumentExportParameters, None], optional): + Parameters for the export operation. + compress (bool): Whether to let the server compress the response. This + saves bandwidth, but the server compresses on the thread that + handles all other requests, which delays them. Defaults to False. + + Returns: + AsyncExportStream: The open stream. + """ + return await self.api_call.export_stream( + self._endpoint_path("export"), + params=export_parameters, + compress=compress, + ) + async def search(self, search_parameters: SearchParameters) -> SearchResponse[TDoc]: """ Search for documents in the collection. diff --git a/src/typesense/async_/stream.py b/src/typesense/async_/stream.py index 51b9a1a..7c6f2f5 100644 --- a/src/typesense/async_/stream.py +++ b/src/typesense/async_/stream.py @@ -1,5 +1,5 @@ """ -Streamed conversational search responses. +Streamed conversational search responses and document exports. With ``conversation_stream`` enabled, Typesense sends the LLM's answer as server-sent events while it is generated, then the full search response: @@ -11,14 +11,19 @@ ``AsyncSearchStream`` yields the answer pieces as ``MessageChunk`` dicts and keeps the final event as the search response, returned by ``get_final_response``. + +``AsyncExportStream`` reads a document export, one JSONL line or one chunk of bytes +at a time, so that a large collection never has to fit in memory. """ import sys +from collections import deque from contextlib import AsyncExitStack from types import TracebackType from typesense.exceptions import TypesenseClientError from typesense.http_backend import ResponseType +from typesense.jsonl import JSONLSplitter from typesense.sse import SSEDecoder, ServerSentEvent, aiter_events from typesense.types.document import MessageChunk, StreamConfig, StreamConfigBuilder @@ -31,6 +36,12 @@ _DONE = "[DONE]" +_EXPORT_CLOSED = "This export stream is closed." +_EXPORT_FAILED = "This export stream failed while reading. Start a new export." +_EXPORT_CLAIMED = ( + "This export stream is already being read. Read its lines or its bytes, not both." +) + class AsyncSearchStream(typing.Generic[TFinal]): """ @@ -168,6 +179,191 @@ def _missing_final_message(self) -> str: return f"{message} {remainder}" if remainder else message +class AsyncExportChunks: + """ + The decoded bytes of an export, returned by ``AsyncExportStream.aiter_bytes``. + + An httpx iterator simply ends once it has been closed or has failed, which would + make a partial export look complete. Reading from this one raises instead. + """ + + def __init__( + self, + chunks: typing.AsyncIterator[bytes], + exit_stack: AsyncExitStack, + ) -> None: + """ + Initialize the iterator. + + Args: + chunks: The response's decoded bytes. Holding on to this iterator + matters, because dropping it closes the connection. + exit_stack (AsyncExitStack): Closes the response and gives up the + export's place once the body has ended or failed. + """ + self._chunks = chunks + self._exit_stack = exit_stack + self._unreadable: typing.Optional[str] = None + + def __aiter__(self) -> typing.Self: + """Return the iterator itself; it can be iterated only once.""" + return self + + async def __anext__(self) -> bytes: + """Return the next chunk of the body.""" + self._raise_if_unreadable() + try: + return await self._chunks.__anext__() + except BaseException as error: + if isinstance(error, Exception): + # Closing the stream ends or breaks a read that is in progress. + self._raise_if_unreadable() + if isinstance(error, StopAsyncIteration): + await self._exit_stack.aclose() + else: + await self._fail() + raise + + async def _fail(self) -> None: + """Make further reads raise, and give up the export's place.""" + self._unreadable = self._unreadable or _EXPORT_FAILED + await self._exit_stack.aclose() + + def _mark_closed(self) -> None: + """Make further reads raise.""" + self._unreadable = _EXPORT_CLOSED + + def _raise_if_unreadable(self) -> None: + """Raise if the stream was closed or a read has failed.""" + if self._unreadable is not None: + raise TypesenseClientError(self._unreadable) + + +class AsyncExportStream: + """ + An open document export. + + Iterate over it for the raw JSONL lines, as ``str`` without the line feed, or + call ``aiter_bytes`` for the decoded bytes. An export can be read only one of + these ways, and only once. Use it as a context manager, or call ``aclose``: + a stream abandoned before its end keeps its place among the open exports. + + Errors while reading are raised as they are, from httpx or httpx2, and nothing + is retried. A failed export has to be started again. + + Attributes: + response (httpx.Response | httpx2.Response): The underlying response. + """ + + def __init__( + self, + response: ResponseType, + exit_stack: AsyncExitStack, + ) -> None: + """ + Initialize the stream. + + Args: + response (httpx.Response | httpx2.Response): A successful response + opened with ``stream=True``. + exit_stack (AsyncExitStack): Closes the response and gives up the + export's place when the stream is closed. + """ + self.response = response + self._exit_stack = exit_stack + self._closed = False + self._chunks: typing.Optional[AsyncExportChunks] = None + self._line_chunks: typing.Optional[AsyncExportChunks] = None + self._splitter = JSONLSplitter() + self._lines: typing.Deque[bytes] = deque() + + def __aiter__(self) -> typing.Self: + """Start reading lines, or carry on from the last line read.""" + self._claim_lines() + return self + + async def __anext__(self) -> str: + """Return the next line, without its line feed.""" + chunks = self._claim_lines() + while not self._lines: + try: + chunk = await chunks.__anext__() + except StopAsyncIteration: + # Only a complete body gets here, so this is a whole last line. + self._lines.extend(self._splitter.flush()) + if not self._lines: + raise + else: + self._lines.extend(self._splitter.feed(chunk)) + line = self._lines.popleft() + try: + return line.decode("utf-8") + except UnicodeDecodeError: + # Dropping the lines already read makes every further read raise. + self._lines.clear() + await chunks._fail() + raise + + async def __aenter__(self) -> typing.Self: + """Enter the context manager.""" + return self + + async def __aexit__( + self, + exc_type: typing.Optional[typing.Type[BaseException]], + exc_val: typing.Optional[BaseException], + exc_tb: typing.Optional[TracebackType], + ) -> None: + """Close the stream.""" + await self.aclose() + + def aiter_bytes( + self, + chunk_size: typing.Optional[int] = None, + ) -> AsyncExportChunks: + """ + Read the export as bytes, for example to write it to a file. + + Args: + chunk_size (int | None): The size of each chunk. Defaults to the sizes + the data arrives in. + + Returns: + AsyncExportChunks: The decoded bytes of the export. + + Raises: + TypesenseClientError: If the stream is closed or already being read. + """ + return self._claim_chunks(chunk_size) + + async def aclose(self) -> None: + """Close the response without reading the rest of it. Safe to call twice.""" + self._closed = True + if self._chunks is not None: + self._chunks._mark_closed() + await self._exit_stack.aclose() + + def _claim_lines(self) -> AsyncExportChunks: + """Return the chunks that lines are read from.""" + if self._closed: + raise TypesenseClientError(_EXPORT_CLOSED) + if self._line_chunks is None: + self._line_chunks = self._claim_chunks(None) + return self._line_chunks + + def _claim_chunks(self, chunk_size: typing.Optional[int]) -> AsyncExportChunks: + """Start reading the body, which can be done only once.""" + if self._closed: + raise TypesenseClientError(_EXPORT_CLOSED) + if self._chunks is not None: + raise TypesenseClientError(_EXPORT_CLAIMED) + self._chunks = AsyncExportChunks( + self.response.aiter_bytes(chunk_size), + self._exit_stack, + ) + return self._chunks + + def resolve_stream_config( stream_config: typing.Union[ StreamConfig[TFinal], diff --git a/src/typesense/configuration.py b/src/typesense/configuration.py index 0d2b0ab..8735877 100644 --- a/src/typesense/configuration.py +++ b/src/typesense/configuration.py @@ -92,8 +92,11 @@ class ConfigDict(typing.TypedDict): ``connection_timeout_seconds`` makes the httpcore connection leak (encode/httpcore#1093) more likely under load. - max_connections (int): The maximum number of connections in the pool. - Defaults to 100. + max_connections (int): The maximum number of connections in the pool. With + ``max_concurrent_requests``, it also limits open streaming exports to + ``max_connections - max_concurrent_requests``, or one if that is not + positive, when an open export can leave a request short of a connection. + Further exports wait for one to close. Defaults to 100. max_keepalive_connections (int): The maximum number of idle connections kept alive in the pool. Defaults to 20. @@ -101,13 +104,16 @@ class ConfigDict(typing.TypedDict): max_concurrent_requests (int): The maximum number of requests in flight at once; further requests wait for a slot. Keep it below ``max_connections`` so a burst of slow requests cannot exhaust the pool. + A streaming export holds a slot only until its response headers arrive. Defaults to no limit. stream_read_timeout_seconds (float): How long a streaming conversation - search waits for the next chunk before raising ``httpx.ReadTimeout``. - Replaces the read timeout for streaming requests only, since the first - chunk arrives only once the LLM starts answering. Defaults to 60, the - server's own limit for an LLM response. + search or document export waits for the next chunk before raising + ``httpx.ReadTimeout``. Replaces the read timeout for streaming requests + only, since the first chunk arrives only once the LLM starts answering + or the server has found the documents to export. Time spent between + reads does not count. Defaults to 60, the server's own limit for an LLM + response. """ nodes: typing.List[typing.Union[str, NodeConfigDict]] @@ -276,7 +282,10 @@ def __init__( "pool_timeout_seconds", self.connection_timeout_seconds, ) - self.max_connections = config_dict.get("max_connections", 100) + self.max_connections: typing.Optional[int] = config_dict.get( + "max_connections", + 100, + ) self.max_keepalive_connections = config_dict.get( "max_keepalive_connections", 20, diff --git a/src/typesense/jsonl.py b/src/typesense/jsonl.py new file mode 100644 index 0000000..db5eac7 --- /dev/null +++ b/src/typesense/jsonl.py @@ -0,0 +1,65 @@ +""" +Line splitting for JSONL document exports. + +Lines are split on the ``\\n`` byte before anything is decoded. ``str.splitlines``, +and httpx's ``iter_lines`` with it, also split on U+2028, U+2029 and U+0085, which +JSON allows unescaped inside strings, so they would break valid documents apart. +Lines are otherwise left as they arrived: ``\\r`` and blank lines are kept. +""" + +import sys + +if sys.version_info >= (3, 11): + import typing +else: + import typing_extensions as typing + + +class JSONLSplitter: + """Incremental splitter that turns response bytes into lines.""" + + def __init__(self) -> None: + """Initialize an empty splitter.""" + # Kept as pieces and joined once per line. Appending to a bytes buffer + # copies it every time, which is quadratic for a large document. + self._pending: typing.List[bytes] = [] + + def feed(self, chunk: bytes) -> typing.List[bytes]: + """ + Split a chunk of the response body. + + Args: + chunk (bytes): The next bytes read from the response. + + Returns: + List[bytes]: The lines completed by this chunk, without their ``\\n``. + """ + lines: typing.List[bytes] = [] + start = 0 + while (end := chunk.find(b"\n", start)) != -1: + if self._pending: + self._pending.append(chunk[start:end]) + lines.append(b"".join(self._pending)) + self._pending.clear() + else: + lines.append(chunk[start:end]) + start = end + 1 + if start < len(chunk): + self._pending.append(chunk[start:]) + return lines + + def flush(self) -> typing.List[bytes]: + """ + Return the unterminated last line. Call this only after a complete body. + + Typesense does not end an export with ``\\n``, so the last document is + always returned here. + + Returns: + List[bytes]: The last line, or nothing if the body ended with ``\\n``. + """ + if not self._pending: + return [] + line = b"".join(self._pending) + self._pending.clear() + return [line] diff --git a/src/typesense/sync/api_call.py b/src/typesense/sync/api_call.py index 817c578..80fb468 100644 --- a/src/typesense/sync/api_call.py +++ b/src/typesense/sync/api_call.py @@ -59,7 +59,7 @@ backend_errors, verify_option, ) -from .stream import SearchStream +from .stream import ExportStream, SearchStream from typesense.node_manager import NodeManager from typesense.request_handler import RequestHandler, _QueryParams @@ -69,6 +69,7 @@ import typing_extensions as typing TEntityDict = typing.TypeVar("TEntityDict") +TStream = typing.TypeVar("TStream") TParams = typing.TypeVar("TParams", bound=typing.Mapping[str, object]) TBody = typing.TypeVar( "TBody", bound=typing.Union[str, bytes, typing.Mapping[str, typing.Any]] @@ -184,6 +185,7 @@ def __init__( config.max_concurrent_requests, ) self._owns_client = http_client is None + self._export_limit = ConcurrencyLimit(self._max_open_exports(config)) if http_client is not None: if not isinstance(http_client, CLIENT_TYPES): raise TypeError( @@ -203,6 +205,25 @@ def __init__( verify=verify_option(config.verify), ) + def _max_open_exports(self, config: Configuration) -> typing.Optional[int]: + """ + Return how many exports may be open at once, or ``None`` for no limit. + + An open export keeps a connection but not a concurrency slot, so exports + get the connections the slots cannot use. There is no limit without + ``max_concurrent_requests``, or when the pool is unlimited or belongs to a + client passed in by the caller. When the slots alone can fill the pool, one + export at a time is still allowed, which can leave a request short of a + connection. + """ + max_concurrent_requests = config.max_concurrent_requests + max_connections = config.max_connections + if max_concurrent_requests is None or max_connections is None: + return None + if not self._owns_client: + return None + return max(max_connections - max_concurrent_requests, 1) + def __enter__(self) -> "ApiCall": """Async context manager entry.""" return self @@ -588,22 +609,62 @@ def stream( SearchStream[TEntityDict]: The open stream. """ return self._execute_stream_request( - method, endpoint, - entity_type, + lambda node, url, request_kwargs: self._open_search_stream( + method, + node, + url, + entity_type, + **request_kwargs, + ), params=params, data=body, ) + def export_stream( + self, + endpoint: str, + params: typing.Union[TParams, None] = None, + *, + compress: bool = False, + ) -> ExportStream: + """ + Open a document export as a stream. + + Failing nodes are retried like any other request until the response + headers arrive. Errors after that are raised while reading the stream and + are not retried, since part of the export has already been read. + + Args: + endpoint (str): The export endpoint to call. + params (Union[TParams, None], optional): Query parameters for the request. + compress (bool): Whether to let the server compress the response. + + Returns: + ExportStream: The open stream. + """ + return self._execute_stream_request( + endpoint, + lambda node, url, request_kwargs: self._open_export_stream( + node, + url, + compress, + **request_kwargs, + ), + params=params, + ) + def _execute_stream_request( self, - method: str, endpoint: str, - entity_type: typing.Type[TEntityDict], + open_stream: typing.Callable[ + [Node, str, SessionFunctionKwargs[TParams, TBody]], + TStream, + ], last_exception: typing.Union[None, Exception] = None, num_retries: int = 0, **kwargs: typing.Unpack[SessionFunctionKwargs[TParams, TBody]], - ) -> SearchStream[TEntityDict]: + ) -> TStream: """Open a streaming request, failing over to other nodes like ``_execute_request``.""" if num_retries > self.config.num_retries: if last_exception: @@ -613,9 +674,7 @@ def _execute_stream_request( node, url, request_kwargs = self._prepare_request_params(endpoint, **kwargs) try: - return self._open_stream( - method, node, url, entity_type, **request_kwargs - ) + return open_stream(node, url, request_kwargs) except _CLIENT_ERRORS: raise except _SERVER_ERRORS as server_error: @@ -623,15 +682,14 @@ def _execute_stream_request( if num_retries < self.config.num_retries: time.sleep(self.config.retry_interval_seconds) return self._execute_stream_request( - method, endpoint, - entity_type, + open_stream, last_exception=server_error, num_retries=num_retries + 1, **kwargs, ) - def _open_stream( + def _open_search_stream( self, method: str, node: Node, @@ -640,15 +698,79 @@ def _open_stream( **kwargs: typing.Unpack[SessionFunctionKwargs[TParams, TBody]], ) -> SearchStream[TEntityDict]: """ - Send a streaming request to `node` and return the stream once headers arrive. + Send a streaming search to `node` and return the stream once headers arrive. The stream holds a concurrency slot until it is closed. Reads use ``stream_read_timeout_seconds``, since the first piece of an answer only arrives once the LLM starts generating it. """ request_kwargs = self.request_handler.build_request_kwargs(**kwargs) - headers = request_kwargs.get("headers", {}) - headers["Accept"] = "text/event-stream" + request_kwargs.setdefault("headers", {})["Accept"] = "text/event-stream" + response_context = self._stream_context(method, url, request_kwargs) + + # Owns the concurrency slot and the response until the stream is closed. + exit_stack = ExitStack() + self._concurrency_limit.acquire() + exit_stack.callback(self._concurrency_limit.release) + try: + response = self._enter_stream(exit_stack, response_context) + except BaseException: + exit_stack.close() + raise + + self.node_manager.set_node_health(node, is_healthy=True) + return SearchStream(response, exit_stack) + + def _open_export_stream( + self, + node: Node, + url: str, + compress: bool, + **kwargs: typing.Unpack[SessionFunctionKwargs[TParams, TBody]], + ) -> ExportStream: + """ + Send an export request to `node` and return the stream once headers arrive. + + The concurrency slot is held only while opening, so that a request made + while reading the export does not have to wait for the export to finish. + The stream keeps its place among the open exports until it is closed. + + Unless ``compress`` is set the export is requested uncompressed, because + the server compresses on the thread that handles every other request. An + ``Accept-Encoding`` in ``additional_headers`` is left as it is. + """ + request_kwargs = self.request_handler.build_request_kwargs(**kwargs) + headers = request_kwargs.setdefault("headers", {}) + if not compress and "accept-encoding" not in map(str.lower, headers): + headers["Accept-Encoding"] = "identity" + response_context = self._stream_context("GET", url, request_kwargs) + + # Closes the response, then gives back the export's place. + export = ExitStack() + self._export_limit.acquire() + export.callback(self._export_limit.release) + try: + with self._concurrency_limit: + response = self._enter_stream(export, response_context) + except BaseException: + export.close() + raise + + # A single entry, so that a second close cannot give back the place while + # the first is still closing the response. + exit_stack = ExitStack() + exit_stack.enter_context(export) + + self.node_manager.set_node_health(node, is_healthy=True) + return ExportStream(response, exit_stack) + + def _stream_context( + self, + method: str, + url: str, + request_kwargs: SessionFunctionKwargs[TParams, TBody], + ) -> typing.ContextManager[ResponseType]: + """Return the context manager that sends a streaming request.""" timeout = self._client.timeout # Annotated so httpx and httpx2 responses unify as ``ResponseType``. response_context: typing.ContextManager[ResponseType] = ( @@ -660,7 +782,7 @@ def _open_stream( request_kwargs.get("params"), ), content=request_kwargs.get("content"), - headers=headers, + headers=request_kwargs.get("headers"), timeout=( timeout.connect, self.config.stream_read_timeout_seconds, @@ -669,22 +791,19 @@ def _open_stream( ), ) ) + return response_context - # Owns the concurrency slot and the response until the stream is closed. - exit_stack = ExitStack() - self._concurrency_limit.acquire() - exit_stack.callback(self._concurrency_limit.release) - try: - response = exit_stack.enter_context(response_context) - if response.status_code < 200 or response.status_code >= 300: - response.read() - self.request_handler.raise_for_status(response) - except BaseException: - exit_stack.close() - raise - - self.node_manager.set_node_health(node, is_healthy=True) - return SearchStream(response, exit_stack) + def _enter_stream( + self, + exit_stack: ExitStack, + response_context: typing.ContextManager[ResponseType], + ) -> ResponseType: + """Send the request, raising the matching error for a non-2xx response.""" + response = exit_stack.enter_context(response_context) + if response.status_code < 200 or response.status_code >= 300: + response.read() + self.request_handler.raise_for_status(response) + return response def _prepare_request_params( self, diff --git a/src/typesense/sync/documents.py b/src/typesense/sync/documents.py index badd527..278002e 100644 --- a/src/typesense/sync/documents.py +++ b/src/typesense/sync/documents.py @@ -22,6 +22,7 @@ from .api_call import ApiCall from .document import Document from .stream import ( + ExportStream, SearchStream, consume_stream, notify_error, @@ -362,6 +363,39 @@ def export( ) return api_response + def export_stream( + self, + export_parameters: typing.Union[DocumentExportParameters, None] = None, + *, + compress: bool = False, + ) -> ExportStream: + """ + Export documents from the collection without loading them all into memory. + + Iterate over the returned stream for the raw JSONL lines, or call its + ``iter_bytes`` for the bytes. Use the stream as a context manager so the + connection is released if you stop early. + + Failing nodes are retried only until the response headers arrive. After + that, errors are raised from httpx or httpx2 while reading, and the export + has to be started again. + + Args: + export_parameters (Union[DocumentExportParameters, None], optional): + Parameters for the export operation. + compress (bool): Whether to let the server compress the response. This + saves bandwidth, but the server compresses on the thread that + handles all other requests, which delays them. Defaults to False. + + Returns: + ExportStream: The open stream. + """ + return self.api_call.export_stream( + self._endpoint_path("export"), + params=export_parameters, + compress=compress, + ) + def search(self, search_parameters: SearchParameters) -> SearchResponse[TDoc]: """ Search for documents in the collection. diff --git a/src/typesense/sync/stream.py b/src/typesense/sync/stream.py index bbe6f5a..bdf5da4 100644 --- a/src/typesense/sync/stream.py +++ b/src/typesense/sync/stream.py @@ -1,5 +1,5 @@ """ -Streamed conversational search responses. +Streamed conversational search responses and document exports. With ``conversation_stream`` enabled, Typesense sends the LLM's answer as server-sent events while it is generated, then the full search response: @@ -11,14 +11,19 @@ ``SearchStream`` yields the answer pieces as ``MessageChunk`` dicts and keeps the final event as the search response, returned by ``get_final_response``. + +``ExportStream`` reads a document export, one JSONL line or one chunk of bytes +at a time, so that a large collection never has to fit in memory. """ import sys +from collections import deque from contextlib import ExitStack from types import TracebackType from typesense.exceptions import TypesenseClientError from typesense.http_backend import ResponseType +from typesense.jsonl import JSONLSplitter from typesense.sse import SSEDecoder, ServerSentEvent, iter_events from typesense.types.document import MessageChunk, StreamConfig, StreamConfigBuilder @@ -31,6 +36,12 @@ _DONE = "[DONE]" +_EXPORT_CLOSED = "This export stream is closed." +_EXPORT_FAILED = "This export stream failed while reading. Start a new export." +_EXPORT_CLAIMED = ( + "This export stream is already being read. Read its lines or its bytes, not both." +) + class SearchStream(typing.Generic[TFinal]): """ @@ -168,6 +179,191 @@ def _missing_final_message(self) -> str: return f"{message} {remainder}" if remainder else message +class ExportChunks: + """ + The decoded bytes of an export, returned by ``ExportStream.iter_bytes``. + + An httpx iterator simply ends once it has been closed or has failed, which would + make a partial export look complete. Reading from this one raises instead. + """ + + def __init__( + self, + chunks: typing.Iterator[bytes], + exit_stack: ExitStack, + ) -> None: + """ + Initialize the iterator. + + Args: + chunks: The response's decoded bytes. Holding on to this iterator + matters, because dropping it closes the connection. + exit_stack (ExitStack): Closes the response and gives up the + export's place once the body has ended or failed. + """ + self._chunks = chunks + self._exit_stack = exit_stack + self._unreadable: typing.Optional[str] = None + + def __iter__(self) -> typing.Self: + """Return the iterator itself; it can be iterated only once.""" + return self + + def __next__(self) -> bytes: + """Return the next chunk of the body.""" + self._raise_if_unreadable() + try: + return self._chunks.__next__() + except BaseException as error: + if isinstance(error, Exception): + # Closing the stream ends or breaks a read that is in progress. + self._raise_if_unreadable() + if isinstance(error, StopIteration): + self._exit_stack.close() + else: + self._fail() + raise + + def _fail(self) -> None: + """Make further reads raise, and give up the export's place.""" + self._unreadable = self._unreadable or _EXPORT_FAILED + self._exit_stack.close() + + def _mark_closed(self) -> None: + """Make further reads raise.""" + self._unreadable = _EXPORT_CLOSED + + def _raise_if_unreadable(self) -> None: + """Raise if the stream was closed or a read has failed.""" + if self._unreadable is not None: + raise TypesenseClientError(self._unreadable) + + +class ExportStream: + """ + An open document export. + + Iterate over it for the raw JSONL lines, as ``str`` without the line feed, or + call ``iter_bytes`` for the decoded bytes. An export can be read only one of + these ways, and only once. Use it as a context manager, or call ``close``: + a stream abandoned before its end keeps its place among the open exports. + + Errors while reading are raised as they are, from httpx or httpx2, and nothing + is retried. A failed export has to be started again. + + Attributes: + response (httpx.Response | httpx2.Response): The underlying response. + """ + + def __init__( + self, + response: ResponseType, + exit_stack: ExitStack, + ) -> None: + """ + Initialize the stream. + + Args: + response (httpx.Response | httpx2.Response): A successful response + opened with ``stream=True``. + exit_stack (ExitStack): Closes the response and gives up the + export's place when the stream is closed. + """ + self.response = response + self._exit_stack = exit_stack + self._closed = False + self._chunks: typing.Optional[ExportChunks] = None + self._line_chunks: typing.Optional[ExportChunks] = None + self._splitter = JSONLSplitter() + self._lines: typing.Deque[bytes] = deque() + + def __iter__(self) -> typing.Self: + """Start reading lines, or carry on from the last line read.""" + self._claim_lines() + return self + + def __next__(self) -> str: + """Return the next line, without its line feed.""" + chunks = self._claim_lines() + while not self._lines: + try: + chunk = chunks.__next__() + except StopIteration: + # Only a complete body gets here, so this is a whole last line. + self._lines.extend(self._splitter.flush()) + if not self._lines: + raise + else: + self._lines.extend(self._splitter.feed(chunk)) + line = self._lines.popleft() + try: + return line.decode("utf-8") + except UnicodeDecodeError: + # Dropping the lines already read makes every further read raise. + self._lines.clear() + chunks._fail() + raise + + def __enter__(self) -> typing.Self: + """Enter the context manager.""" + return self + + def __exit__( + self, + exc_type: typing.Optional[typing.Type[BaseException]], + exc_val: typing.Optional[BaseException], + exc_tb: typing.Optional[TracebackType], + ) -> None: + """Close the stream.""" + self.close() + + def iter_bytes( + self, + chunk_size: typing.Optional[int] = None, + ) -> ExportChunks: + """ + Read the export as bytes, for example to write it to a file. + + Args: + chunk_size (int | None): The size of each chunk. Defaults to the sizes + the data arrives in. + + Returns: + ExportChunks: The decoded bytes of the export. + + Raises: + TypesenseClientError: If the stream is closed or already being read. + """ + return self._claim_chunks(chunk_size) + + def close(self) -> None: + """Close the response without reading the rest of it. Safe to call twice.""" + self._closed = True + if self._chunks is not None: + self._chunks._mark_closed() + self._exit_stack.close() + + def _claim_lines(self) -> ExportChunks: + """Return the chunks that lines are read from.""" + if self._closed: + raise TypesenseClientError(_EXPORT_CLOSED) + if self._line_chunks is None: + self._line_chunks = self._claim_chunks(None) + return self._line_chunks + + def _claim_chunks(self, chunk_size: typing.Optional[int]) -> ExportChunks: + """Start reading the body, which can be done only once.""" + if self._closed: + raise TypesenseClientError(_EXPORT_CLOSED) + if self._chunks is not None: + raise TypesenseClientError(_EXPORT_CLAIMED) + self._chunks = ExportChunks( + self.response.iter_bytes(chunk_size), + self._exit_stack, + ) + return self._chunks + + def resolve_stream_config( stream_config: typing.Union[ StreamConfig[TFinal], diff --git a/src/typesense/types/document.py b/src/typesense/types/document.py index b5cf565..927c39c 100644 --- a/src/typesense/types/document.py +++ b/src/typesense/types/document.py @@ -316,11 +316,13 @@ class DocumentExportParameters(typing.TypedDict): filter_by (str): Filter to apply to documents. include_fields (str): Fields to include in the exported documents. exclude_fields (str): Fields to exclude from the exported documents. + batch_size (int): How many documents the server reads at a time. """ filter_by: typing.NotRequired[str] include_fields: typing.NotRequired[str] exclude_fields: typing.NotRequired[str] + batch_size: typing.NotRequired[int] class RequiredSearchParameters(typing.TypedDict): diff --git a/tests/export_stream_async_test.py b/tests/export_stream_async_test.py new file mode 100644 index 0000000..361d4e8 --- /dev/null +++ b/tests/export_stream_async_test.py @@ -0,0 +1,1033 @@ +"""Tests for streaming document exports with the async client.""" + +import asyncio +import gzip +import json +import sys + +import httpx +import pytest +import respx + +from tests.utils.backends import AsyncHandler, Backend, RequestType, load_backend +from tests.utils.streaming import ( + COLLECTION_PATH, + COLLECTION_URL, + EXPORT_PATH, + EXPORT_URL, +) +from typesense.async_.api_call import AsyncApiCall +from typesense.async_.documents import AsyncDocuments +from typesense.async_.stream import AsyncExportStream +from typesense.configuration import Configuration +from typesense.exceptions import ( + ObjectNotFound, + RequestMalformed, + TypesenseClientError, +) +from typesense.http_backend import ResponseType +from typesense.types.document import DocumentSchema + +if sys.version_info >= (3, 11): + import typing +else: + import typing_extensions as typing + +TResult = typing.TypeVar("TResult") + +BODY: typing.Final = b'{"id":"1"}\n{"id":"2"}\n{"id":"3"}' +LINES: typing.Final = ['{"id":"1"}', '{"id":"2"}', '{"id":"3"}'] +WAIT_SECONDS: typing.Final = 1 +SETTLE_SECONDS: typing.Final = 0.02 + + +@pytest.fixture(name="backend", params=["httpx", "httpx2"]) +def backend_fixture(request: pytest.FixtureRequest) -> Backend: + """Return each HTTP backend that is installed.""" + name = request.param + assert isinstance(name, str) + return load_backend(name) + + +def make_api_call( + backend: Backend, + config: Configuration, + handler: AsyncHandler, +) -> AsyncApiCall: + """Return an API call that sends requests through a mock transport.""" + return AsyncApiCall(config, backend.async_client(handler)) + + +def make_documents( + backend: Backend, + config: Configuration, + handler: AsyncHandler, +) -> AsyncDocuments[DocumentSchema]: + """Return documents sent through a mock transport of ``backend``.""" + return AsyncDocuments[DocumentSchema]( + make_api_call(backend, config, handler), "books" + ) + + +async def chunked( + *chunks: bytes, + error: typing.Optional[Exception] = None, +) -> typing.AsyncIterator[bytes]: + """Yield ``chunks``, then raise ``error`` if there is one.""" + for chunk in chunks: + yield chunk + if error is not None: + raise error + + +def respond_with(backend: Backend, *chunks: bytes) -> AsyncHandler: + """Return a handler that sends ``chunks`` as a streamed export.""" + + async def handler(request: RequestType) -> ResponseType: + return backend.Response(200, content=chunked(*chunks)) + + return handler + + +def fail_with(backend: Backend, error: Exception, *chunks: bytes) -> AsyncHandler: + """Return a handler that sends ``chunks``, then fails while streaming.""" + + async def handler(request: RequestType) -> ResponseType: + return backend.Response(200, content=chunked(*chunks, error=error)) + + return handler + + +async def read_lines( + documents: AsyncDocuments[DocumentSchema], + *, + compress: bool = False, +) -> typing.List[str]: + """Open an export and return all of its lines.""" + async with await documents.export_stream(compress=compress) as stream: + return [line async for line in stream] + + +async def assert_waiting(task: "asyncio.Future[TResult]") -> None: + """Assert that ``task`` has not finished after giving it time to run.""" + await asyncio.sleep(SETTLE_SECONDS) + assert not task.done() + + +def limited_documents( + config: Configuration, + max_connections: typing.Optional[int], + max_concurrent_requests: typing.Optional[int], +) -> AsyncDocuments[DocumentSchema]: + """Return documents using the client's own connection pool.""" + config.max_connections = max_connections + config.max_concurrent_requests = max_concurrent_requests + return AsyncDocuments[DocumentSchema](AsyncApiCall(config), "books") + + +def export_response(request: httpx.Request) -> httpx.Response: + """Return a complete export, as a fresh response for every request.""" + return httpx.Response(200, content=BODY) + + +def mock_export() -> respx.Route: + """Mock the export endpoint with a complete export.""" + return respx.get(EXPORT_URL).mock(side_effect=export_response) + + +async def open_export(documents: AsyncDocuments[DocumentSchema]) -> AsyncExportStream: + """Open an export, failing the test if it has to wait.""" + return await asyncio.wait_for(documents.export_stream(), WAIT_SECONDS) + + +async def test_yields_lines_without_their_line_feed( + backend: Backend, + fake_config: Configuration, +) -> None: + """Test that the lines are complete, including the unterminated last one.""" + documents = make_documents(backend, fake_config, respond_with(backend, BODY)) + + assert await read_lines(documents) == LINES + + +async def test_sends_the_export_parameters( + backend: Backend, + fake_config: Configuration, +) -> None: + """Test that the request goes to the export endpoint with its parameters.""" + requests: typing.List[RequestType] = [] + + async def handler(request: RequestType) -> ResponseType: + requests.append(request) + return backend.Response(200, content=BODY) + + documents = make_documents(backend, fake_config, handler) + + async with await documents.export_stream( + {"filter_by": "year:>2000", "batch_size": 500}, + ): + pass + + assert requests[0].method == "GET" + assert requests[0].url.path == EXPORT_PATH + assert requests[0].url.params["filter_by"] == "year:>2000" + assert requests[0].url.params["batch_size"] == "500" + + +@pytest.mark.parametrize("ending", ["", "\n"]) +@pytest.mark.parametrize("text", ["a
b", "a
b", "a\u0085b", "é€😀"]) +async def test_a_body_split_anywhere_gives_the_same_lines( + backend: Backend, + fake_config: Configuration, + text: str, + ending: str, +) -> None: + """Test Unicode separators and characters split across chunks.""" + expected = [ + json.dumps({"id": "1", "title": text}, ensure_ascii=False), + '{"id":"2"}', + ] + body = ("\n".join(expected) + ending).encode() + + for offset in range(len(body) + 1): + handler = respond_with(backend, body[:offset], body[offset:]) + documents = make_documents(backend, fake_config, handler) + assert await read_lines(documents) == expected + + +async def test_lines_are_left_as_they_arrived( + backend: Backend, + fake_config: Configuration, +) -> None: + """Test that blank lines and carriage returns are kept.""" + body = b'a\n\n{"id":"1"}\r\nb\rc' + documents = make_documents(backend, fake_config, respond_with(backend, body)) + + lines = await read_lines(documents) + + assert lines == ["a", "", '{"id":"1"}\r', "b\rc"] + assert json.loads(lines[2]) == {"id": "1"} + + +async def test_invalid_utf8_raises_after_the_lines_before_it( + backend: Backend, + fake_config: Configuration, +) -> None: + """Test that a line that cannot be decoded fails the export.""" + body = b'{"id":"1"}\n\xff\n{"id":"3"}\n{"id":"4"}' + documents = make_documents(backend, fake_config, respond_with(backend, body)) + + async with await documents.export_stream() as stream: + assert await stream.__anext__() == '{"id":"1"}' + with pytest.raises(UnicodeDecodeError): + await stream.__anext__() + with pytest.raises(TypesenseClientError, match="failed"): + await stream.__anext__() + + +async def test_aiter_bytes_yields_the_body( + backend: Backend, + fake_config: Configuration, +) -> None: + """Test that the bytes are the body, unchanged.""" + handler = respond_with(backend, BODY[:7], BODY[7:]) + documents = make_documents(backend, fake_config, handler) + + async with await documents.export_stream() as stream: + chunks = [chunk async for chunk in stream.aiter_bytes()] + + assert b"".join(chunks) == BODY + + +async def test_aiter_bytes_accepts_a_chunk_size( + backend: Backend, + fake_config: Configuration, +) -> None: + """Test that chunks are cut to the requested size.""" + documents = make_documents(backend, fake_config, respond_with(backend, b"abcde")) + + async with await documents.export_stream() as stream: + chunks = [chunk async for chunk in stream.aiter_bytes(chunk_size=2)] + + assert chunks == [b"ab", b"cd", b"e"] + + +async def test_compressed_responses_are_decoded( + backend: Backend, + fake_config: Configuration, +) -> None: + """Test that gzip gives the same lines and bytes as an uncompressed export.""" + compressed = gzip.compress(BODY) + + async def handler(request: RequestType) -> ResponseType: + return backend.Response( + 200, + headers={"Content-Encoding": "gzip"}, + content=chunked(compressed[:9], compressed[9:]), + ) + + documents = make_documents(backend, fake_config, handler) + + assert await read_lines(documents, compress=True) == LINES + async with await documents.export_stream(compress=True) as stream: + assert b"".join([c async for c in stream.aiter_bytes()]) == BODY + + +async def test_requests_an_uncompressed_export_by_default( + backend: Backend, + fake_config: Configuration, +) -> None: + """Test the ``Accept-Encoding`` sent with and without ``compress``.""" + requests: typing.List[RequestType] = [] + + async def handler(request: RequestType) -> ResponseType: + requests.append(request) + return backend.Response(200, content=BODY) + + documents = make_documents(backend, fake_config, handler) + + await read_lines(documents) + await read_lines(documents, compress=True) + + assert requests[0].headers["Accept-Encoding"] == "identity" + assert "gzip" in requests[1].headers["Accept-Encoding"] + + +async def test_an_accept_encoding_in_additional_headers_is_kept( + backend: Backend, + fake_config: Configuration, +) -> None: + """Test that a configured header wins, whatever its case.""" + requests: typing.List[RequestType] = [] + + async def handler(request: RequestType) -> ResponseType: + requests.append(request) + return backend.Response(200, content=BODY) + + fake_config.additional_headers = {"accept-encoding": "gzip"} + documents = make_documents(backend, fake_config, handler) + + await read_lines(documents) + + assert requests[0].headers.get_list("Accept-Encoding") == ["gzip"] + + +async def test_uses_the_stream_read_timeout( + backend: Backend, + fake_config: Configuration, +) -> None: + """Test that reads wait for ``stream_read_timeout_seconds``.""" + requests: typing.List[RequestType] = [] + + async def handler(request: RequestType) -> ResponseType: + requests.append(request) + return backend.Response(200, content=BODY) + + fake_config.stream_read_timeout_seconds = 12.5 + documents = make_documents(backend, fake_config, handler) + + await read_lines(documents) + + assert requests[0].extensions["timeout"]["read"] == 12.5 + + +@pytest.mark.parametrize( + "received", + [b'{"id":"1"}\n{"id', b'{"id":"1"}\n'], + ids=["mid-line", "line-boundary"], +) +async def test_truncated_body_raises_without_a_partial_line( + backend: Backend, + fake_config: Configuration, + received: bytes, +) -> None: + """Test that a cut-off export raises the backend's error.""" + error = backend.RemoteProtocolError("peer closed connection") + handler = fail_with(backend, error, received) + documents = make_documents(backend, fake_config, handler) + lines: typing.List[str] = [] + + async with await documents.export_stream() as stream: + with pytest.raises(backend.RemoteProtocolError): + async for line in stream: + lines.append(line) + + assert lines == ['{"id":"1"}'] + + +async def test_truncated_body_raises_from_aiter_bytes( + backend: Backend, + fake_config: Configuration, +) -> None: + """Test that the bytes view reports a cut-off export too.""" + error = backend.RemoteProtocolError("peer closed connection") + documents = make_documents(backend, fake_config, fail_with(backend, error, b"a")) + + async with await documents.export_stream() as stream: + with pytest.raises(backend.RemoteProtocolError): + async for _ in stream.aiter_bytes(): + pass + + +async def test_reading_after_a_failure_does_not_look_complete( + backend: Backend, + fake_config: Configuration, +) -> None: + """Test that lines and bytes keep raising once a read has failed.""" + error = backend.ReadError("connection reset") + handler = fail_with(backend, error, b"a\n") + documents = make_documents(backend, fake_config, handler) + + async with await documents.export_stream() as stream: + assert await stream.__anext__() == "a" + with pytest.raises(backend.ReadError): + await stream.__anext__() + with pytest.raises(TypesenseClientError, match="Start a new export"): + await stream.__anext__() + + async with await documents.export_stream() as stream: + chunks = stream.aiter_bytes() + assert await chunks.__anext__() == b"a\n" + with pytest.raises(backend.ReadError): + await chunks.__anext__() + with pytest.raises(TypesenseClientError, match="Start a new export"): + await chunks.__anext__() + + +async def test_reading_after_a_cancelled_read_does_not_look_complete( + backend: Backend, + fake_config: Configuration, +) -> None: + """Test that a read that timed out in the caller is not taken for the end.""" + never = asyncio.Event() + + async def body() -> typing.AsyncIterator[bytes]: + yield b"a\n" + await never.wait() + + async def handler(request: RequestType) -> ResponseType: + return backend.Response(200, content=body()) + + documents = make_documents(backend, fake_config, handler) + + async with await documents.export_stream() as stream: + assert await stream.__anext__() == "a" + with pytest.raises(asyncio.TimeoutError): + await asyncio.wait_for(stream.__anext__(), SETTLE_SECONDS) + with pytest.raises(TypesenseClientError, match="Start a new export"): + await stream.__anext__() + + +async def test_iteration_can_stop_and_carry_on( + backend: Backend, + fake_config: Configuration, +) -> None: + """Test that leaving a loop keeps the connection and the position.""" + handler = respond_with(backend, b"a\nb\n", b"c\n") + documents = make_documents(backend, fake_config, handler) + + async with await documents.export_stream() as stream: + async for line in stream: + assert line == "a" + break + assert not stream.response.is_closed + assert [line async for line in stream] == ["b", "c"] + + +async def test_closing_early_closes_the_response_without_draining( + backend: Backend, + fake_config: Configuration, +) -> None: + """Test that the rest of the body is not read.""" + sent: typing.List[int] = [] + + async def body() -> typing.AsyncIterator[bytes]: + for index in range(1000): + sent.append(index) + yield b"a\n" + + async def handler(request: RequestType) -> ResponseType: + return backend.Response(200, content=body()) + + documents = make_documents(backend, fake_config, handler) + + async with await documents.export_stream() as stream: + await stream.__anext__() + + assert stream.response.is_closed + assert len(sent) == 1 + + +async def test_a_request_inside_the_loop_does_not_wait_for_the_export( + backend: Backend, + fake_config: Configuration, +) -> None: + """Test that a reading export holds no concurrency slot.""" + + async def handler(request: RequestType) -> ResponseType: + if request.url.path == EXPORT_PATH: + return backend.Response(200, content=chunked(BODY)) + return backend.Response(200, json={"name": "books"}) + + fake_config.max_concurrent_requests = 1 + api_call = make_api_call(backend, fake_config, handler) + documents = AsyncDocuments[DocumentSchema](api_call, "books") + + async with await documents.export_stream() as stream: + async for _ in stream: + collection = await asyncio.wait_for( + api_call.get("/collections/books", dict), + WAIT_SECONDS, + ) + assert collection == {"name": "books"} + + +async def test_opening_an_export_takes_a_concurrency_slot( + backend: Backend, + fake_config: Configuration, +) -> None: + """Test that a request waits while an export is waiting for its headers.""" + export_started = asyncio.Event() + send_headers = asyncio.Event() + + async def handler(request: RequestType) -> ResponseType: + if request.url.path == EXPORT_PATH: + export_started.set() + await send_headers.wait() + return backend.Response(200, content=BODY) + return backend.Response(200, json={}) + + fake_config.max_concurrent_requests = 1 + api_call = make_api_call(backend, fake_config, handler) + documents = AsyncDocuments[DocumentSchema](api_call, "books") + + opening = asyncio.ensure_future(documents.export_stream()) + await asyncio.wait_for(export_started.wait(), WAIT_SECONDS) + request = asyncio.ensure_future(api_call.get("/collections/books", dict)) + await assert_waiting(request) + + send_headers.set() + stream = await asyncio.wait_for(opening, WAIT_SECONDS) + await asyncio.wait_for(request, WAIT_SECONDS) + await stream.aclose() + + +async def test_only_one_view_of_the_body_can_be_read( + backend: Backend, + fake_config: Configuration, +) -> None: + """Test that asking for a second view raises at the call.""" + documents = make_documents(backend, fake_config, respond_with(backend, BODY)) + + async with await documents.export_stream() as stream: + await stream.__anext__() + with pytest.raises(TypesenseClientError, match="already being read"): + stream.aiter_bytes() + + async with await documents.export_stream() as stream: + stream.aiter_bytes() + with pytest.raises(TypesenseClientError, match="already being read"): + stream.__aiter__() + with pytest.raises(TypesenseClientError, match="already being read"): + stream.aiter_bytes() + + +async def test_error_responses_raise_when_opening( + backend: Backend, + fake_config: Configuration, +) -> None: + """Test that the error body is read and the request is not retried.""" + requests: typing.List[RequestType] = [] + + async def handler(request: RequestType) -> ResponseType: + requests.append(request) + return backend.Response(400, json={"message": "Bad filter"}) + + documents = make_documents(backend, fake_config, handler) + + with pytest.raises(RequestMalformed, match="Bad filter"): + await documents.export_stream({"filter_by": "nope"}) + + assert len(requests) == 1 + + +async def test_fails_over_before_the_body_starts( + backend: Backend, + fake_config: Configuration, +) -> None: + """Test that a 5xx is retried on the next node, which is marked healthy.""" + hosts: typing.List[str] = [] + + async def handler(request: RequestType) -> ResponseType: + hosts.append(request.url.host) + if request.url.host == "nearest": + return backend.Response(503, text="Down") + return backend.Response(200, content=BODY) + + documents = make_documents(backend, fake_config, handler) + node = documents.api_call.node_manager.nodes[0] + node.healthy = False + node.last_access_ts = 0 + + assert await read_lines(documents) == LINES + + assert hosts == ["nearest", "node0"] + assert fake_config.nearest_node is not None + assert fake_config.nearest_node.healthy is False + assert node.healthy is True + + +async def test_does_not_retry_once_the_body_has_started( + backend: Backend, + fake_config: Configuration, +) -> None: + """Test that an error after the first chunk reaches the caller.""" + requests: typing.List[RequestType] = [] + + async def handler(request: RequestType) -> ResponseType: + requests.append(request) + error = backend.ReadError("connection reset") + return backend.Response(200, content=chunked(b"a\n", error=error)) + + documents = make_documents(backend, fake_config, handler) + + async with await documents.export_stream() as stream: + assert await stream.__anext__() == "a" + with pytest.raises(backend.ReadError): + await stream.__anext__() + + assert len(requests) == 1 + + +async def test_reading_after_close_raises( + backend: Backend, + fake_config: Configuration, +) -> None: + """Test that a closed export cannot be mistaken for a finished one.""" + documents = make_documents(backend, fake_config, respond_with(backend, BODY)) + + async with await documents.export_stream() as stream: + await stream.__anext__() + with pytest.raises(TypesenseClientError, match="closed"): + await stream.__anext__() + with pytest.raises(TypesenseClientError, match="closed"): + stream.__aiter__() + with pytest.raises(TypesenseClientError, match="closed"): + stream.aiter_bytes() + + async with await documents.export_stream() as stream: + chunks = stream.aiter_bytes() + with pytest.raises(TypesenseClientError, match="closed"): + await chunks.__anext__() + + +async def test_closing_while_another_task_reads( + backend: Backend, + fake_config: Configuration, +) -> None: + """Test that closing does not raise and the reader does not see a clean end.""" + end_body = asyncio.Event() + + async def body() -> typing.AsyncIterator[bytes]: + yield b"a\n" + await end_body.wait() + + async def handler(request: RequestType) -> ResponseType: + return backend.Response(200, content=body()) + + documents = make_documents(backend, fake_config, handler) + stream = await documents.export_stream() + assert await stream.__anext__() == "a" + reader = asyncio.ensure_future(stream.__anext__()) + await assert_waiting(reader) + + await asyncio.wait_for(stream.aclose(), WAIT_SECONDS) + + end_body.set() + with pytest.raises(TypesenseClientError, match="closed"): + await asyncio.wait_for(reader, WAIT_SECONDS) + + +async def test_a_read_broken_by_closing_reports_the_close( + backend: Backend, + fake_config: Configuration, +) -> None: + """Test that the error a close causes does not look like a network failure.""" + break_read = asyncio.Event() + + async def body() -> typing.AsyncIterator[bytes]: + yield b"a" + await break_read.wait() + raise backend.ReadError("connection closed") + + async def handler(request: RequestType) -> ResponseType: + return backend.Response(200, content=body()) + + documents = make_documents(backend, fake_config, handler) + stream = await documents.export_stream() + chunks = stream.aiter_bytes() + assert await chunks.__anext__() == b"a" + reader = asyncio.ensure_future(chunks.__anext__()) + await assert_waiting(reader) + + await asyncio.wait_for(stream.aclose(), WAIT_SECONDS) + break_read.set() + + with pytest.raises(TypesenseClientError, match="closed"): + await asyncio.wait_for(reader, WAIT_SECONDS) + with pytest.raises(TypesenseClientError, match="closed"): + await chunks.__anext__() + + +async def test_a_read_cancelled_after_close_stays_cancelled( + backend: Backend, + fake_config: Configuration, +) -> None: + """Test that cancelling a read is not turned into an error, even after a close.""" + end_body = asyncio.Event() + + async def body() -> typing.AsyncIterator[bytes]: + yield b"a" + await end_body.wait() + + async def handler(request: RequestType) -> ResponseType: + return backend.Response(200, content=body()) + + documents = make_documents(backend, fake_config, handler) + stream = await documents.export_stream() + chunks = stream.aiter_bytes() + assert await chunks.__anext__() == b"a" + reader = asyncio.ensure_future(chunks.__anext__()) + await assert_waiting(reader) + await asyncio.wait_for(stream.aclose(), WAIT_SECONDS) + + reader.cancel() + + with pytest.raises(asyncio.CancelledError): + await asyncio.wait_for(reader, WAIT_SECONDS) + with pytest.raises(TypesenseClientError, match="closed"): + await chunks.__anext__() + + +async def test_chunks_arriving_during_close_are_the_last_ones( + backend: Backend, + fake_config: Configuration, +) -> None: + """Test that the bytes view stops at the read that was already in progress.""" + send_more = asyncio.Event() + + async def body() -> typing.AsyncIterator[bytes]: + yield b"a" + await send_more.wait() + yield b"b" + yield b"c" + + async def handler(request: RequestType) -> ResponseType: + return backend.Response(200, content=body()) + + documents = make_documents(backend, fake_config, handler) + stream = await documents.export_stream() + chunks = stream.aiter_bytes() + assert await chunks.__anext__() == b"a" + reader = asyncio.ensure_future(chunks.__anext__()) + await assert_waiting(reader) + + await stream.aclose() + send_more.set() + + assert await asyncio.wait_for(reader, WAIT_SECONDS) == b"b" + with pytest.raises(TypesenseClientError, match="closed"): + await chunks.__anext__() + + +@pytest.mark.parametrize( + ("max_connections", "max_concurrent_requests", "places"), + [(3, 2, 1), (5, 2, 3), (2, 2, 1), (1, 5, 1)], +) +async def test_open_exports_are_limited( + fake_config: Configuration, + max_connections: int, + max_concurrent_requests: int, + places: int, +) -> None: + """Test the limit, including when the slots leave no room in the pool.""" + documents = limited_documents(fake_config, max_connections, max_concurrent_requests) + + with respx.mock: + mock_export() + streams = [await open_export(documents) for _ in range(places)] + waiting = asyncio.ensure_future(documents.export_stream()) + await assert_waiting(waiting) + + await streams[0].aclose() + streams[0] = await asyncio.wait_for(waiting, WAIT_SECONDS) + + for stream in streams: + await stream.aclose() + + +async def test_closing_twice_gives_back_one_place( + fake_config: Configuration, +) -> None: + """Test that a second close cannot raise the limit.""" + documents = limited_documents(fake_config, 3, 2) + + with respx.mock: + mock_export() + stream = await open_export(documents) + await stream.aclose() + await stream.aclose() + + first = await open_export(documents) + second = asyncio.ensure_future(documents.export_stream()) + await assert_waiting(second) + await first.aclose() + await (await asyncio.wait_for(second, WAIT_SECONDS)).aclose() + + +async def test_overlapping_closes_keep_the_place_until_the_response_closes( + fake_config: Configuration, +) -> None: + """Test that a second close cannot free the place while the first is closing.""" + finish_close = asyncio.Event() + + class SlowToClose(httpx.AsyncByteStream): + """A body whose connection takes a while to close.""" + + async def __aiter__(self) -> typing.AsyncIterator[bytes]: + """Yield the whole body.""" + yield BODY + + async def aclose(self) -> None: + """Wait until the test lets the close finish.""" + await asyncio.wait_for(finish_close.wait(), WAIT_SECONDS) + + documents = limited_documents(fake_config, 2, 1) + + with respx.mock: + + def respond(request: httpx.Request) -> httpx.Response: + return httpx.Response(200, stream=SlowToClose()) + + respx.get(EXPORT_URL).mock(side_effect=respond) + stream = await open_export(documents) + first_close = asyncio.ensure_future(stream.aclose()) + await assert_waiting(first_close) + await asyncio.wait_for(stream.aclose(), WAIT_SECONDS) + + opening = asyncio.ensure_future(documents.export_stream()) + await assert_waiting(opening) + + finish_close.set() + await asyncio.wait_for(first_close, WAIT_SECONDS) + await (await asyncio.wait_for(opening, WAIT_SECONDS)).aclose() + + +async def test_exports_are_not_limited_without_a_concurrency_limit( + fake_config: Configuration, +) -> None: + """Test that the limit needs ``max_concurrent_requests``.""" + documents = limited_documents(fake_config, 1, None) + + with respx.mock: + mock_export() + streams = [await open_export(documents) for _ in range(3)] + for stream in streams: + await stream.aclose() + + +async def test_exports_are_not_limited_with_an_unlimited_pool( + fake_config: Configuration, +) -> None: + """Test that a pool without a size leaves nothing to reserve.""" + documents = limited_documents(fake_config, None, 2) + + with respx.mock: + mock_export() + streams = [await open_export(documents) for _ in range(3)] + for stream in streams: + await stream.aclose() + + +async def test_reading_to_the_end_gives_back_the_place( + fake_config: Configuration, +) -> None: + """Test that an export read to its end does not need closing.""" + documents = limited_documents(fake_config, 3, 2) + + with respx.mock: + mock_export() + lines_stream = await open_export(documents) + lines = [line async for line in lines_stream] + bytes_stream = await open_export(documents) + body = b"".join([chunk async for chunk in bytes_stream.aiter_bytes()]) + await (await open_export(documents)).aclose() + + assert lines == LINES + assert body == BODY + + +async def test_a_failed_read_gives_back_the_place( + fake_config: Configuration, +) -> None: + """Test that an export that failed does not need closing.""" + documents = limited_documents(fake_config, 3, 2) + + with respx.mock: + + def respond(request: httpx.Request) -> httpx.Response: + error = httpx.ReadError("connection reset") + return httpx.Response(200, content=chunked(b"a\n", error=error)) + + route = respx.get(EXPORT_URL).mock(side_effect=respond) + stream = await open_export(documents) + with pytest.raises(httpx.ReadError): + async for _ in stream: + pass + + route.mock(side_effect=export_response) + await (await open_export(documents)).aclose() + + +async def test_exports_are_not_limited_with_a_caller_supplied_client( + backend: Backend, + fake_config: Configuration, +) -> None: + """Test that the limit is skipped when the pool size is unknown.""" + fake_config.max_connections = 2 + fake_config.max_concurrent_requests = 1 + documents = make_documents(backend, fake_config, respond_with(backend, BODY)) + + streams = [await open_export(documents) for _ in range(3)] + + for stream in streams: + await stream.aclose() + + +async def test_a_failed_open_gives_back_its_slot_and_place( + fake_config: Configuration, +) -> None: + """Test that an error response leaves the next export free to open.""" + documents = limited_documents(fake_config, 2, 1) + + with respx.mock: + route = respx.get(EXPORT_URL) + route.mock(return_value=httpx.Response(404, json={"message": "Not found"})) + with pytest.raises(ObjectNotFound, match="Not found"): + await documents.export_stream() + + mock_export() + await (await open_export(documents)).aclose() + + +async def test_cancelling_while_waiting_for_a_place( + fake_config: Configuration, +) -> None: + """Test that a cancelled export takes no place with it.""" + documents = limited_documents(fake_config, 3, 2) + + with respx.mock: + mock_export() + stream = await open_export(documents) + waiting = asyncio.ensure_future(documents.export_stream()) + await assert_waiting(waiting) + waiting.cancel() + await asyncio.wait({waiting}, timeout=WAIT_SECONDS) + await stream.aclose() + + first = await open_export(documents) + second = asyncio.ensure_future(documents.export_stream()) + await assert_waiting(second) + await first.aclose() + await (await asyncio.wait_for(second, WAIT_SECONDS)).aclose() + + +async def test_an_export_waiting_for_a_place_holds_no_slot( + fake_config: Configuration, +) -> None: + """Test that requests keep running while an export waits its turn.""" + documents = limited_documents(fake_config, 2, 1) + + with respx.mock: + mock_export() + respx.get(COLLECTION_URL).mock(return_value=httpx.Response(200, json={})) + stream = await open_export(documents) + waiting = asyncio.ensure_future(documents.export_stream()) + await assert_waiting(waiting) + + await asyncio.wait_for( + documents.api_call.get(COLLECTION_PATH, dict), + WAIT_SECONDS, + ) + + await stream.aclose() + await (await asyncio.wait_for(waiting, WAIT_SECONDS)).aclose() + + +async def test_cancelling_while_waiting_for_a_slot_gives_back_the_place( + fake_config: Configuration, +) -> None: + """Test that the place taken first is released.""" + finish_request = asyncio.Event() + request_started = asyncio.Event() + + async def respond(request: httpx.Request) -> httpx.Response: + request_started.set() + await finish_request.wait() + return httpx.Response(200, json={}) + + documents = limited_documents(fake_config, 2, 1) + + with respx.mock: + mock_export() + respx.get(COLLECTION_URL).mock(side_effect=respond) + request = asyncio.ensure_future( + documents.api_call.get(COLLECTION_PATH, dict), + ) + await asyncio.wait_for(request_started.wait(), WAIT_SECONDS) + + opening = asyncio.ensure_future(documents.export_stream()) + await assert_waiting(opening) + opening.cancel() + await asyncio.wait({opening}, timeout=WAIT_SECONDS) + + finish_request.set() + await asyncio.wait_for(request, WAIT_SECONDS) + await (await open_export(documents)).aclose() + + +async def test_cancelling_while_waiting_for_headers_gives_back_the_slot( + backend: Backend, + fake_config: Configuration, +) -> None: + """Test that a request can run after an export was cancelled while opening.""" + export_started = asyncio.Event() + never = asyncio.Event() + + async def handler(request: RequestType) -> ResponseType: + if request.url.path == EXPORT_PATH: + export_started.set() + await never.wait() + return backend.Response(200, json={}) + + fake_config.max_concurrent_requests = 1 + api_call = make_api_call(backend, fake_config, handler) + documents = AsyncDocuments[DocumentSchema](api_call, "books") + + opening = asyncio.ensure_future(documents.export_stream()) + await asyncio.wait_for(export_started.wait(), WAIT_SECONDS) + opening.cancel() + await asyncio.wait({opening}, timeout=WAIT_SECONDS) + + await asyncio.wait_for(api_call.get("/collections/books", dict), WAIT_SECONDS) + + +async def test_export_stream_through_the_default_client( + fake_config: Configuration, +) -> None: + """Test the export without a client passed in.""" + documents = AsyncDocuments[DocumentSchema](AsyncApiCall(fake_config), "books") + + with respx.mock: + mock_export() + assert await read_lines(documents) == LINES diff --git a/tests/export_stream_integration_test.py b/tests/export_stream_integration_test.py new file mode 100644 index 0000000..962a804 --- /dev/null +++ b/tests/export_stream_integration_test.py @@ -0,0 +1,143 @@ +"""Tests for streaming document exports against a Typesense server.""" + +import json +import sys + +from typesense.async_.api_call import AsyncApiCall +from typesense.async_.documents import AsyncDocuments +from typesense.configuration import Configuration +from typesense.sync.api_call import ApiCall +from typesense.sync.documents import Documents + +if sys.version_info >= (3, 11): + import typing +else: + import typing_extensions as typing + +COMPANIES: typing.Final = [ + {"id": "1", "company_name": "Line
separator", "num_employees": 10}, + {"id": "2", "company_name": "Next\u0085line", "num_employees": 20}, + {"id": "3", "company_name": "Ünïcode 😀", "num_employees": 30}, +] +COMPANY_COUNT: typing.Final = len(COMPANIES) + + +def test_export_stream_matches_export( + delete_all: None, + create_collection: None, + actual_api_call: ApiCall, +) -> None: + """Test that lines and bytes match the buffered export, with and without gzip.""" + documents = Documents(actual_api_call, "companies") + documents.import_(COMPANIES, {"action": "create"}) + exported = documents.export() + + with documents.export_stream() as stream: + lines = list(stream) + with documents.export_stream(compress=True) as stream: + compressed_lines = list(stream) + with documents.export_stream() as stream: + body = b"".join(stream.iter_bytes()) + + assert [json.loads(line) for line in lines] == COMPANIES + assert lines == exported.split("\n") + assert compressed_lines == lines + assert body.decode() == exported + + +def test_export_stream_applies_the_parameters( + delete_all: None, + create_collection: None, + actual_api_call: ApiCall, +) -> None: + """Test a filtered export with a batch size and selected fields.""" + documents = Documents(actual_api_call, "companies") + documents.import_(COMPANIES, {"action": "create"}) + + with documents.export_stream( + { + "filter_by": "num_employees:>=20", + "include_fields": "num_employees", + "batch_size": 1, + }, + ) as stream: + lines = [json.loads(line) for line in stream] + + assert lines == [{"num_employees": 20}, {"num_employees": 30}] + + +def test_export_stream_with_no_matches_has_no_lines( + delete_all: None, + create_collection: None, + actual_api_call: ApiCall, +) -> None: + """Test that a filter matching nothing gives an empty export.""" + documents = Documents(actual_api_call, "companies") + + with documents.export_stream({"filter_by": "num_employees:>0"}) as stream: + assert not list(stream) + + +def test_leaving_an_export_early_frees_the_client( + delete_all: None, + create_collection: None, + actual_config: Configuration, +) -> None: + """Test requests during and after an export at the tightest limits.""" + actual_config.max_concurrent_requests = 1 + actual_config.max_connections = 2 + api_call = ApiCall(actual_config) + documents = Documents(api_call, "companies") + documents.import_(COMPANIES, {"action": "create"}) + + with documents.export_stream() as stream: + assert json.loads(next(stream)) == COMPANIES[0] + collection = api_call.get("/collections/companies", dict) + assert collection["name"] == "companies" + + with documents.export_stream() as stream: + assert len(list(stream)) == COMPANY_COUNT + + +async def test_export_stream_matches_export_async( + delete_all: None, + create_collection: None, + actual_async_api_call: AsyncApiCall, +) -> None: + """Test that lines and bytes match the buffered export, with and without gzip.""" + documents = AsyncDocuments(actual_async_api_call, "companies") + await documents.import_(COMPANIES, {"action": "create"}) + exported = await documents.export() + + async with await documents.export_stream() as stream: + lines = [line async for line in stream] + async with await documents.export_stream(compress=True) as stream: + compressed_lines = [line async for line in stream] + async with await documents.export_stream() as stream: + body = b"".join([chunk async for chunk in stream.aiter_bytes()]) + + assert [json.loads(line) for line in lines] == COMPANIES + assert lines == exported.split("\n") + assert compressed_lines == lines + assert body.decode() == exported + + +async def test_leaving_an_export_early_frees_the_client_async( + delete_all: None, + create_collection: None, + actual_config: Configuration, +) -> None: + """Test requests during and after an export at the tightest limits.""" + actual_config.max_concurrent_requests = 1 + actual_config.max_connections = 2 + api_call = AsyncApiCall(actual_config) + documents = AsyncDocuments(api_call, "companies") + await documents.import_(COMPANIES, {"action": "create"}) + + async with await documents.export_stream() as stream: + assert json.loads(await stream.__anext__()) == COMPANIES[0] + collection = await api_call.get("/collections/companies", dict) + assert collection["name"] == "companies" + + async with await documents.export_stream() as stream: + assert len([line async for line in stream]) == COMPANY_COUNT diff --git a/tests/export_stream_test.py b/tests/export_stream_test.py new file mode 100644 index 0000000..0059323 --- /dev/null +++ b/tests/export_stream_test.py @@ -0,0 +1,895 @@ +"""Tests for streaming document exports with the sync client.""" + +import gzip +import json +import sys +import threading +from concurrent.futures import Future, wait + +import httpx +import pytest +import respx + +from tests.utils.backends import Backend, Handler, RequestType, load_backend +from tests.utils.streaming import ( + COLLECTION_PATH, + COLLECTION_URL, + EXPORT_PATH, + EXPORT_URL, +) +from typesense.configuration import Configuration +from typesense.exceptions import ( + ObjectNotFound, + RequestMalformed, + TypesenseClientError, +) +from typesense.sync.api_call import ApiCall +from typesense.sync.documents import Documents +from typesense.http_backend import ResponseType +from typesense.types.document import DocumentSchema +from typesense.sync.stream import ExportStream + +if sys.version_info >= (3, 11): + import typing +else: + import typing_extensions as typing + +TResult = typing.TypeVar("TResult") + +BODY: typing.Final = b'{"id":"1"}\n{"id":"2"}\n{"id":"3"}' +LINES: typing.Final = ['{"id":"1"}', '{"id":"2"}', '{"id":"3"}'] +WAIT_SECONDS: typing.Final = 2 +SETTLE_SECONDS: typing.Final = 0.05 + + +class Background(typing.Generic[TResult]): + """Runs a call in a daemon thread, so a call that hangs cannot hang the tests.""" + + def __init__(self, function: typing.Callable[[], TResult]) -> None: + """Start running ``function``.""" + self._outcome: "Future[TResult]" = Future() + threading.Thread(target=self._run, args=(function,), daemon=True).start() + + def _run(self, function: typing.Callable[[], TResult]) -> None: + """Keep the outcome of the call.""" + try: + self._outcome.set_result(function()) + except BaseException as error: # noqa: B902 (reported by ``result``) + self._outcome.set_exception(error) + + def assert_waiting(self) -> None: + """Assert that the call has not finished after giving it time to run.""" + assert not wait([self._outcome], SETTLE_SECONDS).done + + def result(self) -> TResult: + """Return the call's result, failing the test if it does not finish.""" + return self._outcome.result(WAIT_SECONDS) + + +@pytest.fixture(name="backend", params=["httpx", "httpx2"]) +def backend_fixture(request: pytest.FixtureRequest) -> Backend: + """Return each HTTP backend that is installed.""" + name = request.param + assert isinstance(name, str) + return load_backend(name) + + +def make_api_call( + backend: Backend, + config: Configuration, + handler: Handler, +) -> ApiCall: + """Return an API call that sends requests through a mock transport.""" + return ApiCall(config, backend.client(handler)) + + +def make_documents( + backend: Backend, + config: Configuration, + handler: Handler, +) -> Documents[DocumentSchema]: + """Return documents sent through a mock transport of ``backend``.""" + return Documents[DocumentSchema](make_api_call(backend, config, handler), "books") + + +def chunked( + *chunks: bytes, + error: typing.Optional[Exception] = None, +) -> typing.Iterator[bytes]: + """Yield ``chunks``, then raise ``error`` if there is one.""" + yield from chunks + if error is not None: + raise error + + +def respond_with(backend: Backend, *chunks: bytes) -> Handler: + """Return a handler that sends ``chunks`` as a streamed export.""" + + def handler(request: RequestType) -> ResponseType: + return backend.Response(200, content=chunked(*chunks)) + + return handler + + +def fail_with(backend: Backend, error: Exception, *chunks: bytes) -> Handler: + """Return a handler that sends ``chunks``, then fails while streaming.""" + + def handler(request: RequestType) -> ResponseType: + return backend.Response(200, content=chunked(*chunks, error=error)) + + return handler + + +def read_lines( + documents: Documents[DocumentSchema], *, compress: bool = False +) -> typing.List[str]: + """Open an export and return all of its lines.""" + with documents.export_stream(compress=compress) as stream: + return list(stream) + + +def limited_documents( + config: Configuration, + max_connections: typing.Optional[int], + max_concurrent_requests: typing.Optional[int], +) -> Documents[DocumentSchema]: + """Return documents using the client's own connection pool.""" + config.max_connections = max_connections + config.max_concurrent_requests = max_concurrent_requests + return Documents[DocumentSchema](ApiCall(config), "books") + + +def export_response(request: httpx.Request) -> httpx.Response: + """Return a complete export, as a fresh response for every request.""" + return httpx.Response(200, content=BODY) + + +def mock_export() -> respx.Route: + """Mock the export endpoint with a complete export.""" + return respx.get(EXPORT_URL).mock(side_effect=export_response) + + +def open_export(documents: Documents[DocumentSchema]) -> ExportStream: + """Open an export, failing the test if it has to wait.""" + return Background(documents.export_stream).result() + + +def test_yields_lines_without_their_line_feed( + backend: Backend, + fake_config: Configuration, +) -> None: + """Test that the lines are complete, including the unterminated last one.""" + documents = make_documents(backend, fake_config, respond_with(backend, BODY)) + + assert read_lines(documents) == LINES + + +def test_sends_the_export_parameters( + backend: Backend, + fake_config: Configuration, +) -> None: + """Test that the request goes to the export endpoint with its parameters.""" + requests: typing.List[RequestType] = [] + + def handler(request: RequestType) -> ResponseType: + requests.append(request) + return backend.Response(200, content=BODY) + + documents = make_documents(backend, fake_config, handler) + + with documents.export_stream({"filter_by": "year:>2000", "batch_size": 500}): + pass + + assert requests[0].method == "GET" + assert requests[0].url.path == EXPORT_PATH + assert requests[0].url.params["filter_by"] == "year:>2000" + assert requests[0].url.params["batch_size"] == "500" + + +@pytest.mark.parametrize("ending", ["", "\n"]) +@pytest.mark.parametrize("text", ["a
b", "a
b", "a\u0085b", "é€😀"]) +def test_a_body_split_anywhere_gives_the_same_lines( + backend: Backend, + fake_config: Configuration, + text: str, + ending: str, +) -> None: + """Test Unicode separators and characters split across chunks.""" + expected = [ + json.dumps({"id": "1", "title": text}, ensure_ascii=False), + '{"id":"2"}', + ] + body = ("\n".join(expected) + ending).encode() + + for offset in range(len(body) + 1): + handler = respond_with(backend, body[:offset], body[offset:]) + documents = make_documents(backend, fake_config, handler) + assert read_lines(documents) == expected + + +def test_lines_are_left_as_they_arrived( + backend: Backend, + fake_config: Configuration, +) -> None: + """Test that blank lines and carriage returns are kept.""" + body = b'a\n\n{"id":"1"}\r\nb\rc' + documents = make_documents(backend, fake_config, respond_with(backend, body)) + + lines = read_lines(documents) + + assert lines == ["a", "", '{"id":"1"}\r', "b\rc"] + assert json.loads(lines[2]) == {"id": "1"} + + +def test_invalid_utf8_raises_after_the_lines_before_it( + backend: Backend, + fake_config: Configuration, +) -> None: + """Test that a line that cannot be decoded fails the export.""" + body = b'{"id":"1"}\n\xff\n{"id":"3"}\n{"id":"4"}' + documents = make_documents(backend, fake_config, respond_with(backend, body)) + + with documents.export_stream() as stream: + assert next(stream) == '{"id":"1"}' + with pytest.raises(UnicodeDecodeError): + next(stream) + with pytest.raises(TypesenseClientError, match="failed"): + next(stream) + + +def test_iter_bytes_yields_the_body( + backend: Backend, + fake_config: Configuration, +) -> None: + """Test that the bytes are the body, unchanged.""" + handler = respond_with(backend, BODY[:7], BODY[7:]) + documents = make_documents(backend, fake_config, handler) + + with documents.export_stream() as stream: + assert b"".join(stream.iter_bytes()) == BODY + + +def test_iter_bytes_accepts_a_chunk_size( + backend: Backend, + fake_config: Configuration, +) -> None: + """Test that chunks are cut to the requested size.""" + documents = make_documents(backend, fake_config, respond_with(backend, b"abcde")) + + with documents.export_stream() as stream: + assert list(stream.iter_bytes(chunk_size=2)) == [b"ab", b"cd", b"e"] + + +def test_compressed_responses_are_decoded( + backend: Backend, + fake_config: Configuration, +) -> None: + """Test that gzip gives the same lines and bytes as an uncompressed export.""" + compressed = gzip.compress(BODY) + + def handler(request: RequestType) -> ResponseType: + return backend.Response( + 200, + headers={"Content-Encoding": "gzip"}, + content=chunked(compressed[:9], compressed[9:]), + ) + + documents = make_documents(backend, fake_config, handler) + + assert read_lines(documents, compress=True) == LINES + with documents.export_stream(compress=True) as stream: + assert b"".join(stream.iter_bytes()) == BODY + + +def test_requests_an_uncompressed_export_by_default( + backend: Backend, + fake_config: Configuration, +) -> None: + """Test the ``Accept-Encoding`` sent with and without ``compress``.""" + requests: typing.List[RequestType] = [] + + def handler(request: RequestType) -> ResponseType: + requests.append(request) + return backend.Response(200, content=BODY) + + documents = make_documents(backend, fake_config, handler) + + read_lines(documents) + read_lines(documents, compress=True) + + assert requests[0].headers["Accept-Encoding"] == "identity" + assert "gzip" in requests[1].headers["Accept-Encoding"] + + +def test_an_accept_encoding_in_additional_headers_is_kept( + backend: Backend, + fake_config: Configuration, +) -> None: + """Test that a configured header wins, whatever its case.""" + requests: typing.List[RequestType] = [] + + def handler(request: RequestType) -> ResponseType: + requests.append(request) + return backend.Response(200, content=BODY) + + fake_config.additional_headers = {"accept-encoding": "gzip"} + documents = make_documents(backend, fake_config, handler) + + read_lines(documents) + + assert requests[0].headers.get_list("Accept-Encoding") == ["gzip"] + + +def test_uses_the_stream_read_timeout( + backend: Backend, + fake_config: Configuration, +) -> None: + """Test that reads wait for ``stream_read_timeout_seconds``.""" + requests: typing.List[RequestType] = [] + + def handler(request: RequestType) -> ResponseType: + requests.append(request) + return backend.Response(200, content=BODY) + + fake_config.stream_read_timeout_seconds = 12.5 + documents = make_documents(backend, fake_config, handler) + + read_lines(documents) + + assert requests[0].extensions["timeout"]["read"] == 12.5 + + +@pytest.mark.parametrize( + "received", + [b'{"id":"1"}\n{"id', b'{"id":"1"}\n'], + ids=["mid-line", "line-boundary"], +) +def test_truncated_body_raises_without_a_partial_line( + backend: Backend, + fake_config: Configuration, + received: bytes, +) -> None: + """Test that a cut-off export raises the backend's error.""" + error = backend.RemoteProtocolError("peer closed connection") + handler = fail_with(backend, error, received) + documents = make_documents(backend, fake_config, handler) + lines: typing.List[str] = [] + + with documents.export_stream() as stream: + with pytest.raises(backend.RemoteProtocolError): + for line in stream: + lines.append(line) + + assert lines == ['{"id":"1"}'] + + +def test_truncated_body_raises_from_iter_bytes( + backend: Backend, + fake_config: Configuration, +) -> None: + """Test that the bytes view reports a cut-off export too.""" + error = backend.RemoteProtocolError("peer closed connection") + documents = make_documents(backend, fake_config, fail_with(backend, error, b"a")) + + with documents.export_stream() as stream: + with pytest.raises(backend.RemoteProtocolError): + list(stream.iter_bytes()) + + +def test_reading_after_a_failure_does_not_look_complete( + backend: Backend, + fake_config: Configuration, +) -> None: + """Test that lines and bytes keep raising once a read has failed.""" + error = backend.ReadError("connection reset") + handler = fail_with(backend, error, b"a\n") + documents = make_documents(backend, fake_config, handler) + + with documents.export_stream() as stream: + assert next(stream) == "a" + with pytest.raises(backend.ReadError): + next(stream) + with pytest.raises(TypesenseClientError, match="Start a new export"): + next(stream) + + with documents.export_stream() as stream: + chunks = stream.iter_bytes() + assert next(chunks) == b"a\n" + with pytest.raises(backend.ReadError): + next(chunks) + with pytest.raises(TypesenseClientError, match="Start a new export"): + next(chunks) + + +def test_iteration_can_stop_and_carry_on( + backend: Backend, + fake_config: Configuration, +) -> None: + """Test that leaving a loop keeps the connection and the position.""" + handler = respond_with(backend, b"a\nb\n", b"c\n") + documents = make_documents(backend, fake_config, handler) + + with documents.export_stream() as stream: + for line in stream: + assert line == "a" + break + assert not stream.response.is_closed + assert list(stream) == ["b", "c"] + + +def test_closing_early_closes_the_response_without_draining( + backend: Backend, + fake_config: Configuration, +) -> None: + """Test that the rest of the body is not read.""" + sent: typing.List[int] = [] + + def body() -> typing.Iterator[bytes]: + for index in range(1000): + sent.append(index) + yield b"a\n" + + def handler(request: RequestType) -> ResponseType: + return backend.Response(200, content=body()) + + documents = make_documents(backend, fake_config, handler) + + with documents.export_stream() as stream: + next(stream) + + assert stream.response.is_closed + assert len(sent) == 1 + + +def test_a_request_inside_the_loop_does_not_wait_for_the_export( + backend: Backend, + fake_config: Configuration, +) -> None: + """Test that a reading export holds no concurrency slot.""" + + def handler(request: RequestType) -> ResponseType: + if request.url.path == EXPORT_PATH: + return backend.Response(200, content=chunked(BODY)) + return backend.Response(200, json={"name": "books"}) + + fake_config.max_concurrent_requests = 1 + api_call = make_api_call(backend, fake_config, handler) + documents = Documents[DocumentSchema](api_call, "books") + + with documents.export_stream() as stream: + for _ in stream: + request = Background(lambda: api_call.get("/collections/books", dict)) + assert request.result() == {"name": "books"} + + +def test_opening_an_export_takes_a_concurrency_slot( + backend: Backend, + fake_config: Configuration, +) -> None: + """Test that a request waits while an export is waiting for its headers.""" + export_started = threading.Event() + send_headers = threading.Event() + + def handler(request: RequestType) -> ResponseType: + if request.url.path == EXPORT_PATH: + export_started.set() + assert send_headers.wait(WAIT_SECONDS) + return backend.Response(200, content=BODY) + return backend.Response(200, json={}) + + fake_config.max_concurrent_requests = 1 + api_call = make_api_call(backend, fake_config, handler) + documents = Documents[DocumentSchema](api_call, "books") + + opening = Background(documents.export_stream) + assert export_started.wait(WAIT_SECONDS) + request = Background(lambda: api_call.get("/collections/books", dict)) + request.assert_waiting() + + send_headers.set() + stream = opening.result() + request.result() + stream.close() + + +def test_only_one_view_of_the_body_can_be_read( + backend: Backend, + fake_config: Configuration, +) -> None: + """Test that asking for a second view raises at the call.""" + documents = make_documents(backend, fake_config, respond_with(backend, BODY)) + + with documents.export_stream() as stream: + next(stream) + with pytest.raises(TypesenseClientError, match="already being read"): + stream.iter_bytes() + + with documents.export_stream() as stream: + stream.iter_bytes() + with pytest.raises(TypesenseClientError, match="already being read"): + iter(stream) + with pytest.raises(TypesenseClientError, match="already being read"): + stream.iter_bytes() + + +def test_error_responses_raise_when_opening( + backend: Backend, + fake_config: Configuration, +) -> None: + """Test that the error body is read and the request is not retried.""" + requests: typing.List[RequestType] = [] + + def handler(request: RequestType) -> ResponseType: + requests.append(request) + return backend.Response(400, json={"message": "Bad filter"}) + + documents = make_documents(backend, fake_config, handler) + + with pytest.raises(RequestMalformed, match="Bad filter"): + documents.export_stream({"filter_by": "nope"}) + + assert len(requests) == 1 + + +def test_fails_over_before_the_body_starts( + backend: Backend, + fake_config: Configuration, +) -> None: + """Test that a 5xx is retried on the next node, which is marked healthy.""" + hosts: typing.List[str] = [] + + def handler(request: RequestType) -> ResponseType: + hosts.append(request.url.host) + if request.url.host == "nearest": + return backend.Response(503, text="Down") + return backend.Response(200, content=BODY) + + documents = make_documents(backend, fake_config, handler) + node = documents.api_call.node_manager.nodes[0] + node.healthy = False + node.last_access_ts = 0 + + assert read_lines(documents) == LINES + + assert hosts == ["nearest", "node0"] + assert fake_config.nearest_node is not None + assert fake_config.nearest_node.healthy is False + assert node.healthy is True + + +def test_does_not_retry_once_the_body_has_started( + backend: Backend, + fake_config: Configuration, +) -> None: + """Test that an error after the first chunk reaches the caller.""" + requests: typing.List[RequestType] = [] + + def handler(request: RequestType) -> ResponseType: + requests.append(request) + error = backend.ReadError("connection reset") + return backend.Response(200, content=chunked(b"a\n", error=error)) + + documents = make_documents(backend, fake_config, handler) + + with documents.export_stream() as stream: + assert next(stream) == "a" + with pytest.raises(backend.ReadError): + next(stream) + + assert len(requests) == 1 + + +def test_reading_after_close_raises( + backend: Backend, + fake_config: Configuration, +) -> None: + """Test that a closed export cannot be mistaken for a finished one.""" + documents = make_documents(backend, fake_config, respond_with(backend, BODY)) + + with documents.export_stream() as stream: + next(stream) + with pytest.raises(TypesenseClientError, match="closed"): + next(stream) + with pytest.raises(TypesenseClientError, match="closed"): + iter(stream) + with pytest.raises(TypesenseClientError, match="closed"): + stream.iter_bytes() + + with documents.export_stream() as stream: + chunks = stream.iter_bytes() + with pytest.raises(TypesenseClientError, match="closed"): + next(chunks) + + +def test_closing_while_another_thread_reads( + backend: Backend, + fake_config: Configuration, +) -> None: + """Test that closing does not raise and the reader does not see a clean end.""" + end_body = threading.Event() + + def body() -> typing.Iterator[bytes]: + yield b"a\n" + assert end_body.wait(WAIT_SECONDS) + + def handler(request: RequestType) -> ResponseType: + return backend.Response(200, content=body()) + + documents = make_documents(backend, fake_config, handler) + stream = documents.export_stream() + assert next(stream) == "a" + reader = Background(lambda: next(stream)) + reader.assert_waiting() + + Background(stream.close).result() + + end_body.set() + with pytest.raises(TypesenseClientError, match="closed"): + reader.result() + + +def test_a_read_broken_by_closing_reports_the_close( + backend: Backend, + fake_config: Configuration, +) -> None: + """Test that the error a close causes does not look like a network failure.""" + break_read = threading.Event() + + def body() -> typing.Iterator[bytes]: + yield b"a" + assert break_read.wait(WAIT_SECONDS) + raise backend.ReadError("connection closed") + + def handler(request: RequestType) -> ResponseType: + return backend.Response(200, content=body()) + + documents = make_documents(backend, fake_config, handler) + stream = documents.export_stream() + chunks = stream.iter_bytes() + assert next(chunks) == b"a" + reader = Background(lambda: next(chunks)) + reader.assert_waiting() + + Background(stream.close).result() + break_read.set() + + with pytest.raises(TypesenseClientError, match="closed"): + reader.result() + with pytest.raises(TypesenseClientError, match="closed"): + next(chunks) + + +def test_chunks_arriving_during_close_are_the_last_ones( + backend: Backend, + fake_config: Configuration, +) -> None: + """Test that the bytes view stops at the read that was already in progress.""" + send_more = threading.Event() + + def body() -> typing.Iterator[bytes]: + yield b"a" + assert send_more.wait(WAIT_SECONDS) + yield b"b" + yield b"c" + + def handler(request: RequestType) -> ResponseType: + return backend.Response(200, content=body()) + + documents = make_documents(backend, fake_config, handler) + stream = documents.export_stream() + chunks = stream.iter_bytes() + assert next(chunks) == b"a" + reader = Background(lambda: next(chunks)) + reader.assert_waiting() + + Background(stream.close).result() + send_more.set() + + assert reader.result() == b"b" + with pytest.raises(TypesenseClientError, match="closed"): + next(chunks) + + +@pytest.mark.parametrize( + ("max_connections", "max_concurrent_requests", "places"), + [(3, 2, 1), (5, 2, 3), (2, 2, 1), (1, 5, 1)], +) +def test_open_exports_are_limited( + fake_config: Configuration, + max_connections: int, + max_concurrent_requests: int, + places: int, +) -> None: + """Test the limit, including when the slots leave no room in the pool.""" + documents = limited_documents(fake_config, max_connections, max_concurrent_requests) + + with respx.mock: + mock_export() + streams = [open_export(documents) for _ in range(places)] + waiting = Background(documents.export_stream) + waiting.assert_waiting() + + streams[0].close() + streams[0] = waiting.result() + + for stream in streams: + stream.close() + + +def test_an_export_waiting_for_a_place_holds_no_slot( + fake_config: Configuration, +) -> None: + """Test that requests keep running while an export waits its turn.""" + documents = limited_documents(fake_config, 2, 1) + + with respx.mock: + mock_export() + respx.get(COLLECTION_URL).mock(return_value=httpx.Response(200, json={})) + stream = open_export(documents) + waiting = Background(documents.export_stream) + waiting.assert_waiting() + + Background(lambda: documents.api_call.get(COLLECTION_PATH, dict)).result() + + stream.close() + waiting.result().close() + + +def test_closing_twice_gives_back_one_place(fake_config: Configuration) -> None: + """Test that a second close cannot raise the limit.""" + documents = limited_documents(fake_config, 3, 2) + + with respx.mock: + mock_export() + stream = open_export(documents) + stream.close() + stream.close() + + first = open_export(documents) + second = Background(documents.export_stream) + second.assert_waiting() + first.close() + second.result().close() + + +def test_overlapping_closes_keep_the_place_until_the_response_closes( + fake_config: Configuration, +) -> None: + """Test that a second close cannot free the place while the first is closing.""" + finish_close = threading.Event() + + class SlowToClose(httpx.SyncByteStream): + """A body whose connection takes a while to close.""" + + def __iter__(self) -> typing.Iterator[bytes]: + """Yield the whole body.""" + yield BODY + + def close(self) -> None: + """Wait until the test lets the close finish.""" + assert finish_close.wait(WAIT_SECONDS) + + documents = limited_documents(fake_config, 2, 1) + + with respx.mock: + + def respond(request: httpx.Request) -> httpx.Response: + return httpx.Response(200, stream=SlowToClose()) + + respx.get(EXPORT_URL).mock(side_effect=respond) + stream = open_export(documents) + first_close = Background(stream.close) + first_close.assert_waiting() + Background(stream.close).result() + + opening = Background(documents.export_stream) + opening.assert_waiting() + + finish_close.set() + first_close.result() + opening.result().close() + + +def test_exports_are_not_limited_without_a_concurrency_limit( + fake_config: Configuration, +) -> None: + """Test that the limit needs ``max_concurrent_requests``.""" + documents = limited_documents(fake_config, 1, None) + + with respx.mock: + mock_export() + streams = [open_export(documents) for _ in range(3)] + for stream in streams: + stream.close() + + +def test_exports_are_not_limited_with_an_unlimited_pool( + fake_config: Configuration, +) -> None: + """Test that a pool without a size leaves nothing to reserve.""" + documents = limited_documents(fake_config, None, 2) + + with respx.mock: + mock_export() + streams = [open_export(documents) for _ in range(3)] + for stream in streams: + stream.close() + + +def test_reading_to_the_end_gives_back_the_place( + fake_config: Configuration, +) -> None: + """Test that an export read to its end does not need closing.""" + documents = limited_documents(fake_config, 3, 2) + + with respx.mock: + mock_export() + lines_stream = open_export(documents) + lines = list(lines_stream) + bytes_stream = open_export(documents) + body = b"".join(bytes_stream.iter_bytes()) + open_export(documents).close() + + assert lines == LINES + assert body == BODY + + +def test_a_failed_read_gives_back_the_place(fake_config: Configuration) -> None: + """Test that an export that failed does not need closing.""" + documents = limited_documents(fake_config, 3, 2) + + with respx.mock: + + def respond(request: httpx.Request) -> httpx.Response: + error = httpx.ReadError("connection reset") + return httpx.Response(200, content=chunked(b"a\n", error=error)) + + route = respx.get(EXPORT_URL).mock(side_effect=respond) + stream = open_export(documents) + with pytest.raises(httpx.ReadError): + list(stream) + + route.mock(side_effect=export_response) + open_export(documents).close() + + +def test_exports_are_not_limited_with_a_caller_supplied_client( + backend: Backend, + fake_config: Configuration, +) -> None: + """Test that the limit is skipped when the pool size is unknown.""" + fake_config.max_connections = 2 + fake_config.max_concurrent_requests = 1 + documents = make_documents(backend, fake_config, respond_with(backend, BODY)) + + streams = [open_export(documents) for _ in range(3)] + + for stream in streams: + stream.close() + + +def test_a_failed_open_gives_back_its_slot_and_place( + fake_config: Configuration, +) -> None: + """Test that an error response leaves the next export free to open.""" + documents = limited_documents(fake_config, 2, 1) + + with respx.mock: + route = respx.get(EXPORT_URL) + route.mock(return_value=httpx.Response(404, json={"message": "Not found"})) + with pytest.raises(ObjectNotFound, match="Not found"): + documents.export_stream() + + mock_export() + open_export(documents).close() + + +def test_export_stream_through_the_default_client( + fake_config: Configuration, +) -> None: + """Test the export without a client passed in.""" + documents = Documents[DocumentSchema](ApiCall(fake_config), "books") + + with respx.mock: + mock_export() + assert read_lines(documents) == LINES diff --git a/tests/jsonl_test.py b/tests/jsonl_test.py new file mode 100644 index 0000000..0870547 --- /dev/null +++ b/tests/jsonl_test.py @@ -0,0 +1,76 @@ +"""Tests for splitting an export body into lines.""" + +import json +import sys + +import pytest + +from typesense.jsonl import JSONLSplitter + +if sys.version_info >= (3, 11): + import typing +else: + import typing_extensions as typing + + +def split(chunks: typing.Iterable[bytes]) -> typing.List[bytes]: + """Return every line in ``chunks``, including an unterminated last line.""" + splitter = JSONLSplitter() + lines: typing.List[bytes] = [] + for chunk in chunks: + lines.extend(splitter.feed(chunk)) + lines.extend(splitter.flush()) + return lines + + +def test_splits_on_line_feeds() -> None: + """Test that each line is returned without its line feed.""" + assert split([b'{"id":"1"}\n{"id":"2"}\n']) == [b'{"id":"1"}', b'{"id":"2"}'] + + +def test_keeps_an_unterminated_last_line_until_flush() -> None: + """Test that the last line is held back, since more of it may still arrive.""" + splitter = JSONLSplitter() + + assert splitter.feed(b'{"id":"1"}\n{"id"') == [b'{"id":"1"}'] + assert splitter.flush() == [b'{"id"'] + assert splitter.flush() == [] + + +def test_joins_a_line_split_across_chunks() -> None: + """Test that the pieces of a line are joined, including at the line feed.""" + assert split([b"ab", b"cd", b"\nef", b"\n"]) == [b"abcd", b"ef"] + + +def test_ignores_empty_chunks() -> None: + """Test that an empty chunk neither ends a line nor adds to it.""" + assert split([b"", b"ab", b"", b"c\n", b""]) == [b"abc"] + + +def test_keeps_blank_lines() -> None: + """Test that lines are not filtered.""" + assert split([b"a\n\n\nb\n"]) == [b"a", b"", b"", b"b"] + + +def test_only_line_feeds_end_a_line() -> None: + """Test that a carriage return stays in the line, alone or before a line feed.""" + assert split([b"a\rb\nc\r\n"]) == [b"a\rb", b"c\r"] + + +def test_a_final_line_feed_adds_no_empty_line() -> None: + """Test that a body ending in a line feed has nothing left to flush.""" + splitter = JSONLSplitter() + + assert splitter.feed(b"a\n") == [b"a"] + assert splitter.flush() == [] + + +@pytest.mark.parametrize("separator", ["
", "
", "\u0085"]) +def test_unicode_line_separators_stay_inside_a_line(separator: str) -> None: + """Test that a body split at every byte offset gives back the same documents.""" + documents = [{"id": "1", "title": f"a{separator}b"}, {"id": "2", "title": "é"}] + body = "\n".join(json.dumps(doc, ensure_ascii=False) for doc in documents).encode() + + for offset in range(len(body) + 1): + lines = split([body[:offset], body[offset:]]) + assert [json.loads(line) for line in lines] == documents diff --git a/tests/stream_async_test.py b/tests/stream_async_test.py index 95009ce..953f762 100644 --- a/tests/stream_async_test.py +++ b/tests/stream_async_test.py @@ -1,5 +1,6 @@ """Tests for streamed conversational search with the async client.""" +import asyncio import json import sys @@ -282,6 +283,29 @@ async def test_closing_early_releases_the_connection_and_slot( await stream.get_final_response() +async def test_search_stream_holds_its_slot_until_closed( + fake_config: Configuration, +) -> None: + """Test that a request waits for an open search stream at the limit.""" + fake_config.max_concurrent_requests = 1 + api_call = AsyncApiCall(fake_config) + documents = AsyncDocuments(api_call, "books") + + with respx.mock: + respx.get(SEARCH_URL).mock(return_value=sse_response()) + respx.get("http://nearest:8108/collections/books").mock( + return_value=httpx.Response(200, json={"name": "books"}), + ) + + stream = await documents.search_stream(SEARCH_PARAMS) + request = asyncio.ensure_future(api_call.get("/collections/books", dict)) + await asyncio.sleep(0.02) + assert not request.done() + + await stream.aclose() + assert await asyncio.wait_for(request, 1) == {"name": "books"} + + async def test_multi_search_stream_sends_conversation_params_in_query( fake_async_api_call: AsyncApiCall, ) -> None: diff --git a/tests/stream_test.py b/tests/stream_test.py index 212912e..432c0be 100644 --- a/tests/stream_test.py +++ b/tests/stream_test.py @@ -2,6 +2,7 @@ import json import sys +import threading import httpx import pytest @@ -264,6 +265,33 @@ def test_closing_early_releases_the_connection_and_slot( stream.get_final_response() +def test_search_stream_holds_its_slot_until_closed( + fake_config: Configuration, +) -> None: + """Test that a request waits for an open search stream at the limit.""" + fake_config.max_concurrent_requests = 1 + api_call = ApiCall(fake_config) + documents = Documents(api_call, "books") + finished = threading.Event() + + def request() -> None: + api_call.get("/collections/books", dict) + finished.set() + + with respx.mock: + respx.get(SEARCH_URL).mock(return_value=sse_response()) + respx.get("http://nearest:8108/collections/books").mock( + return_value=httpx.Response(200, json={"name": "books"}), + ) + + stream = documents.search_stream(SEARCH_PARAMS) + threading.Thread(target=request, daemon=True).start() + assert not finished.wait(0.05) + + stream.close() + assert finished.wait(2) + + def test_multi_search_stream_sends_conversation_params_in_query( fake_api_call: ApiCall, ) -> None: diff --git a/tests/utils/backends.py b/tests/utils/backends.py new file mode 100644 index 0000000..6d93d89 --- /dev/null +++ b/tests/utils/backends.py @@ -0,0 +1,129 @@ +""" +The HTTP backends that the streaming tests run against. + +``httpx`` and ``httpx2`` have the same API but separate classes, so a test written +once for both cannot be typed with either module. ``Backend`` is a typed view of the +parts the tests use, under the modules' own names, built once for each module. +""" + +import dataclasses +import sys + +import httpx +import pytest + +from typesense.http_backend import AsyncClientType, ResponseType, SyncClientType + +if sys.version_info >= (3, 11): + import typing +else: + import typing_extensions as typing + +if typing.TYPE_CHECKING: + import httpx2 + +RequestType = typing.Union[httpx.Request, "httpx2.Request"] +Handler = typing.Callable[[RequestType], ResponseType] +AsyncHandler = typing.Callable[[RequestType], typing.Awaitable[ResponseType]] +ResponseContent = typing.Union[ + bytes, + typing.Iterator[bytes], + typing.AsyncIterator[bytes], +] + + +class ResponseFactory(typing.Protocol): + """Builds a response the way ``httpx.Response`` does.""" + + def __call__( + self, + status_code: int, + *, + headers: typing.Optional[typing.Mapping[str, str]] = None, + content: typing.Optional[ResponseContent] = None, + text: typing.Optional[str] = None, + json: object = None, + ) -> ResponseType: + """Return a response with ``status_code`` and the given body.""" + + +@dataclasses.dataclass(frozen=True) +class Backend: + """The parts of ``httpx`` or ``httpx2`` that the tests use.""" + + Response: ResponseFactory + ReadError: typing.Union[ + typing.Type[httpx.ReadError], + typing.Type["httpx2.ReadError"], + ] + RemoteProtocolError: typing.Union[ + typing.Type[httpx.RemoteProtocolError], + typing.Type["httpx2.RemoteProtocolError"], + ] + client: typing.Callable[[Handler], SyncClientType] + async_client: typing.Callable[[AsyncHandler], AsyncClientType] + + +def load_backend(name: str) -> Backend: + """Return the backend called ``name``, skipping the test if it is not installed.""" + if name == "httpx": + return _httpx_backend() + pytest.importorskip("httpx2") + return _httpx2_backend() + + +def _httpx_backend() -> Backend: + """Return ``httpx`` as a ``Backend``.""" + + def client(handler: Handler) -> httpx.Client: + def respond(request: httpx.Request) -> httpx.Response: + response = handler(request) + assert isinstance(response, httpx.Response) + return response + + return httpx.Client(transport=httpx.MockTransport(respond)) + + def async_client(handler: AsyncHandler) -> httpx.AsyncClient: + async def respond(request: httpx.Request) -> httpx.Response: + response = await handler(request) + assert isinstance(response, httpx.Response) + return response + + return httpx.AsyncClient(transport=httpx.MockTransport(respond)) + + return Backend( + Response=httpx.Response, + ReadError=httpx.ReadError, + RemoteProtocolError=httpx.RemoteProtocolError, + client=client, + async_client=async_client, + ) + + +def _httpx2_backend() -> Backend: + """Return ``httpx2`` as a ``Backend``. It is imported here, being optional.""" + import httpx2 # noqa: WPS433 + + def client(handler: Handler) -> httpx2.Client: + def respond(request: httpx2.Request) -> httpx2.Response: + response = handler(request) + assert isinstance(response, httpx2.Response) + return response + + return httpx2.Client(transport=httpx2.MockTransport(respond)) + + def async_client(handler: AsyncHandler) -> httpx2.AsyncClient: + async def respond(request: httpx2.Request) -> httpx2.Response: + response = await handler(request) + assert isinstance(response, httpx2.Response) + return response + + return httpx2.AsyncClient(transport=httpx2.MockTransport(respond)) + + return Backend( + Response=httpx2.Response, + ReadError=httpx2.ReadError, + RemoteProtocolError=httpx2.RemoteProtocolError, + client=client, + async_client=async_client, + ) diff --git a/tests/utils/streaming.py b/tests/utils/streaming.py index 07da931..9cf7525 100644 --- a/tests/utils/streaming.py +++ b/tests/utils/streaming.py @@ -14,6 +14,10 @@ SEARCH_URL: typing.Final = "http://nearest:8108/collections/books/documents/search" MULTI_SEARCH_URL: typing.Final = "http://nearest:8108/multi_search" +COLLECTION_PATH: typing.Final = "/collections/books" +COLLECTION_URL: typing.Final = f"http://nearest:8108{COLLECTION_PATH}" +EXPORT_PATH: typing.Final = "/collections/books/documents/export" +EXPORT_URL: typing.Final = f"http://nearest:8108{EXPORT_PATH}" CONVERSATION_ID: typing.Final = "6f1c0e5a" diff --git a/utils/run-unasync.py b/utils/run-unasync.py index 144ebe6..8611749 100644 --- a/utils/run-unasync.py +++ b/utils/run-unasync.py @@ -41,6 +41,8 @@ def collect_class_replacements(source_dir: Path) -> dict[str, str]: # ``AsyncGenerator`` takes two type arguments, but ``Generator`` needs three # before Python 3.13. replacements["Generator[MessageChunk, None]"] = "Generator[MessageChunk, None, None]" + # Sync stream openers return the stream itself. + replacements["typing.Awaitable[TStream]"] = "TStream" return replacements From 19ba1dc96f27c493cd8fb55b030b030c6e524390 Mon Sep 17 00:00:00 2001 From: Fanis Tharropoulos Date: Fri, 20 Nov 2026 13:32:36 +0200 Subject: [PATCH 2/2] docs(documents): document streaming exports --- README.md | 34 +++++++++++++++++ examples/async_export_streaming.py | 61 ++++++++++++++++++++++++++++++ examples/export_streaming.py | 52 +++++++++++++++++++++++++ 3 files changed, 147 insertions(+) create mode 100644 examples/async_export_streaming.py create mode 100644 examples/export_streaming.py diff --git a/README.md b/README.md index fd919b6..b76edd1 100644 --- a/README.md +++ b/README.md @@ -42,6 +42,40 @@ if __name__ == "__main__": See `examples/async_collection_operations.py` for a fuller async walkthrough. +## Streaming document exports + +`documents.export()` loads the whole export into memory. `documents.export_stream()` reads it as it arrives: + +```python +with client.collections["books"].documents.export_stream({"batch_size": 500}) as stream: + for line in stream: # str, without the line feed + document = json.loads(line) + +with client.collections["books"].documents.export_stream() as stream, open("books.jsonl", "wb") as file: + for chunk in stream.iter_bytes(): # decoded bytes + file.write(chunk) +``` + +With `AsyncClient`, await the call and use `async with` and `async for`, with `stream.aiter_bytes()` for the bytes: + +```python +async with await client.collections["books"].documents.export_stream() as stream: + async for line in stream: + document = json.loads(line) +``` + +A stream can be read once, either as lines or as bytes. Keep these in mind: + +- **Always close the stream**, ideally with a context manager. With `max_concurrent_requests` set, a stream that is abandoned before its end permanently uses up one of the open export places below. +- **A failed export has to be restarted.** Nodes are only retried until the response headers arrive. After that, errors such as `httpx.RemoteProtocolError` or `httpx.ReadTimeout` are raised as they are, and exports cannot resume from where they stopped. +- **Keep reading.** If your code stops reading for about 60 seconds, the server drops the connection. `stream_read_timeout_seconds` (default 60) separately limits how long the client waits for the server's next chunk. +- **Lines are raw.** They are not parsed, and the server could write an error message into the body after a successful status, so a line is not guaranteed to be a document. +- **Exports are uncompressed by default.** The server compresses on the thread that handles all other requests, which delays them, especially with a large `batch_size`. Pass `compress=True` if bandwidth matters more. An `Accept-Encoding` in `additional_headers` is always respected. + +With `max_concurrent_requests`, an export only takes a slot while it opens, so requests made while reading an export do not wait for it. To keep connections free for those requests, at most `max_connections - max_concurrent_requests` exports can be open at once. If that is not positive, one export is still allowed, and it can leave a request short of a connection, so keep `max_concurrent_requests` below `max_connections`. Further exports wait for a place, so opening an export inside another one can wait forever when no place is free. The limit does not apply to an `http_client` you pass in, because its pool size is unknown. + +If your application cancels many requests, prefer [httpx2](#using-httpx2), which fixes a connection pool leak that cancellation can trigger in httpx. + ## Using httpx2 The client sends requests with [httpx](https://www.python-httpx.org/) by default. On Python 3.10+ you can pass an [httpx2](https://github.com/pydantic/httpx2) client instead. httpx2 is Pydantic's maintained continuation of httpx, and it fixes a connection pool leak in httpcore ([encode/httpcore#1093](https://github.com/encode/httpcore/issues/1093)) that can leave an `AsyncClient` failing every request with `PoolTimeout` under load. diff --git a/examples/async_export_streaming.py b/examples/async_export_streaming.py new file mode 100644 index 0000000..93752b5 --- /dev/null +++ b/examples/async_export_streaming.py @@ -0,0 +1,61 @@ +import asyncio +import json +import os +import sys + +curr_dir = os.path.dirname(os.path.realpath(__file__)) +repo_root = os.path.abspath(os.path.join(curr_dir, os.pardir)) +sys.path.insert(1, os.path.join(repo_root, "src")) + +import typesense + +COLLECTION = "async_export_streaming_books" + + +async def main() -> None: + client = typesense.AsyncClient( + { + "api_key": os.environ.get("TYPESENSE_API_KEY", "xyz"), + "nodes": [{"host": "localhost", "port": "8108", "protocol": "http"}], + "connection_timeout_seconds": 10, + } + ) + + await client.collections.create( + { + "name": COLLECTION, + "fields": [ + {"name": "title", "type": "string"}, + {"name": "year", "type": "int32"}, + ], + } + ) + + try: + documents = client.collections[COLLECTION].documents + await documents.import_( + [{"id": str(year), "title": f"Book {year}", "year": year} for year in range(2000, 2010)], + {"action": "create"}, + ) + + # Read one document at a time. The stream is closed when the block ends, + # even if the loop stops early. + async with await documents.export_stream( + {"filter_by": "year:>=2005", "batch_size": 100}, + ) as stream: + async for line in stream: + print(json.loads(line)["title"]) + + # Count the bytes without keeping the export in memory. + size = 0 + async with await documents.export_stream() as stream: + async for chunk in stream.aiter_bytes(): + size += len(chunk) + print(f"Read {size} bytes") + finally: + await client.collections[COLLECTION].delete() + await client.api_call.aclose() + + +if __name__ == "__main__": + asyncio.run(main()) diff --git a/examples/export_streaming.py b/examples/export_streaming.py new file mode 100644 index 0000000..9acc39d --- /dev/null +++ b/examples/export_streaming.py @@ -0,0 +1,52 @@ +import json +import os +import sys + +curr_dir = os.path.dirname(os.path.realpath(__file__)) +repo_root = os.path.abspath(os.path.join(curr_dir, os.pardir)) +sys.path.insert(1, os.path.join(repo_root, "src")) + +import typesense + +COLLECTION = "export_streaming_books" + +client = typesense.Client( + { + "api_key": os.environ.get("TYPESENSE_API_KEY", "xyz"), + "nodes": [{"host": "localhost", "port": "8108", "protocol": "http"}], + "connection_timeout_seconds": 10, + } +) + +client.collections.create( + { + "name": COLLECTION, + "fields": [ + {"name": "title", "type": "string"}, + {"name": "year", "type": "int32"}, + ], + } +) + +try: + documents = client.collections[COLLECTION].documents + documents.import_( + [{"id": str(year), "title": f"Book {year}", "year": year} for year in range(2000, 2010)], + {"action": "create"}, + ) + + # Read one document at a time. The stream is closed when the block ends, + # even if the loop stops early. + with documents.export_stream({"filter_by": "year:>=2005", "batch_size": 100}) as stream: + for line in stream: + print(json.loads(line)["title"]) + + # Write the export to a file without keeping it in memory. + path = f"{COLLECTION}.jsonl" + with documents.export_stream() as stream, open(path, "wb") as file: + for chunk in stream.iter_bytes(): + file.write(chunk) + print(f"Wrote {os.path.getsize(path)} bytes to {path}") + os.remove(path) +finally: + client.collections[COLLECTION].delete()