diff --git a/zulip/tests/test_client.py b/zulip/tests/test_client.py new file mode 100644 index 000000000..3530c482c --- /dev/null +++ b/zulip/tests/test_client.py @@ -0,0 +1,122 @@ +from unittest import TestCase +from unittest.mock import MagicMock, patch + +import requests +from typing_extensions import override + +import zulip +from zulip import UnrecoverableNetworkError, ZulipError + + +class TestFetchUpload(TestCase): + @override + def setUp(self) -> None: + # Avoid a real network request in Client.__init__, which calls + # get_server_settings(). + patcher = patch.object( + zulip.Client, + "get_server_settings", + return_value={"zulip_version": "10.0", "zulip_feature_level": 300}, + ) + self.addCleanup(patcher.stop) + patcher.start() + + self.client = zulip.Client( + email="bot@example.com", + api_key="test-api-key", + site="https://chat.zulip.org", + ) + self.mock_session = MagicMock() + self.client.session = self.mock_session + + def mock_response(self, status_code: int = 200, content: bytes = b"file-bytes") -> MagicMock: + response = MagicMock() + response.status_code = status_code + response.content = content + return response + + def test_fetch_upload_relative_path(self) -> None: + self.mock_session.request.return_value = self.mock_response() + content = self.client.fetch_upload("/user_uploads/1/abc123/file.png") + self.assertEqual(content, b"file-bytes") + self.mock_session.request.assert_called_once_with( + "GET", + "https://chat.zulip.org/user_uploads/1/abc123/file.png", + timeout=15.0, + ) + + def test_fetch_upload_path_without_leading_slash(self) -> None: + self.mock_session.request.return_value = self.mock_response() + self.client.fetch_upload("user_uploads/1/abc123/file.png") + self.mock_session.request.assert_called_once_with( + "GET", + "https://chat.zulip.org/user_uploads/1/abc123/file.png", + timeout=15.0, + ) + + def test_fetch_upload_full_url(self) -> None: + self.mock_session.request.return_value = self.mock_response() + self.client.fetch_upload("https://chat.zulip.org/user_uploads/1/abc123/file.png") + self.mock_session.request.assert_called_once_with( + "GET", + "https://chat.zulip.org/user_uploads/1/abc123/file.png", + timeout=15.0, + ) + + def test_fetch_upload_temporary_url(self) -> None: + self.mock_session.request.return_value = self.mock_response() + self.client.fetch_upload("/user_uploads/temporary/abc123/file.png") + self.mock_session.request.assert_called_once_with( + "GET", + "https://chat.zulip.org/user_uploads/temporary/abc123/file.png", + timeout=15.0, + ) + + def test_fetch_upload_strips_api_v1_prefix_from_path(self) -> None: + # GET /api/v1/user_uploads/... only returns a temporary access + # URL as JSON, not the file itself, so the prefix must be + # stripped to hit the direct download endpoint. + self.mock_session.request.return_value = self.mock_response() + self.client.fetch_upload("/api/v1/user_uploads/1/abc123/file.png") + self.mock_session.request.assert_called_once_with( + "GET", + "https://chat.zulip.org/user_uploads/1/abc123/file.png", + timeout=15.0, + ) + + def test_fetch_upload_strips_api_v1_prefix_from_full_url(self) -> None: + self.mock_session.request.return_value = self.mock_response() + self.client.fetch_upload( + "https://chat.zulip.org/api/v1/user_uploads/1/abc123/file.png?token=xyz" + ) + self.mock_session.request.assert_called_once_with( + "GET", + "https://chat.zulip.org/user_uploads/1/abc123/file.png?token=xyz", + timeout=15.0, + ) + + def test_fetch_upload_custom_timeout(self) -> None: + self.mock_session.request.return_value = self.mock_response() + self.client.fetch_upload("/user_uploads/1/abc123/file.png", timeout=5.0) + self.mock_session.request.assert_called_once_with( + "GET", + "https://chat.zulip.org/user_uploads/1/abc123/file.png", + timeout=5.0, + ) + + def test_fetch_upload_rejects_absolute_url_on_other_host(self) -> None: + # The bot's credentials must never be sent to an external host, + # e.g. a link extracted from user message markdown. + with self.assertRaises(ZulipError): + self.client.fetch_upload("https://evil.example.com/user_uploads/1/abc/file.png") + self.mock_session.request.assert_not_called() + + def test_fetch_upload_http_error(self) -> None: + self.mock_session.request.return_value = self.mock_response(status_code=404) + with self.assertRaises(ZulipError): + self.client.fetch_upload("/user_uploads/1/abc123/file.png") + + def test_fetch_upload_connection_error(self) -> None: + self.mock_session.request.side_effect = requests.exceptions.ConnectionError + with self.assertRaises(UnrecoverableNetworkError): + self.client.fetch_upload("/user_uploads/1/abc123/file.png") diff --git a/zulip/zulip/__init__.py b/zulip/zulip/__init__.py index 6d725a10b..a3565c0bd 100644 --- a/zulip/zulip/__init__.py +++ b/zulip/zulip/__init__.py @@ -876,6 +876,73 @@ def upload_file(self, file: IO[Any]) -> Dict[str, Any]: """ return self.call_endpoint(url="user_uploads", files=[file]) + def fetch_upload(self, url: str, timeout: Optional[float] = None) -> bytes: + """ + Download a file previously uploaded to the Zulip server. + + `url` may be either a path (e.g. "/user_uploads/1/abc123/file.png", + as it appears in message content) or a full URL. Unlike + `call_endpoint`, this does not prepend "/api/v1/", because + GET /api/v1/user_uploads/... only returns a temporary access + URL for the file, rather than the file itself. + + Example usage: + + >>> content = client.fetch_upload("/user_uploads/1/abc123/file.png") + >>> content[:4] + b'\\x89PNG' + + Returns the raw bytes of the file. Raises ZulipError if the + server returns an HTTP error status, or if a full URL is given + for a host other than this client's Zulip server (so the + bot's credentials are never sent to an external host). + """ + url = url.strip() + + if url.startswith(("http://", "https://")): + parsed_url = urllib.parse.urlparse(url) + # Never send the bot's HTTP Basic Auth credentials to an + # external host: only fetch from this client's Zulip server. + realm_netloc = urllib.parse.urlparse(self.base_url).netloc + if parsed_url.netloc != realm_netloc: + raise ZulipError( + "fetch_upload only supports URLs on this Zulip server " + f"({realm_netloc}), not {parsed_url.netloc}" + ) + path = parsed_url.path + if path.startswith("/api/v1/"): + path = path[len("/api/v1") :] + download_url = urllib.parse.urlunparse( + (parsed_url.scheme, parsed_url.netloc, path, "", parsed_url.query, "") + ) + else: + path = url.lstrip("/") + if path.startswith("api/v1/"): + path = path[len("api/v1/") :] + # self.base_url is "/api/"; uploaded files are served + # from the site root, without the "/api/" prefix. + site_url = self.base_url[: -len("api/")] + download_url = urllib.parse.urljoin(site_url, path) + + request_timeout = timeout or 15.0 + + self.ensure_session() + assert self.session is not None + + try: + res = self.session.request( + "GET", + download_url, + timeout=request_timeout, + ) + 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"Error fetching upload: HTTP {res.status_code} from {download_url}") + + return res.content + def get_attachments(self) -> Dict[str, Any]: """ Example usage: