Rename PG Bouncer to PG Event Distributor

Author: janbjorge

docs/index.rst

@@ -18,5 +18,5 @@ The repository is hosted on `github <https://github.com/janbjorge/PGCacheWatch>`
    setup
    configuration
    strategies
-   pgb
+   pged
    examples

docs/pgb.md

@@ -0,0 +1,44 @@
+## PG Event Distributor
+
+The PG event distributor, is designed to enhance PGCacheWatch by enabling efficient distribution of PostgreSQL notifications to multiple clients. This service acts as a middleware, receiving notifications from PostgreSQL and broadcasting them to connected clients via WebSockets. This "fan-out" effect ensures real-time cache invalidation across all clients with minimal database connections.
+
+###  Key Benefits:
+
+- **Scalability**: Handles numerous clients without increasing load on the PostgreSQL server.
+- **Efficiency**: Reduces the need for multiple direct connections to PostgreSQL for NOTIFY/LISTEN.
+- **Real-time**: Ensures immediate cache invalidation across services upon database changes.
+
+### Illustration:
+
+```
+                                      +-------------------+
+                                      |   PostgreSQL DB   |
+                                      | - NOTIFY on event |
+                                      +---------+---------+
+                                                |
+                                                | NOTIFY
+                                                |
+                                      +---------v-------------+
+                                      |  PG Event Distributor |
+                                      |  Service              |
+                                      | - Fan-out NOTIFY      |
+                                      +---------+-------------+
+                                                |
+                                  +-------------+-------------+
+                                  |                           |
+                          +-------v-------+           +-------v-------+
+                          | WebSocket     |           | WebSocket     |
+                          | Client 1      |           | Client N      |
+                          | - Invalidate  |           | - Invalidate  |
+                          |   Cache       |           |   Cache       |
+                          +---------------+           +---------------+
+```
+
+To leverage the PG Event Distributor within your PGCacheWatch setup, ensure it's running and accessible by your application. Configure PGCacheWatch to connect to the PG Event Distributor instead of directly to PostgreSQL for notifications. This setup amplifies the effectiveness of your cache invalidation strategy by ensuring timely updates across all client caches with optimized resource usage.
+
+### Running the PG Event Distributor
+To start the PG Event Distributor service, use the following command in your terminal. This command utilizes uvicorn, an ASGI server, to run the service defined in the `pgcachewatch.pg_event_distributor:main` module. The --factory flag is used to indicate that uvicorn should call the provided application factory function to get the ASGI application instance.
+
+```bash
+uvicorn pgcachewatch.pg_event_distributor:main --factory
+```

docs/pged.md

@@ -4,7 +4,7 @@
 among multiple clients
 
 Usage example:
-`uvicorn pgcachewatch.pg_bouncer:main --factory`
+`uvicorn pgcachewatch.pg_event_distributor:main --factory`
 """
 
 import asyncio

src/pgcachewatch/pg_bouncer.py renamed to src/pgcachewatch/pg_event_distributor.py

@@ -14,7 +14,7 @@ def pgb_address() -> str:
     return "127.0.0.1:8000"
 
 
-async def pg_bouncer_isup() -> bool:
+async def pg_event_distributor_isup() -> bool:
     timeout = timedelta(seconds=1)
     deadline = datetime.now() + timeout
 
@@ -61,13 +61,13 @@ def set_pg_envs(monkeypatch: pytest.MonkeyPatch) -> None:
 
 
 @pytest.fixture(scope="function")
-async def pgbapp() -> AsyncGenerator[Popen, None]:
+async def pgedapp() -> AsyncGenerator[Popen, None]:
     with Popen(
-        "uvicorn pgcachewatch.pg_bouncer:main --factory".split(),
+        "uvicorn pgcachewatch.pg_event_distributor:main --factory".split(),
         stderr=PIPE,
         stdout=PIPE,
     ) as p:
-        await pg_bouncer_isup()
+        await pg_event_distributor_isup()
         try:
             yield p
         finally:

tests/conftest.py

@@ -48,7 +48,7 @@ async def test_eventqueue_and_pglistner(
 @pytest.mark.parametrize("N", (1, 8, 32))
 @pytest.mark.parametrize("operation", get_args(models.OPERATIONS))
 async def test_eventqueue_and_wslistner(
-    pgbapp: Popen,
+    pgedapp: Popen,
     N: int,
     operation: models.OPERATIONS,
     pgpool: asyncpg.Pool,

tests/test_listeners.py

@@ -6,18 +6,18 @@
 import asyncpg
 import pytest
 import websockets
-from conftest import pg_bouncer_isup, pgb_address
+from conftest import pg_event_distributor_isup, pgb_address
 from pgcachewatch import listeners, models, utils
 
 
-async def test_up_endpoint(pgbapp: Popen) -> None:
-    assert await pg_bouncer_isup()
+async def test_up_endpoint(pgedapp: Popen) -> None:
+    assert await pg_event_distributor_isup()
 
 
 @pytest.mark.parametrize("operation", get_args(models.OPERATIONS))
 @pytest.mark.parametrize("N", (1, 8))
 async def test_ws_broadcast(
-    pgbapp: Popen,
+    pgedapp: Popen,
     N: int,
     pgpool: asyncpg.Pool,
     operation: models.OPERATIONS,
@@ -99,7 +99,7 @@ async def test_put_ws_event_queue(
 @pytest.mark.parametrize("operation", get_args(models.OPERATIONS))
 @pytest.mark.parametrize("N", (1, 64))
 async def test_put_on_event_ws_event_queue(
-    pgbapp: Popen,
+    pgedapp: Popen,
     N: int,
     pgpool: asyncpg.Pool,
     operation: models.OPERATIONS,
@@ -133,7 +133,7 @@ async def test_put_on_event_ws_event_queue(
 
 
 async def test_ws_event_queue_connection_healthy(
-    pgbapp: Popen,
+    pgedapp: Popen,
     channel: models.PGChannel = models.PGChannel(
         "test_ws_event_queue_connection_healthy"
     ),