harp-proxy 0.5.0__tar.gz

harp_proxy-0.5.0/LICENSE.rst

@@ -0,0 +1,43 @@
+License
+=======
+
+HARP Community Edition (or HARP CE) is the open-source core (`this repository <https://github.com/msqd/harp>`_) for the
+HARP ecosystem (including both the open-source core, the professional and enterprise extensions and third party
+extensions that did not define their own licence).
+
+
+HARP Community Edition (HARP CE)
+::::::::::::::::::::::::::::::::
+
+HARP CE is an API Runtime Proxy, a sidecar service for web applications that helps raising reliability, performances,
+security and observability of your external API usage.
+
+All the code included in this repository is part of HARP CE, and is distributed under the terms of the GNU Lesser
+General Public License (LGPL) version 3.0 or later.
+
+Copyright (C) 2023-2024  Romain Dorgueil
+
+.. code-block:: text
+
+    This program is free software: you can redistribute it and/or modify
+    it under the terms of the GNU Lesser General Public License as published by
+    the Free Software Foundation, either version 3 of the License, or
+    (at your option) any later version.
+
+    This program is distributed in the hope that it will be useful,
+    but WITHOUT ANY WARRANTY; without even the implied warranty of
+    MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+    GNU Lesser General Public License for more details.
+
+    You should have received a copy of the GNU Lesser General Public License
+    along with this program.  If not, see <https://www.gnu.org/licenses/>.
+
+Read the full license: https://www.gnu.org/licenses/lgpl-3.0.txt
+
+
+HARP Professional Edition (HARP PE) and Enterprise Edition (HARP EE)
+::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::
+
+HARP Professional Edition (HARP PE) and Enterprise Edition (HARP EE) are the commercial extensions of HARP CE, and are
+distributed under a commercial license. They are not open-source (although you will get access to the source code if
+you are a professional edition or enterprise edition customer), and are not distributed with this repository.

harp_proxy-0.5.0/PKG-INFO

