diff --git a/zulip/tests/test_fetch_upload.py b/zulip/tests/test_fetch_upload.py new file mode 100644 index 000000000..8bdb784bc --- /dev/null +++ b/zulip/tests/test_fetch_upload.py @@ -0,0 +1,162 @@ +from unittest.mock import MagicMock, patch + +import pytest +import requests + +from zulip import Client, UnrecoverableNetworkError, ZulipError + + +def make_client() -> Client: + with patch.object( + Client, + "get_server_settings", + return_value={"zulip_version": "test-version", "zulip_feature_level": 1}, + ): + return Client( + email="test@example.com", + api_key="test-api-key", + site="https://zulip.example.com", + client="test-client", + ) + + +def mock_response(status_code: int, content: bytes) -> MagicMock: + response = MagicMock() + response.status_code = status_code + response.content = content + return response + + +class TestFetchUpload: + def test_absolute_url_passthrough(self) -> None: + client = make_client() + client.ensure_session() + assert client.session is not None + with patch.object( + client.session, "get", return_value=mock_response(200, b"file contents") + ) as mock_get: + result = client.fetch_upload("https://zulip.example.com/user_uploads/1/file.pdf") + mock_get.assert_called_once_with( + "https://zulip.example.com/user_uploads/1/file.pdf", timeout=90.0 + ) + assert result == b"file contents" + + def test_absolute_url_api_v1_prefix_stripped(self) -> None: + client = make_client() + client.ensure_session() + assert client.session is not None + with patch.object( + client.session, "get", return_value=mock_response(200, b"file contents") + ) as mock_get: + client.fetch_upload( + "https://zulip.example.com/api/v1/user_uploads/1/file.pdf?token=xyz" + ) + mock_get.assert_called_once_with( + "https://zulip.example.com/user_uploads/1/file.pdf?token=xyz", timeout=90.0 + ) + + def test_temporary_token_url(self) -> None: + client = make_client() + client.ensure_session() + assert client.session is not None + with patch.object( + client.session, "get", return_value=mock_response(200, b"file contents") + ) as mock_get: + client.fetch_upload("/user_uploads/temporary/token123/file.pdf") + mock_get.assert_called_once_with( + "https://zulip.example.com/user_uploads/temporary/token123/file.pdf", + timeout=90.0, + ) + + def test_absolute_url_on_other_origin_rejected(self) -> None: + client = make_client() + client.ensure_session() + assert client.session is not None + with patch.object(client.session, "get") as mock_get: + with pytest.raises(ZulipError): + client.fetch_upload("https://evil.example.com/user_uploads/1/file.pdf") + mock_get.assert_not_called() + + def test_absolute_url_with_different_scheme_rejected(self) -> None: + client = make_client() + client.ensure_session() + assert client.session is not None + with patch.object(client.session, "get") as mock_get: + with pytest.raises(ZulipError): + client.fetch_upload("http://zulip.example.com/user_uploads/1/file.pdf") + mock_get.assert_not_called() + + def test_root_relative_path_resolved_against_server_root(self) -> None: + client = make_client() + client.ensure_session() + assert client.session is not None + with patch.object( + client.session, "get", return_value=mock_response(200, b"file contents") + ) as mock_get: + result = client.fetch_upload("/user_uploads/1/file.pdf") + mock_get.assert_called_once_with( + "https://zulip.example.com/user_uploads/1/file.pdf", timeout=90.0 + ) + assert result == b"file contents" + + def test_custom_timeout(self) -> None: + client = make_client() + client.ensure_session() + assert client.session is not None + with patch.object( + client.session, "get", return_value=mock_response(200, b"file contents") + ) as mock_get: + client.fetch_upload("/user_uploads/1/file.pdf", timeout=5) + mock_get.assert_called_once_with( + "https://zulip.example.com/user_uploads/1/file.pdf", timeout=5.0 + ) + + def test_path_without_leading_slash_accepted(self) -> None: + client = make_client() + client.ensure_session() + assert client.session is not None + with patch.object( + client.session, "get", return_value=mock_response(200, b"file contents") + ) as mock_get: + client.fetch_upload("user_uploads/1/file.pdf") + mock_get.assert_called_once_with( + "https://zulip.example.com/user_uploads/1/file.pdf", timeout=90.0 + ) + + def test_path_api_v1_prefix_stripped(self) -> None: + client = make_client() + client.ensure_session() + assert client.session is not None + with patch.object( + client.session, "get", return_value=mock_response(200, b"file contents") + ) as mock_get: + client.fetch_upload("/api/v1/user_uploads/1/file.pdf") + mock_get.assert_called_once_with( + "https://zulip.example.com/user_uploads/1/file.pdf", timeout=90.0 + ) + + def test_non_user_uploads_path_rejected(self) -> None: + client = make_client() + with pytest.raises(ZulipError): + client.fetch_upload("random/path/here") + + def test_non_200_raises(self) -> None: + client = make_client() + client.ensure_session() + assert client.session is not None + with patch.object( + client.session, "get", return_value=mock_response(403, b"") + ), pytest.raises(ZulipError): + client.fetch_upload("/user_uploads/1/file.pdf") + + def test_connection_error_raises_unrecoverable(self) -> None: + client = make_client() + client.ensure_session() + assert client.session is not None + with patch.object( + client.session, + "get", + side_effect=requests.exceptions.ConnectionError("boom"), + ): + with pytest.raises(UnrecoverableNetworkError): + client.fetch_upload("/user_uploads/1/file.pdf") diff --git a/zulip/zulip/__init__.py b/zulip/zulip/__init__.py index 6d725a10b..04352b1d1 100644 --- a/zulip/zulip/__init__.py +++ b/zulip/zulip/__init__.py @@ -876,6 +876,71 @@ def upload_file(self, file: IO[Any]) -> Dict[str, Any]: """ return self.call_endpoint(url="user_uploads", files=[file]) + def fetch_upload(self, url_or_path: str, timeout: Optional[float] = None) -> bytes: + """ + Download an uploaded file, using API authentication. + + Accepts a path (e.g. "/user_uploads/1/abc123/file.png", as it + appears in message content), a `/user_uploads/temporary/...` + token URL, or an absolute `http(s)` URL on this Zulip server. + A leading `/api/v1/` prefix is stripped: + `GET /api/v1/user_uploads/...` returns a JSON temporary-access + URL rather than the file, so downloads have to go to the + unprefixed path. + + Absolute URLs on other origins are rejected, because the + authenticated session would otherwise send the bot's API key + to a third-party host. + + `timeout` is the request timeout in seconds; defaults to 90, + like long-polling requests. + + Returns the file contents as bytes. Raises UnrecoverableNetworkError + if the request cannot be made, and ZulipError if the server + returns an HTTP error status. + """ + server_root = self.base_url.removesuffix("/api/") + server_origin = urllib.parse.urlsplit(server_root) + if url_or_path.startswith(("http://", "https://")): + parsed = urllib.parse.urlsplit(url_or_path) + if (parsed.scheme.lower(), parsed.netloc.lower()) != ( + server_origin.scheme.lower(), + server_origin.netloc.lower(), + ): + raise ZulipError( + f"fetch_upload() requires an absolute URL on {server_root!r}; refusing to send credentials elsewhere" + ) + path = parsed.path + if path.startswith("/api/v1/"): + path = path[len("/api/v1"):] + url = urllib.parse.urlunsplit( + (parsed.scheme, parsed.netloc, path, parsed.query, "") + ) + else: + # Path on this Zulip server (leading/trailing slashes and a + # mistaken /api/v1/ prefix are tolerated). + path = url_or_path.lstrip("/") + if path.startswith("api/v1/"): + path = path[len("api/v1/"):] + if not path.startswith("user_uploads/"): + raise ZulipError( + f"fetch_upload() requires an absolute URL or a path under /user_uploads/, got {url_or_path!r}" + ) + url = server_root + "/" + path + self.ensure_session() + assert self.session is not None + try: + res = self.session.get(url, timeout=timeout if timeout is not None else 90.0) + except requests.exceptions.ConnectionError as e: + raise UnrecoverableNetworkError( + "cannot connect to server " + self.base_url + ) from e + if res.status_code != 200: + raise ZulipError( + f"Failed to fetch upload {url_or_path!r}: server returned {res.status_code}" + ) + return res.content + def get_attachments(self) -> Dict[str, Any]: """ Example usage: