Merge pull request #5 from G4brym/add-d1-binding

Add support for workers and D1 binding

Author: G4brym

README.md

@@ -1,60 +1,191 @@
 # django-cf
-Django database engine for Cloudflare D1 and Durable Objects
+django-cf is a package that integrates Django with Cloudflare products
+
+Integrations:
+ - Cloudflare D1
+ - Cloudflare Workers
 
 ## Installation
 
 ```bash
 pip install django-cf
 ```
 
-## Using with D1
+## Cloudflare D1
 
-The D1 engine uses the HTTP api directly from Cloudflare, meaning you only need to create a new D1 database, then
-create an API token with `D1 read` permission, and you are good to go!
+Cloudflare D1 doesn't support transactions, meaning all execute queries are final and rollbacks are not available.
+
+A simple tutorial is [available here](https://massadas.com/posts/django-meets-cloudflare-d1/) for you to read.
 
-But using an HTTP endpoint for executing queries one by one is very slow, and currently there is no way to accelerate
-it, until a websocket endpoint is available.
 
-The HTTP api doesn't support transactions, meaning all execute queries are final and rollbacks are not available.
+### D1 Binding
+
+You can now deploy Django into a Cloudflare Python Worker, and in that environment, D1 is available as a Binding for
+faster queries.
 
 ```python
 DATABASES = {
     'default': {
-        'ENGINE': 'django_d1',
+        'ENGINE': 'django_cf.d1_binding',
+        'CLOUDFLARE_BINDING': 'DB',
+    }
+}
+```
+
+### D1 API
+
+The D1 engine uses the HTTP api directly from Cloudflare, meaning you only need to create a new D1 database, then
+create an API token with `D1 read` and `D1 write` permission, and you are good to go!
+
+But using an HTTP endpoint for executing queries one by one is very slow, and currently there is no way to speed up
+it.
+
+```python
+DATABASES = {
+    'default': {
+        'ENGINE': 'django_cf.d1_api',
         'CLOUDFLARE_DATABASE_ID': '<database_id>',
         'CLOUDFLARE_ACCOUNT_ID': '<account_id>',
         'CLOUDFLARE_TOKEN': '<token>',
     }
 }
 ```
 
-The Cloudflare token requires D1 Edit permissions.
+## Cloudflare Workers
 
-A simple tutorial is [available here](https://massadas.com/posts/django-meets-cloudflare-d1/) for you to read.
+django-cf includes an adapter that allows you to run Django inside Cloudflare Workers named `DjangoCFAdapter`
+
+Suggested project structure
+```
+root
+ |-> src/
+ |-> src/manage.py
+ |-> src/worker.py               <-- Wrangler entrypoint
+ |-> src/your-apps-here/
+ |-> src/vendor/...              <-- Project dependencies, details bellow
+ |-> vendor.txt
+ |-> wrangler.jsonc
+```
+
+`vendor.txt`
+```txt
+django==5.1.2
+django-cf
+tzdata
+```
+
+`wrangler.jsonc`
+```jsonc
+{
+    "name": "django-on-workers",
+    "main": "src/worker.py",
+    "compatibility_flags": [
+        "python_workers_20250116",
+        "python_workers"
+    ],
+    "compatibility_date": "2025-04-10",
+    "assets": {
+      "directory": "./staticfiles/"
+    },
+    "rules": [
+        {
+            "globs": [
+                "vendor/**/*.py",
+                "vendor/**/*.mo",
+                "vendor/tzdata/**/",
+            ],
+            "type": "Data",
+            "fallthrough": true
+        }
+    ],
+    "d1_databases": [
+        {
+            "binding": "DB",
+            "database_name": "my-django-db",
+            "database_id": "924e612f-6293-4a3f-be66-cce441957b03",
+        }
+    ],
+    "observability": {
+        "enabled": true
+    }
+}
+```
 
-## Using with Durable Objects
+`src/worker.py`
+```python
+from django_cf import DjangoCFAdapter
 
-The DO engine, requires you to deploy [workers-dbms](https://github.com/G4brym/workers-dbms) on your cloudflare account.
-This engine uses a websocket endpoint to keep the connection alive, meaning sql queries are executed way faster.
+async def on_fetch(request, env):
+    from app.wsgi import application  # Update acording to your project structure
+    adapter = DjangoCFAdapter(application)
 
-workers-dbms have an experimental transaction support, everything should be working out of the box, but you should keep
-an eye out for weird issues and report them back.
+    return adapter.handle_request(request)
 
+```
 
+Then run this command to vendor your dependencies:
+```bash
+pip install -t src/vendor -r vendor.txt
+```
+
+To bundle static assets with your worker, add this line to your `settings.py`, this will place the assets outside the src folder
 ```python
-DATABASES = {
-    'default': {
-        'ENGINE': 'django_dbms',
-        'WORKERS_DBMS_ENDPOINT': '<websocket_endpoint>',  # This should start with wss://
-        'WORKERS_DBMS_ACCESS_ID': '<access_id>',  # Optional, but highly recommended!
-        'WORKERS_DBMS_ACCESS_SECRET': '<access_secret>',  # Optional, but highly recommended!
-    }
-}
+STATIC_URL = 'static/'
+STATIC_ROOT = BASE_DIR.parent.joinpath('staticfiles').joinpath('static')
 ```
 
+And this command generate the static assets:
+```bash
+python src/manage.py collectstatic
+```
+
+Now deploy your worker
+```bash
+npx wrangler deploy
+```
+
+### Running migrations and other commands
+In the ideal setup, your application will have two settings, one for production and another for development.
+
+- The production one, will connect to D1 via using the binding, as this is way faster.
+- The development one, will connect using the D1 API.
+
+Using this setup, you can apply the migrations from your local machine.
+
+In case that is not enought for you, here is a snippet that allows you to apply D1 migrations using a deployed worker:
+
+Just add these new routes to your `urls.py`:
+
+```python
+from django.contrib import admin
+from django.contrib.auth import get_user_model;
+from django.http import JsonResponse
+from django.urls import path
+
+def create_admin(request):
+    User = get_user_model();
+    User.objects.create_superuser('admin', '[email protected]', 'password')
+    return JsonResponse({"user": "ok"})
+
+def migrate(request):
+    from django.core.management import execute_from_command_line
+    execute_from_command_line(["manage.py", "migrate"])
+
+    return JsonResponse({"migrations": "ok"})
+
+urlpatterns = [
+    path('create-admin', create_admin),
+    path('migrate', migrate),
+    path('admin/', admin.site.urls),
+]
+```
+
+You may now call your worker to apply all missing migrations, ex: `https://django-on-workers.{username}.workers.dev/migrate`
 
 ## Limitations
 
 When using D1 engine, queries are expected to be slow, and transactions are disabled.
 
+A lot of query features are additionally disabled, for example inline sql functions, used extensively inside Django Admin
+
 Read all Django limitations for SQLite [databases here](https://docs.djangoproject.com/en/5.0/ref/databases/#sqlite-notes).

django_cf/__init__.py

@@ -0,0 +1,72 @@
+import os
+from io import BytesIO
+
+class DjangoCFAdapter:
+    def __init__(self, app):
+        self.app = app
+
+    async def handle_request(self, request):
+        os.environ.setdefault('DJANGO_ALLOW_ASYNC_UNSAFE', 'false')
+        from js import Object, Response, URL, console
+
+        headers = []
+        for header in request.headers:
+            headers.append(tuple([header[0], header[1]]))
+
+        url = URL.new(request.url)
+        assert url.protocol[-1] == ":"
+        scheme = url.protocol[:-1]
+        path = url.pathname
+        assert "?".startswith(url.search[0:1])
+        query_string = url.search[1:]
+        method = str(request.method).upper()
+
+        host = url.host.split(':')[0]
+
+        wsgi_request = {
+            'REQUEST_METHOD': method,
+            'PATH_INFO': path,
+            'QUERY_STRING': query_string,
+            'SERVER_NAME': host,
+            'SERVER_PORT': url.port,
+            'SERVER_PROTOCOL': 'HTTP/1.1',
+            'wsgi.input': BytesIO(b''),
+            'wsgi.errors': console.error,
+            'wsgi.version': (1, 0),
+            'wsgi.multithread': False,
+            'wsgi.multiprocess': False,
+            'wsgi.run_once': True,
+            'wsgi.url_scheme': scheme,
+        }
+
+        if request.headers.get('content-type'):
+            wsgi_request['CONTENT_TYPE'] = request.headers.get('content-type')
+
+        if request.headers.get('content-length'):
+            wsgi_request['CONTENT_LENGTH'] = request.headers.get('content-length')
+
+        for header in request.headers:
+            wsgi_request[f'HTTP_{header[0].upper()}'] = header[1]
+
+        if method in ['POST', 'PUT', 'PATCH']:
+            body = (await request.arrayBuffer()).to_bytes()
+            wsgi_request['wsgi.input'] = BytesIO(body)
+
+        def start_response(status_str, response_headers):
+            nonlocal status, headers
+            status = status_str
+            headers = response_headers
+
+        resp = self.app(wsgi_request, start_response)
+        status = resp.status_code
+        headers = resp.headers
+
+        final_response = Response.new(
+            resp.content.decode('utf-8'), headers=Object.fromEntries(headers.items()), status=status
+        )
+
+        for k, v in resp.cookies.items():
+            value = str(v)
+            final_response.headers.set('Set-Cookie', value.replace('Set-Cookie: ', '', 1));
+
+        return final_response

django_d1/__init__.py renamed to django_cf/d1_api/__init__.py

@@ -26,7 +26,7 @@ class DatabaseWrapper(SQLiteDatabaseWrapper):
     transaction_modes = frozenset([])
 
     def get_database_version(self):
-        return (4,)
+        return (4, )
 
     def get_connection_params(self):
         settings_dict = self.settings_dict