@@ -0,0 +1,187 @@
+Metadata-Version: 2.1
+Name: harp-proxy
+Version: 0.5.0
+Summary: Harp is an API Runtime Proxy – A toolkit for Fast, Reliable and Observable external APIs
+Author: Romain Dorgueil
+Author-email: romain@makersquad.fr
+Requires-Python: >=3.12,<4.0
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.12
+Provides-Extra: dev
+Requires-Dist: aiohttp (>=3.9.5,<4.0.0)
+Requires-Dist: aiosqlite (>=0.19,<0.21)
+Requires-Dist: alembic (>=1.13.1,<2.0.0)
+Requires-Dist: anyio (>=4.4.0,<5.0.0)
+Requires-Dist: asgi-prometheus (>=1.1.2,<2.0.0)
+Requires-Dist: asgimiddlewarestaticfile (>=0.6.0,<0.7.0)
+Requires-Dist: asgiref (>=3.8.1,<4.0.0)
+Requires-Dist: asyncpg (>=0.29.0,<0.30.0)
+Requires-Dist: dataclasses-json (>=0.6.7,<0.7.0)
+Requires-Dist: dataclasses-jsonschema (>=2.16.0,<3.0.0)
+Requires-Dist: essentials-configuration (>=2.0.4,<3.0.0)
+Requires-Dist: hishel (>=0.0.21,<0.0.28)
+Requires-Dist: honcho (>=1.1.0,<2.0.0) ; extra == "dev"
+Requires-Dist: http-router (>=4.1.2,<5.0.0)
+Requires-Dist: httpx (>=0.26,<0.28)
+Requires-Dist: hypercorn (>=0.17.2,<0.18.0)
+Requires-Dist: multidict (>=6.0.5,<7.0.0)
+Requires-Dist: orjson (>=3.10.5,<4.0.0)
+Requires-Dist: passlib (>=1.7.4,<2.0.0)
+Requires-Dist: psycopg2-binary (>=2.9.9,<3.0.0)
+Requires-Dist: pyheck (>=0.1.5,<0.2.0)
+Requires-Dist: pyyaml (>=6.0.1,<7.0.0)
+Requires-Dist: rich (>=13.7.1,<14.0.0)
+Requires-Dist: rich-click (>=1.8.3,<2.0.0)
+Requires-Dist: rodi (>=2.0.6,<3.0.0)
+Requires-Dist: sentry-sdk (>=2.5.1,<3.0.0)
+Requires-Dist: sqlalchemy-utils (>=0.41.1,<0.42.0)
+Requires-Dist: sqlalchemy[asyncio] (>=2.0.30,<3.0.0)
+Requires-Dist: structlog (>=24.2.0,<25.0.0)
+Requires-Dist: svix-ksuid (>=0.6.2,<0.7.0)
+Requires-Dist: watchfiles (>=0.22.0,<0.23.0) ; extra == "dev"
+Requires-Dist: whistle (==2.0.0b1)
+Description-Content-Type: text/x-rst
+
+HARP – Harp, an API Runtime Proxy
+=================================
+
+HARP is a powerful sidecar proxy service designed to elevate the reliability, performance, security, and observability
+of your application's external API interactions. Think of it as a reverse API gateway or a nearline service mesh for
+external APIs.
+
+**HARP is released as an Early Access Preview.**
+
+.. image:: https://img.shields.io/pypi/v/harp-proxy.svg
+    :target: https://pypi.python.org/pypi/harp-proxy
+    :alt: PyPI
+
+.. image:: https://www.gitlab.com/makersquad/oss/harp/badges/dev/pipeline.svg
+    :target: https://www.gitlab.com/makersquad/oss/harp/pipelines
+    :alt: GitLab CI/CD Pipeline Status
+
+.. image:: https://readthedocs.org/projects/harp-proxy/badge/?version=latest
+    :target: https://harp-proxy.readthedocs.io/
+    :alt: Documentation
+
+.. image:: https://img.shields.io/pypi/pyversions/harp-proxy.svg
+    :target: https://pypi.python.org/pypi/harp-proxy
+    :alt: Versions
+
+*Although we use HARP for production workloads, it is still under heavy active development and some features
+may not be available, or it may not be suitable for your applications. We are actively looking for feedback, please
+reach out with your thoughts, ideas, rants or issues. We can help.*
+
+**Quick links:** `Documentation <https://harp-proxy.readthedocs.io/en/latest/>`_
+| `Getting Started <https://harp-proxy.readthedocs.io/en/latest/start/index.html>`_
+| `Install (Docker) <https://harp-proxy.readthedocs.io/en/latest/start/docker.html>`_
+| `Install (PIP) <https://harp-proxy.readthedocs.io/en/latest/start/python.html>`_
+| `Repository (Git) <https://github.com/msqd/harp>`_
+| `Issues <https://github.com/msqd/harp/issues>`_
+| `CI/CD <https://gitlab.com/makersquad/oss/harp/-/pipelines>`_
+
+
+How it works?
+:::::::::::::
+
+Overview
+--------
+
+.. figure:: https://github.com/msqd/harp/raw/dev/docs/images/HowItWorks-Overview.png
+    :alt: An overview of how HARP works in your system
+    :align: center
+
+* **Easy Integration:** Integrating with your application is a breeze, because it speaks the same language you already
+  use: HTTP. Simply run the proxy, update your API endpoints, and you're ready to go. No complex setup or extensive
+  configuration required. Of course, everything is modular and configurable, so you'll be able to fine-tune for your
+  taste later.
+* **Reduced Network Distance:** As a *nearline* proxy, HARP minimizes the network distance between your application
+  and external services, when possible, using standard techniques like caching or prefetching. This leads to faster
+  response times and improved overall performance of your application, even before any configuration is done.
+* **Simplified Development:** HARP eliminates the need for writing extensive code for functionalities such as caching,
+  monitoring, alerting, rate limiting, circuit breaking, retries, tracing, logging, and more. These features can be
+  easily delegated to the proxy, reducing the amount of code you need to write and maintain.
+* **Seamless HTTP Integration:** HARP seamlessly integrates with your application using the HTTP protocol. This means
+  that the integration or removal cost is virtually zero, or even negative when considering the reduction in code you
+  won't need to write.
+
+`Read the full documentation <https://harp-proxy.readthedocs.io/en/latest/>`_
+
+
+Hub to external services
+------------------------
+
+.. figure:: https://github.com/msqd/harp/raw/dev/docs/images/HowItWorks-OverviewMultipleApps.png
+    :alt: An overview of how HARP works in your system when you have multiple consumers
+    :align: center
+
+* **Mutualize Client Logic**: Having n API consumers does not mean you have to implement n times each client-side
+  feature. Use HARP as a hub and greatly reduce the amount of client code you need to write and maintain.
+* **Observes and Controls**: You get a central place to observe and control all your API interactions.
+* **Grow and Scale**: As your company grows and develop new applications, you can leverage the work done on existing
+  external services without having to write a single new line of code.
+
+
+Service
+-------
+
+Within the service, harp runs one or more proxies, each one listening to one port to instrument your external API calls
+with the features you need (auditing, caching, alerting, circuit breaker switch, health checks, etc.).
+
+Each proxy is configured to intercept and forward requests to a specific external API, with independent configuration.
+
+An additional (optional) port serves a dashboard to observe your proxies in real-time.
+
+.. figure:: https://github.com/msqd/harp/raw/dev/docs/images/HowItWorks-Service.png
+    :alt: What happens within the harp service
+    :align: center
+
+* **Features**: Harp comes builtin with a set of industry-standard client side features that you can leverage with a few
+  lines of configuration.
+* **Flexibility**: Each feature is optional, and it's up to you to chose the setup that fits your needs.
+* **Customizable**: You can write code to extend the proxy features, using the same interface as all the builtin
+  features. It guarantees that you can basically implement pretty much anything that make sense inbetween your
+  applications and the external services.
+
+
+Proxy
+-----
+
+As an HTTP Proxy, HARP does not change anything to the way you communicate with the external services. You were speaking
+HTTP before, you will still speak HTTP. The only change needed in your applications configuration to plug or unplug HARP
+is the base endpoint of the external services. In a modern 12factor-like application, it usually only means changing an
+environment variable.
+
+.. figure:: https://github.com/msqd/harp/raw/dev/docs/images/HowItWorks-Proxy.png
+    :alt: What happens within one harp proxy
+    :align: center
+
+* **Reversibility**: By requiring 0 code change on your application side (except endpoint url configuration, that
+  should be outside the code if you follow the 12factor principles), HARP can be plugged and unplugged at a very low
+  cost. You have absolutely no vendor lock-in.
+* **Sidecar**: Harp runs in your infrastructure, implementing the client side features right next to your application.
+  The service is fast, and the minimum network distance between your application and the proxy makes it even faster.
+* **Open Core**: Harp is an open software. The core and reference implementation of the proxy is open source, and you
+  can extend it to fit your needs.
+
+Proxy features
+--------------
+
+.. note:: (TODO) Add a list of features with links to the documentation.
+
+
+Credits
+:::::::
+
+* Core contributors:
+
+  - `Arthur Degonde <https://github.com/ArthurD1>`_
+  - `Romain Dorgueil <https://github.com/hartym>`_
+
+* Original idea, design, and development:
+
+  - `Romain Dorgueil <https://github.com/hartym>`_
+
+* Sponsored by `Makersquad <https://www.makersquad.fr/>`_
+
+`There are many ways you can contribute to HARP! <https://harp-proxy.readthedocs.io/en/latest/contribute/>`_
+

harp_proxy-0.5.0/README.rst

@@ -0,0 +1,142 @@
+HARP – Harp, an API Runtime Proxy
+=================================
+
+HARP is a powerful sidecar proxy service designed to elevate the reliability, performance, security, and observability
+of your application's external API interactions. Think of it as a reverse API gateway or a nearline service mesh for
+external APIs.
+
+**HARP is released as an Early Access Preview.**
+
+.. image:: https://img.shields.io/pypi/v/harp-proxy.svg
+    :target: https://pypi.python.org/pypi/harp-proxy
+    :alt: PyPI
+
+.. image:: https://www.gitlab.com/makersquad/oss/harp/badges/dev/pipeline.svg
+    :target: https://www.gitlab.com/makersquad/oss/harp/pipelines
+    :alt: GitLab CI/CD Pipeline Status
+
+.. image:: https://readthedocs.org/projects/harp-proxy/badge/?version=latest
+    :target: https://harp-proxy.readthedocs.io/
+    :alt: Documentation
+
+.. image:: https://img.shields.io/pypi/pyversions/harp-proxy.svg
+    :target: https://pypi.python.org/pypi/harp-proxy
+    :alt: Versions
+
+*Although we use HARP for production workloads, it is still under heavy active development and some features
+may not be available, or it may not be suitable for your applications. We are actively looking for feedback, please
+reach out with your thoughts, ideas, rants or issues. We can help.*
+
+**Quick links:** `Documentation <https://harp-proxy.readthedocs.io/en/latest/>`_
+| `Getting Started <https://harp-proxy.readthedocs.io/en/latest/start/index.html>`_
+| `Install (Docker) <https://harp-proxy.readthedocs.io/en/latest/start/docker.html>`_
+| `Install (PIP) <https://harp-proxy.readthedocs.io/en/latest/start/python.html>`_
+| `Repository (Git) <https://github.com/msqd/harp>`_
+| `Issues <https://github.com/msqd/harp/issues>`_
+| `CI/CD <https://gitlab.com/makersquad/oss/harp/-/pipelines>`_
+
+
+How it works?
+:::::::::::::
+
+Overview
+--------
+
+.. figure:: https://github.com/msqd/harp/raw/dev/docs/images/HowItWorks-Overview.png
+    :alt: An overview of how HARP works in your system
+    :align: center
+
+* **Easy Integration:** Integrating with your application is a breeze, because it speaks the same language you already
+  use: HTTP. Simply run the proxy, update your API endpoints, and you're ready to go. No complex setup or extensive
+  configuration required. Of course, everything is modular and configurable, so you'll be able to fine-tune for your
+  taste later.
+* **Reduced Network Distance:** As a *nearline* proxy, HARP minimizes the network distance between your application
+  and external services, when possible, using standard techniques like caching or prefetching. This leads to faster
+  response times and improved overall performance of your application, even before any configuration is done.
+* **Simplified Development:** HARP eliminates the need for writing extensive code for functionalities such as caching,
+  monitoring, alerting, rate limiting, circuit breaking, retries, tracing, logging, and more. These features can be
+  easily delegated to the proxy, reducing the amount of code you need to write and maintain.
+* **Seamless HTTP Integration:** HARP seamlessly integrates with your application using the HTTP protocol. This means
+  that the integration or removal cost is virtually zero, or even negative when considering the reduction in code you
+  won't need to write.
+
+`Read the full documentation <https://harp-proxy.readthedocs.io/en/latest/>`_
+
+
+Hub to external services
+------------------------
+
+.. figure:: https://github.com/msqd/harp/raw/dev/docs/images/HowItWorks-OverviewMultipleApps.png
+    :alt: An overview of how HARP works in your system when you have multiple consumers
+    :align: center
+
+* **Mutualize Client Logic**: Having n API consumers does not mean you have to implement n times each client-side
+  feature. Use HARP as a hub and greatly reduce the amount of client code you need to write and maintain.
+* **Observes and Controls**: You get a central place to observe and control all your API interactions.
+* **Grow and Scale**: As your company grows and develop new applications, you can leverage the work done on existing
+  external services without having to write a single new line of code.
+
+
+Service
+-------
+
+Within the service, harp runs one or more proxies, each one listening to one port to instrument your external API calls
+with the features you need (auditing, caching, alerting, circuit breaker switch, health checks, etc.).
+
+Each proxy is configured to intercept and forward requests to a specific external API, with independent configuration.
+
+An additional (optional) port serves a dashboard to observe your proxies in real-time.
+
+.. figure:: https://github.com/msqd/harp/raw/dev/docs/images/HowItWorks-Service.png
+    :alt: What happens within the harp service
+    :align: center
+
+* **Features**: Harp comes builtin with a set of industry-standard client side features that you can leverage with a few
+  lines of configuration.
+* **Flexibility**: Each feature is optional, and it's up to you to chose the setup that fits your needs.
+* **Customizable**: You can write code to extend the proxy features, using the same interface as all the builtin
+  features. It guarantees that you can basically implement pretty much anything that make sense inbetween your
+  applications and the external services.
+
+
+Proxy
+-----
+
+As an HTTP Proxy, HARP does not change anything to the way you communicate with the external services. You were speaking
+HTTP before, you will still speak HTTP. The only change needed in your applications configuration to plug or unplug HARP
+is the base endpoint of the external services. In a modern 12factor-like application, it usually only means changing an
+environment variable.
+
+.. figure:: https://github.com/msqd/harp/raw/dev/docs/images/HowItWorks-Proxy.png
+    :alt: What happens within one harp proxy
+    :align: center
+
+* **Reversibility**: By requiring 0 code change on your application side (except endpoint url configuration, that
+  should be outside the code if you follow the 12factor principles), HARP can be plugged and unplugged at a very low
+  cost. You have absolutely no vendor lock-in.
+* **Sidecar**: Harp runs in your infrastructure, implementing the client side features right next to your application.
+  The service is fast, and the minimum network distance between your application and the proxy makes it even faster.
+* **Open Core**: Harp is an open software. The core and reference implementation of the proxy is open source, and you
+  can extend it to fit your needs.
+
+Proxy features
+--------------
+
+.. note:: (TODO) Add a list of features with links to the documentation.
+
+
+Credits
+:::::::
+
+* Core contributors:
+
+  - `Arthur Degonde <https://github.com/ArthurD1>`_
+  - `Romain Dorgueil <https://github.com/hartym>`_
+
+* Original idea, design, and development:
+
+  - `Romain Dorgueil <https://github.com/hartym>`_
+
+* Sponsored by `Makersquad <https://www.makersquad.fr/>`_
+
+`There are many ways you can contribute to HARP! <https://harp-proxy.readthedocs.io/en/latest/contribute/>`_

harp_proxy-0.5.0/docs/apps/dashboard/development/index.rst

@@ -0,0 +1,24 @@
+Dashboard
+=========
+
+.. toctree::
+   :maxdepth: 2
+
+   tests_unit
+   tests_e2e
+
+Recipes
+:::::::
+
+How to work on interface without the API?
+-----------------------------------------
+
+To work on pure interface development, it is often handy to work using the MSW API mocks instead of the real API.
+
+To do this, you can run the following command:
+
+.. code-block:: bash
+
+    harp start --mock
+
+Caveat: you must use localhost:4080 instead of the ipv6 url.

harp_proxy-0.5.0/docs/apps/dashboard/development/tests_e2e.rst

@@ -0,0 +1,152 @@
+End-to-End Tests
+================
+
+The :doc:`Dashboard Application </apps/dashboard/index>` uses Playwright for end-to-end testing.
+
+Playwright is a Node.js library for automating browser tasks. In our project, we use Playwright for end-to-end (E2E)
+testing. E2E tests simulate real user scenarios by running tests in a real browser environment.
+
+Here's an example of a basic Playwright test:
+
+.. code-block:: javascript
+
+    import { test, expect } from '@playwright/test';
+
+    test('Example test', async ({ page }) => {
+      await page.goto('https://example.com');
+      const title = await page.title();
+      expect(title).toBe('Example Domain');
+    });
+
+
+To run our E2E tests, we use the command `pnpm run test:browser`. This command starts Playwright, which opens a new
+browser window and runs our E2E tests.
+
+
+Running E2E Tests
+:::::::::::::::::
+
+To run all tests, use the following command in the dashboard application directory:
+
+.. code-block:: bash
+
+    pnpm test
+
+This will also include the :doc:`unit tests <./tests_unit>`. If you only want to run the browser tests, use the
+following command:
+
+.. code-block:: bash
+
+    pnpm test:browser
+
+We can also run a single test file by specifying the file path as an argument to the `test` command:
+
+.. code-block:: bash
+
+    pnpm run test:browser transactions.spec.ts
+
+
+Writing E2E Tests
+:::::::::::::::::
+
+We use Playwright for end-to-end testing to simulate real user interactions with our application.
+
+Playwright provides a high-level API to control headless or non-headless browsers, enabling us to automate browser
+tasks and test our application in real-world scenarios.
+
+.. code-block:: typescript
+
+    import { test, expect, request } from "@playwright/test"
+
+    test.beforeEach(async ({ page }) => {
+      await page.goto("/transactions")
+      await page.waitForFunction(() => document.body.innerText.includes("Endpoint"))
+    })
+
+    test.describe("Transactions Page", () => {
+      test("Interacting with the filter side bar", async ({ page }) => {
+        const requestMethodButton = await page.$('span:has-text("Request Method")')
+        const getLabel = await page.getByLabel("GET")
+        expect(getLabel).toBeVisible()
+
+        await requestMethodButton?.click()
+        expect(getLabel).not.toBeVisible()
+
+        const endpointButton = await page.getByText("Endpoint", { exact: true })
+        const endpoint1Label = await page.getByLabel("endpoint1")
+        expect(endpoint1Label).toBeVisible()
+
+        await endpointButton?.click()
+        expect(endpoint1Label).not.toBeVisible()
+      })
+    })
+
+In this example, we use Playwright to test the interactions with the filter sidebar on the Transactions page. We
+navigate to the Transactions page before each test and wait for the page to load. In the test, we simulate user
+interactions with the filter sidebar, such as clicking on buttons and checking the visibility of elements. We use
+Playwright's `expect` function to assert the expected outcomes of these interactions.
+
+This approach allows us to ensure that our application behaves as expected when users interact with it, providing us
+with confidence in the quality of our application.
+
+
+Overriding API Mocks
+--------------------
+
+In some cases, we might want to override the default handlers for a single test. We can do this by accessing the
+`worker` object on the `window` object and calling its `use` method with a new handler.
+
+.. code-block:: typescript
+
+    test("Override msw worker for system dependencies", async ({ page }) => {
+      // Test setup code here...
+
+      await page.evaluate(() => {
+        const { worker, http, HttpResponse } = window.msw
+        worker.use(
+          http.get("/api/system/dependencies", function override() {
+            return HttpResponse.json({ python: ["pydantic", "tensorflow"] })
+          }),
+        )
+      })
+
+      // Test code here...
+    })
+
+In this test, we override the handler for GET requests to `/api/system/dependencies` to return a predefined JSON
+response. This allows us to control the data that our application receives from the API in this specific test.
+
+
+Implementation details
+::::::::::::::::::::::
+
+In our project, we set up the Mock Service Worker (MSW) in development mode to mock API responses. This is done in the
+`main.tsx` file, where we conditionally import the MSW worker and start it if the application is running in development
+mode.
+
+.. code-block:: typescript
+
+    // Enable mocking in development using msw server set up for the browser
+    async function enableMocking() {
+      if (process.env.NODE_ENV !== "development") {
+        return
+      }
+
+      const { worker, http, HttpResponse } = await import("./tests/mocks/browser")
+
+      // @ts-ignore
+      // Propagate the worker and `http` references to be globally available.
+      // This would allow to modify request handlers on runtime.
+      window.msw = {
+        worker,
+        http,
+        HttpResponse,
+      }
+      return worker.start()
+    }
+
+In this function, we first check if the application is running in development mode. If it is, we dynamically import the
+MSW worker, `http`, and `HttpResponse` from our browser mocks. We then assign these to the `window.msw` object, making
+them globally available. This allows us to modify the request handlers at runtime, which is useful for overriding
+handlers in specific tests. Finally, we start the MSW worker, which begins intercepting network requests according to
+the predefined handlers.