constile-gate 0.6.0__tar.gz
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- constile_gate-0.6.0/LICENSE +21 -0
- constile_gate-0.6.0/PKG-INFO +257 -0
- constile_gate-0.6.0/README.md +238 -0
- constile_gate-0.6.0/pyproject.toml +32 -0
- constile_gate-0.6.0/setup.cfg +4 -0
- constile_gate-0.6.0/src/constile_gate/__init__.py +23 -0
- constile_gate-0.6.0/src/constile_gate/_adapter.py +177 -0
- constile_gate-0.6.0/src/constile_gate/_charset.py +191 -0
- constile_gate-0.6.0/src/constile_gate/_js.py +123 -0
- constile_gate-0.6.0/src/constile_gate/agents.py +101 -0
- constile_gate-0.6.0/src/constile_gate/asgi.py +318 -0
- constile_gate-0.6.0/src/constile_gate/core.py +784 -0
- constile_gate-0.6.0/src/constile_gate/django.py +154 -0
- constile_gate-0.6.0/src/constile_gate/driver.py +196 -0
- constile_gate-0.6.0/src/constile_gate/fastapi.py +14 -0
- constile_gate-0.6.0/src/constile_gate/flask.py +52 -0
- constile_gate-0.6.0/src/constile_gate/page_meta.py +88 -0
- constile_gate-0.6.0/src/constile_gate/py.typed +0 -0
- constile_gate-0.6.0/src/constile_gate/starlette.py +15 -0
- constile_gate-0.6.0/src/constile_gate/transport.py +43 -0
- constile_gate-0.6.0/src/constile_gate/wsgi.py +262 -0
- constile_gate-0.6.0/src/constile_gate.egg-info/PKG-INFO +257 -0
- constile_gate-0.6.0/src/constile_gate.egg-info/SOURCES.txt +23 -0
- constile_gate-0.6.0/src/constile_gate.egg-info/dependency_links.txt +1 -0
- constile_gate-0.6.0/src/constile_gate.egg-info/top_level.txt +1 -0
|
@@ -0,0 +1,21 @@
|
|
|
1
|
+
MIT License
|
|
2
|
+
|
|
3
|
+
Copyright (c) 2026 CCC2C Inc.
|
|
4
|
+
|
|
5
|
+
Permission is hereby granted, free of charge, to any person obtaining a copy
|
|
6
|
+
of this software and associated documentation files (the "Software"), to deal
|
|
7
|
+
in the Software without restriction, including without limitation the rights
|
|
8
|
+
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
|
|
9
|
+
copies of the Software, and to permit persons to whom the Software is
|
|
10
|
+
furnished to do so, subject to the following conditions:
|
|
11
|
+
|
|
12
|
+
The above copyright notice and this permission notice shall be included in all
|
|
13
|
+
copies or substantial portions of the Software.
|
|
14
|
+
|
|
15
|
+
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
|
|
16
|
+
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
|
|
17
|
+
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
|
|
18
|
+
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
|
|
19
|
+
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
|
|
20
|
+
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
|
|
21
|
+
SOFTWARE.
|
|
@@ -0,0 +1,257 @@
|
|
|
1
|
+
Metadata-Version: 2.4
|
|
2
|
+
Name: constile-gate
|
|
3
|
+
Version: 0.6.0
|
|
4
|
+
Summary: The Constile gate for Python sites: WSGI and ASGI middleware, with Django, Flask, and FastAPI wiring.
|
|
5
|
+
Author-email: "CCC2C Inc." <hello@constile.app>
|
|
6
|
+
License-Expression: MIT
|
|
7
|
+
Project-URL: Homepage, https://constile.app
|
|
8
|
+
Project-URL: Documentation, https://constile.app/setup/python
|
|
9
|
+
Classifier: Programming Language :: Python :: 3
|
|
10
|
+
Classifier: Programming Language :: Python :: 3 :: Only
|
|
11
|
+
Classifier: Framework :: Django
|
|
12
|
+
Classifier: Framework :: Flask
|
|
13
|
+
Classifier: Framework :: FastAPI
|
|
14
|
+
Classifier: Topic :: Internet :: WWW/HTTP :: WSGI :: Middleware
|
|
15
|
+
Requires-Python: >=3.9
|
|
16
|
+
Description-Content-Type: text/markdown
|
|
17
|
+
License-File: LICENSE
|
|
18
|
+
Dynamic: license-file
|
|
19
|
+
|
|
20
|
+
# Constile gate for Python
|
|
21
|
+
|
|
22
|
+
The Constile gate serves the Constile offer to AI agents that
|
|
23
|
+
fetch your pages for a person. Everyone else, including people, search
|
|
24
|
+
engines, and training crawlers, gets your site as usual.
|
|
25
|
+
|
|
26
|
+
This package runs the gate inside your Python app. It works with Django,
|
|
27
|
+
Flask, FastAPI, Starlette, and any other WSGI or ASGI app. It needs Python 3.9
|
|
28
|
+
or later and nothing outside the standard library.
|
|
29
|
+
|
|
30
|
+
## How the gate works
|
|
31
|
+
|
|
32
|
+
- **People** reach your app untouched. Their responses stream from your app
|
|
33
|
+
as before. The gate reads only the site config, which it caches.
|
|
34
|
+
- **Agents** on an eligible page: the gate asks your app for the page
|
|
35
|
+
in-process, reads its title, description, keywords, and section, and asks
|
|
36
|
+
the Constile network for an offer. If the network has one, the agent
|
|
37
|
+
gets the offer. If not, the agent gets the page.
|
|
38
|
+
- **`/sponsored/*` and `/.well-known/constile`** are answered by the gate.
|
|
39
|
+
- **When the network is down or slow**, visitors get the page as if the gate
|
|
40
|
+
weren't there. The gate waits at most 5 seconds by default. After it fails
|
|
41
|
+
to get the site config, it doesn't ask again for 30 seconds, so an outage
|
|
42
|
+
doesn't slow your pages down.
|
|
43
|
+
|
|
44
|
+
## Before you start
|
|
45
|
+
|
|
46
|
+
You need three values from your site's page in the Constile dashboard:
|
|
47
|
+
the site ID, the site secret, and the network URL. Set them as environment
|
|
48
|
+
variables where your app runs:
|
|
49
|
+
|
|
50
|
+
```sh
|
|
51
|
+
export CONSTILE_SITE_ID="your-site-id"
|
|
52
|
+
export CONSTILE_SITE_SECRET="your-site-secret"
|
|
53
|
+
export CONSTILE_NETWORK_URL="https://constile.app"
|
|
54
|
+
```
|
|
55
|
+
|
|
56
|
+
Keep the site secret out of your repository. Store it the way you store your
|
|
57
|
+
other secrets, such as in your host's secret settings.
|
|
58
|
+
|
|
59
|
+
If any of the three is missing, the gate passes every request through and logs
|
|
60
|
+
one warning.
|
|
61
|
+
|
|
62
|
+
## Install the package
|
|
63
|
+
|
|
64
|
+
```sh
|
|
65
|
+
pip install constile-gate
|
|
66
|
+
```
|
|
67
|
+
|
|
68
|
+
Or install the copy the network serves:
|
|
69
|
+
|
|
70
|
+
```sh
|
|
71
|
+
pip install "https://constile.app/install/constile_gate-0.6.0-py3-none-any.whl"
|
|
72
|
+
```
|
|
73
|
+
|
|
74
|
+
Then add the gate to your app with one of the following sections.
|
|
75
|
+
|
|
76
|
+
## Django
|
|
77
|
+
|
|
78
|
+
1. In `settings.py`, add the middleware first in `MIDDLEWARE`:
|
|
79
|
+
|
|
80
|
+
```python
|
|
81
|
+
MIDDLEWARE = [
|
|
82
|
+
"constile_gate.django.ConstileMiddleware",
|
|
83
|
+
# ...your other middleware
|
|
84
|
+
]
|
|
85
|
+
```
|
|
86
|
+
|
|
87
|
+
Putting it first means it runs before page caches and redirects.
|
|
88
|
+
|
|
89
|
+
1. Set the three values as environment variables, or in `settings.py`:
|
|
90
|
+
|
|
91
|
+
```python
|
|
92
|
+
import os
|
|
93
|
+
|
|
94
|
+
CONSTILE_SITE_ID = os.environ["CONSTILE_SITE_ID"]
|
|
95
|
+
CONSTILE_SITE_SECRET = os.environ["CONSTILE_SITE_SECRET"]
|
|
96
|
+
CONSTILE_NETWORK_URL = os.environ["CONSTILE_NETWORK_URL"]
|
|
97
|
+
```
|
|
98
|
+
|
|
99
|
+
The gate builds each page's URL with `request.build_absolute_uri()`, so your
|
|
100
|
+
`ALLOWED_HOSTS` and `SECURE_PROXY_SSL_HEADER` settings apply.
|
|
101
|
+
|
|
102
|
+
## Flask
|
|
103
|
+
|
|
104
|
+
Wrap your app with the extension:
|
|
105
|
+
|
|
106
|
+
```python
|
|
107
|
+
from flask import Flask
|
|
108
|
+
from constile_gate.flask import Constile
|
|
109
|
+
|
|
110
|
+
app = Flask(__name__)
|
|
111
|
+
Constile(app)
|
|
112
|
+
```
|
|
113
|
+
|
|
114
|
+
If you use an app factory, create the extension once and call `init_app`:
|
|
115
|
+
|
|
116
|
+
```python
|
|
117
|
+
constile = Constile()
|
|
118
|
+
|
|
119
|
+
def create_app():
|
|
120
|
+
app = Flask(__name__)
|
|
121
|
+
constile.init_app(app)
|
|
122
|
+
return app
|
|
123
|
+
```
|
|
124
|
+
|
|
125
|
+
The extension reads `CONSTILE_SITE_ID`, `CONSTILE_SITE_SECRET`, and `CONSTILE_NETWORK_URL`
|
|
126
|
+
from `app.config` first, then from the environment.
|
|
127
|
+
|
|
128
|
+
If you use Werkzeug's `ProxyFix`, apply it after the extension, so it runs
|
|
129
|
+
first and the gate sees the corrected address:
|
|
130
|
+
|
|
131
|
+
```python
|
|
132
|
+
Constile(app)
|
|
133
|
+
app.wsgi_app = ProxyFix(app.wsgi_app, x_for=1, x_proto=1, x_host=1)
|
|
134
|
+
```
|
|
135
|
+
|
|
136
|
+
## FastAPI
|
|
137
|
+
|
|
138
|
+
Add the middleware after your other middleware, so it's the outermost:
|
|
139
|
+
|
|
140
|
+
```python
|
|
141
|
+
from fastapi import FastAPI
|
|
142
|
+
from constile_gate.fastapi import ConstileMiddleware
|
|
143
|
+
|
|
144
|
+
app = FastAPI()
|
|
145
|
+
# app.add_middleware(...your other middleware)
|
|
146
|
+
app.add_middleware(ConstileMiddleware)
|
|
147
|
+
```
|
|
148
|
+
|
|
149
|
+
The gate's network calls run in threads, so they never block the event loop.
|
|
150
|
+
|
|
151
|
+
## Starlette
|
|
152
|
+
|
|
153
|
+
Put the middleware first in the list, so it's the outermost:
|
|
154
|
+
|
|
155
|
+
```python
|
|
156
|
+
from starlette.applications import Starlette
|
|
157
|
+
from starlette.middleware import Middleware
|
|
158
|
+
from constile_gate.starlette import ConstileMiddleware
|
|
159
|
+
|
|
160
|
+
app = Starlette(routes=routes, middleware=[Middleware(ConstileMiddleware)])
|
|
161
|
+
```
|
|
162
|
+
|
|
163
|
+
## Any other WSGI or ASGI app
|
|
164
|
+
|
|
165
|
+
To gate a WSGI app, such as Bottle or Pyramid, wrap it:
|
|
166
|
+
|
|
167
|
+
```python
|
|
168
|
+
from constile_gate.wsgi import ConstileMiddleware
|
|
169
|
+
|
|
170
|
+
application = ConstileMiddleware(application)
|
|
171
|
+
```
|
|
172
|
+
|
|
173
|
+
To gate an ASGI app, such as Quart or Django's ASGI handler, wrap it the same
|
|
174
|
+
way with `constile_gate.asgi.ConstileMiddleware`.
|
|
175
|
+
|
|
176
|
+
## Settings
|
|
177
|
+
|
|
178
|
+
Each setting comes from, in order: the middleware's keyword argument, your
|
|
179
|
+
framework's settings (Django settings or Flask `app.config`), and the
|
|
180
|
+
environment variable.
|
|
181
|
+
|
|
182
|
+
| Environment variable | Keyword argument | Description |
|
|
183
|
+
|---|---|---|
|
|
184
|
+
| `CONSTILE_SITE_ID` | `site_id` | Required. Your site ID. |
|
|
185
|
+
| `CONSTILE_SITE_SECRET` | `secret` | Required. Your site secret. |
|
|
186
|
+
| `CONSTILE_NETWORK_URL` | `network_url` | Required. The network URL. |
|
|
187
|
+
| `CONSTILE_TRUSTED_PROXIES` | `trusted_proxies` | Optional. The addresses or networks of proxies in front of your app, such as `10.0.0.0/8, 192.0.2.1`. |
|
|
188
|
+
| `CONSTILE_TIMEOUT` | `timeout` | Optional. Seconds to wait for the network before serving the page anyway. The default is 5. |
|
|
189
|
+
| `CONSTILE_RETRY_AFTER` | `retry_after` | Optional. After the gate fails to get the site config, seconds to pass every request through before it asks again. The default is 30. |
|
|
190
|
+
| `CONSTILE_DISABLED` | `disabled` | Optional. `1`, `true`, `yes`, or `on` turns the gate off: every request goes to your app unchanged, and nothing goes to the network. Read on every request. |
|
|
191
|
+
|
|
192
|
+
The gate logs to the `constile_gate` logger.
|
|
193
|
+
|
|
194
|
+
## The visitor's address
|
|
195
|
+
|
|
196
|
+
For a request that claims to come from a registered agent, the gate sends the
|
|
197
|
+
visitor's address to the network. The network checks it against the agent
|
|
198
|
+
operator's published addresses, so a request that only claims to be an agent
|
|
199
|
+
earns no money.
|
|
200
|
+
|
|
201
|
+
The gate reads the address from the connection: `REMOTE_ADDR` for WSGI and
|
|
202
|
+
Django, and the `client` of the ASGI scope. It reads `X-Forwarded-For` only
|
|
203
|
+
when you list your proxies in `CONSTILE_TRUSTED_PROXIES`. It then reads the header
|
|
204
|
+
from the right, skips your proxies, and takes the first address that isn't
|
|
205
|
+
one of them. A visitor can't forge that address, because your proxies add it.
|
|
206
|
+
|
|
207
|
+
If something in front of the gate already resolves the address, leave
|
|
208
|
+
`CONSTILE_TRUSTED_PROXIES` unset. For example, uvicorn with
|
|
209
|
+
`--forwarded-allow-ips` set to your proxies, and Werkzeug's `ProxyFix`, both
|
|
210
|
+
set the address the gate reads.
|
|
211
|
+
|
|
212
|
+
## Placement and caches
|
|
213
|
+
|
|
214
|
+
- Install the gate at the root of your host. The gate answers `/sponsored/*`
|
|
215
|
+
and `/.well-known/constile` there. An app mounted under a sub-path, such as
|
|
216
|
+
`/blog`, can't answer them.
|
|
217
|
+
- Keep page caches inside the gate, so an agent never gets a cached page. In
|
|
218
|
+
Django, list the gate before `UpdateCacheMiddleware`. If a cache sits in
|
|
219
|
+
front of your app, such as a CDN or nginx's `proxy_cache`, make it skip
|
|
220
|
+
requests whose `User-Agent` names a registered agent or that carry a
|
|
221
|
+
`Signature` header. Offers carry `Cache-Control: no-store` and
|
|
222
|
+
`Vary: User-Agent`, so caches don't store them.
|
|
223
|
+
- When the gate asks your app for an agent's page, it leaves out the agent's
|
|
224
|
+
`Accept-Encoding` header, so your app answers uncompressed. If your app
|
|
225
|
+
compresses anyway, the gate reads gzip and deflate, but not Brotli or
|
|
226
|
+
Zstandard: an agent then gets the page without an offer. People's requests
|
|
227
|
+
keep their `Accept-Encoding`, so they still get compressed pages.
|
|
228
|
+
- The gate reads a page's title and description in the charset its
|
|
229
|
+
`Content-Type` header names, such as `charset=iso-8859-1`, and as UTF-8 when
|
|
230
|
+
it names none. A page it passes through keeps its exact bytes.
|
|
231
|
+
|
|
232
|
+
## Paywalled content
|
|
233
|
+
|
|
234
|
+
Gate 0.6.0 and later can fetch a paywalled article with the release
|
|
235
|
+
instructions the network sends, so an agent gets the full text and the offer
|
|
236
|
+
fits it. The network gives the gate a page address on your site's own host
|
|
237
|
+
and, optionally, headers to send: `Cookie`, `Authorization`,
|
|
238
|
+
`Constile-Paywall-Key`, or a header starting with `X-`. The gate ignores an
|
|
239
|
+
address on another host and drops other headers. It strips `Set-Cookie` from
|
|
240
|
+
what it releases and never logs the headers. To set up a method, open your
|
|
241
|
+
site's page in the dashboard and choose a content API, a paywall rule, or a
|
|
242
|
+
Constile login. A paywalled page gets offers only after the method works and
|
|
243
|
+
the gate is 0.6.0 or later.
|
|
244
|
+
|
|
245
|
+
## Check the install
|
|
246
|
+
|
|
247
|
+
Open `https://your-site/.well-known/constile`. You see JSON that names your
|
|
248
|
+
site ID, `"gate_version": "constile-gate 0.6.0"`, and the platform, such as
|
|
249
|
+
`"django"`. The install check on your dashboard reads the same address.
|
|
250
|
+
|
|
251
|
+
## Support
|
|
252
|
+
|
|
253
|
+
Write to <hello@constile.app>, or see the [setup guides](https://constile.app/setup).
|
|
254
|
+
|
|
255
|
+
## License
|
|
256
|
+
|
|
257
|
+
MIT. See LICENSE.
|
|
@@ -0,0 +1,238 @@
|
|
|
1
|
+
# Constile gate for Python
|
|
2
|
+
|
|
3
|
+
The Constile gate serves the Constile offer to AI agents that
|
|
4
|
+
fetch your pages for a person. Everyone else, including people, search
|
|
5
|
+
engines, and training crawlers, gets your site as usual.
|
|
6
|
+
|
|
7
|
+
This package runs the gate inside your Python app. It works with Django,
|
|
8
|
+
Flask, FastAPI, Starlette, and any other WSGI or ASGI app. It needs Python 3.9
|
|
9
|
+
or later and nothing outside the standard library.
|
|
10
|
+
|
|
11
|
+
## How the gate works
|
|
12
|
+
|
|
13
|
+
- **People** reach your app untouched. Their responses stream from your app
|
|
14
|
+
as before. The gate reads only the site config, which it caches.
|
|
15
|
+
- **Agents** on an eligible page: the gate asks your app for the page
|
|
16
|
+
in-process, reads its title, description, keywords, and section, and asks
|
|
17
|
+
the Constile network for an offer. If the network has one, the agent
|
|
18
|
+
gets the offer. If not, the agent gets the page.
|
|
19
|
+
- **`/sponsored/*` and `/.well-known/constile`** are answered by the gate.
|
|
20
|
+
- **When the network is down or slow**, visitors get the page as if the gate
|
|
21
|
+
weren't there. The gate waits at most 5 seconds by default. After it fails
|
|
22
|
+
to get the site config, it doesn't ask again for 30 seconds, so an outage
|
|
23
|
+
doesn't slow your pages down.
|
|
24
|
+
|
|
25
|
+
## Before you start
|
|
26
|
+
|
|
27
|
+
You need three values from your site's page in the Constile dashboard:
|
|
28
|
+
the site ID, the site secret, and the network URL. Set them as environment
|
|
29
|
+
variables where your app runs:
|
|
30
|
+
|
|
31
|
+
```sh
|
|
32
|
+
export CONSTILE_SITE_ID="your-site-id"
|
|
33
|
+
export CONSTILE_SITE_SECRET="your-site-secret"
|
|
34
|
+
export CONSTILE_NETWORK_URL="https://constile.app"
|
|
35
|
+
```
|
|
36
|
+
|
|
37
|
+
Keep the site secret out of your repository. Store it the way you store your
|
|
38
|
+
other secrets, such as in your host's secret settings.
|
|
39
|
+
|
|
40
|
+
If any of the three is missing, the gate passes every request through and logs
|
|
41
|
+
one warning.
|
|
42
|
+
|
|
43
|
+
## Install the package
|
|
44
|
+
|
|
45
|
+
```sh
|
|
46
|
+
pip install constile-gate
|
|
47
|
+
```
|
|
48
|
+
|
|
49
|
+
Or install the copy the network serves:
|
|
50
|
+
|
|
51
|
+
```sh
|
|
52
|
+
pip install "https://constile.app/install/constile_gate-0.6.0-py3-none-any.whl"
|
|
53
|
+
```
|
|
54
|
+
|
|
55
|
+
Then add the gate to your app with one of the following sections.
|
|
56
|
+
|
|
57
|
+
## Django
|
|
58
|
+
|
|
59
|
+
1. In `settings.py`, add the middleware first in `MIDDLEWARE`:
|
|
60
|
+
|
|
61
|
+
```python
|
|
62
|
+
MIDDLEWARE = [
|
|
63
|
+
"constile_gate.django.ConstileMiddleware",
|
|
64
|
+
# ...your other middleware
|
|
65
|
+
]
|
|
66
|
+
```
|
|
67
|
+
|
|
68
|
+
Putting it first means it runs before page caches and redirects.
|
|
69
|
+
|
|
70
|
+
1. Set the three values as environment variables, or in `settings.py`:
|
|
71
|
+
|
|
72
|
+
```python
|
|
73
|
+
import os
|
|
74
|
+
|
|
75
|
+
CONSTILE_SITE_ID = os.environ["CONSTILE_SITE_ID"]
|
|
76
|
+
CONSTILE_SITE_SECRET = os.environ["CONSTILE_SITE_SECRET"]
|
|
77
|
+
CONSTILE_NETWORK_URL = os.environ["CONSTILE_NETWORK_URL"]
|
|
78
|
+
```
|
|
79
|
+
|
|
80
|
+
The gate builds each page's URL with `request.build_absolute_uri()`, so your
|
|
81
|
+
`ALLOWED_HOSTS` and `SECURE_PROXY_SSL_HEADER` settings apply.
|
|
82
|
+
|
|
83
|
+
## Flask
|
|
84
|
+
|
|
85
|
+
Wrap your app with the extension:
|
|
86
|
+
|
|
87
|
+
```python
|
|
88
|
+
from flask import Flask
|
|
89
|
+
from constile_gate.flask import Constile
|
|
90
|
+
|
|
91
|
+
app = Flask(__name__)
|
|
92
|
+
Constile(app)
|
|
93
|
+
```
|
|
94
|
+
|
|
95
|
+
If you use an app factory, create the extension once and call `init_app`:
|
|
96
|
+
|
|
97
|
+
```python
|
|
98
|
+
constile = Constile()
|
|
99
|
+
|
|
100
|
+
def create_app():
|
|
101
|
+
app = Flask(__name__)
|
|
102
|
+
constile.init_app(app)
|
|
103
|
+
return app
|
|
104
|
+
```
|
|
105
|
+
|
|
106
|
+
The extension reads `CONSTILE_SITE_ID`, `CONSTILE_SITE_SECRET`, and `CONSTILE_NETWORK_URL`
|
|
107
|
+
from `app.config` first, then from the environment.
|
|
108
|
+
|
|
109
|
+
If you use Werkzeug's `ProxyFix`, apply it after the extension, so it runs
|
|
110
|
+
first and the gate sees the corrected address:
|
|
111
|
+
|
|
112
|
+
```python
|
|
113
|
+
Constile(app)
|
|
114
|
+
app.wsgi_app = ProxyFix(app.wsgi_app, x_for=1, x_proto=1, x_host=1)
|
|
115
|
+
```
|
|
116
|
+
|
|
117
|
+
## FastAPI
|
|
118
|
+
|
|
119
|
+
Add the middleware after your other middleware, so it's the outermost:
|
|
120
|
+
|
|
121
|
+
```python
|
|
122
|
+
from fastapi import FastAPI
|
|
123
|
+
from constile_gate.fastapi import ConstileMiddleware
|
|
124
|
+
|
|
125
|
+
app = FastAPI()
|
|
126
|
+
# app.add_middleware(...your other middleware)
|
|
127
|
+
app.add_middleware(ConstileMiddleware)
|
|
128
|
+
```
|
|
129
|
+
|
|
130
|
+
The gate's network calls run in threads, so they never block the event loop.
|
|
131
|
+
|
|
132
|
+
## Starlette
|
|
133
|
+
|
|
134
|
+
Put the middleware first in the list, so it's the outermost:
|
|
135
|
+
|
|
136
|
+
```python
|
|
137
|
+
from starlette.applications import Starlette
|
|
138
|
+
from starlette.middleware import Middleware
|
|
139
|
+
from constile_gate.starlette import ConstileMiddleware
|
|
140
|
+
|
|
141
|
+
app = Starlette(routes=routes, middleware=[Middleware(ConstileMiddleware)])
|
|
142
|
+
```
|
|
143
|
+
|
|
144
|
+
## Any other WSGI or ASGI app
|
|
145
|
+
|
|
146
|
+
To gate a WSGI app, such as Bottle or Pyramid, wrap it:
|
|
147
|
+
|
|
148
|
+
```python
|
|
149
|
+
from constile_gate.wsgi import ConstileMiddleware
|
|
150
|
+
|
|
151
|
+
application = ConstileMiddleware(application)
|
|
152
|
+
```
|
|
153
|
+
|
|
154
|
+
To gate an ASGI app, such as Quart or Django's ASGI handler, wrap it the same
|
|
155
|
+
way with `constile_gate.asgi.ConstileMiddleware`.
|
|
156
|
+
|
|
157
|
+
## Settings
|
|
158
|
+
|
|
159
|
+
Each setting comes from, in order: the middleware's keyword argument, your
|
|
160
|
+
framework's settings (Django settings or Flask `app.config`), and the
|
|
161
|
+
environment variable.
|
|
162
|
+
|
|
163
|
+
| Environment variable | Keyword argument | Description |
|
|
164
|
+
|---|---|---|
|
|
165
|
+
| `CONSTILE_SITE_ID` | `site_id` | Required. Your site ID. |
|
|
166
|
+
| `CONSTILE_SITE_SECRET` | `secret` | Required. Your site secret. |
|
|
167
|
+
| `CONSTILE_NETWORK_URL` | `network_url` | Required. The network URL. |
|
|
168
|
+
| `CONSTILE_TRUSTED_PROXIES` | `trusted_proxies` | Optional. The addresses or networks of proxies in front of your app, such as `10.0.0.0/8, 192.0.2.1`. |
|
|
169
|
+
| `CONSTILE_TIMEOUT` | `timeout` | Optional. Seconds to wait for the network before serving the page anyway. The default is 5. |
|
|
170
|
+
| `CONSTILE_RETRY_AFTER` | `retry_after` | Optional. After the gate fails to get the site config, seconds to pass every request through before it asks again. The default is 30. |
|
|
171
|
+
| `CONSTILE_DISABLED` | `disabled` | Optional. `1`, `true`, `yes`, or `on` turns the gate off: every request goes to your app unchanged, and nothing goes to the network. Read on every request. |
|
|
172
|
+
|
|
173
|
+
The gate logs to the `constile_gate` logger.
|
|
174
|
+
|
|
175
|
+
## The visitor's address
|
|
176
|
+
|
|
177
|
+
For a request that claims to come from a registered agent, the gate sends the
|
|
178
|
+
visitor's address to the network. The network checks it against the agent
|
|
179
|
+
operator's published addresses, so a request that only claims to be an agent
|
|
180
|
+
earns no money.
|
|
181
|
+
|
|
182
|
+
The gate reads the address from the connection: `REMOTE_ADDR` for WSGI and
|
|
183
|
+
Django, and the `client` of the ASGI scope. It reads `X-Forwarded-For` only
|
|
184
|
+
when you list your proxies in `CONSTILE_TRUSTED_PROXIES`. It then reads the header
|
|
185
|
+
from the right, skips your proxies, and takes the first address that isn't
|
|
186
|
+
one of them. A visitor can't forge that address, because your proxies add it.
|
|
187
|
+
|
|
188
|
+
If something in front of the gate already resolves the address, leave
|
|
189
|
+
`CONSTILE_TRUSTED_PROXIES` unset. For example, uvicorn with
|
|
190
|
+
`--forwarded-allow-ips` set to your proxies, and Werkzeug's `ProxyFix`, both
|
|
191
|
+
set the address the gate reads.
|
|
192
|
+
|
|
193
|
+
## Placement and caches
|
|
194
|
+
|
|
195
|
+
- Install the gate at the root of your host. The gate answers `/sponsored/*`
|
|
196
|
+
and `/.well-known/constile` there. An app mounted under a sub-path, such as
|
|
197
|
+
`/blog`, can't answer them.
|
|
198
|
+
- Keep page caches inside the gate, so an agent never gets a cached page. In
|
|
199
|
+
Django, list the gate before `UpdateCacheMiddleware`. If a cache sits in
|
|
200
|
+
front of your app, such as a CDN or nginx's `proxy_cache`, make it skip
|
|
201
|
+
requests whose `User-Agent` names a registered agent or that carry a
|
|
202
|
+
`Signature` header. Offers carry `Cache-Control: no-store` and
|
|
203
|
+
`Vary: User-Agent`, so caches don't store them.
|
|
204
|
+
- When the gate asks your app for an agent's page, it leaves out the agent's
|
|
205
|
+
`Accept-Encoding` header, so your app answers uncompressed. If your app
|
|
206
|
+
compresses anyway, the gate reads gzip and deflate, but not Brotli or
|
|
207
|
+
Zstandard: an agent then gets the page without an offer. People's requests
|
|
208
|
+
keep their `Accept-Encoding`, so they still get compressed pages.
|
|
209
|
+
- The gate reads a page's title and description in the charset its
|
|
210
|
+
`Content-Type` header names, such as `charset=iso-8859-1`, and as UTF-8 when
|
|
211
|
+
it names none. A page it passes through keeps its exact bytes.
|
|
212
|
+
|
|
213
|
+
## Paywalled content
|
|
214
|
+
|
|
215
|
+
Gate 0.6.0 and later can fetch a paywalled article with the release
|
|
216
|
+
instructions the network sends, so an agent gets the full text and the offer
|
|
217
|
+
fits it. The network gives the gate a page address on your site's own host
|
|
218
|
+
and, optionally, headers to send: `Cookie`, `Authorization`,
|
|
219
|
+
`Constile-Paywall-Key`, or a header starting with `X-`. The gate ignores an
|
|
220
|
+
address on another host and drops other headers. It strips `Set-Cookie` from
|
|
221
|
+
what it releases and never logs the headers. To set up a method, open your
|
|
222
|
+
site's page in the dashboard and choose a content API, a paywall rule, or a
|
|
223
|
+
Constile login. A paywalled page gets offers only after the method works and
|
|
224
|
+
the gate is 0.6.0 or later.
|
|
225
|
+
|
|
226
|
+
## Check the install
|
|
227
|
+
|
|
228
|
+
Open `https://your-site/.well-known/constile`. You see JSON that names your
|
|
229
|
+
site ID, `"gate_version": "constile-gate 0.6.0"`, and the platform, such as
|
|
230
|
+
`"django"`. The install check on your dashboard reads the same address.
|
|
231
|
+
|
|
232
|
+
## Support
|
|
233
|
+
|
|
234
|
+
Write to <hello@constile.app>, or see the [setup guides](https://constile.app/setup).
|
|
235
|
+
|
|
236
|
+
## License
|
|
237
|
+
|
|
238
|
+
MIT. See LICENSE.
|
|
@@ -0,0 +1,32 @@
|
|
|
1
|
+
[build-system]
|
|
2
|
+
requires = ["setuptools>=77"]
|
|
3
|
+
build-backend = "setuptools.build_meta"
|
|
4
|
+
|
|
5
|
+
[project]
|
|
6
|
+
name = "constile-gate"
|
|
7
|
+
version = "0.6.0"
|
|
8
|
+
description = "The Constile gate for Python sites: WSGI and ASGI middleware, with Django, Flask, and FastAPI wiring."
|
|
9
|
+
readme = "README.md"
|
|
10
|
+
license = "MIT"
|
|
11
|
+
license-files = ["LICENSE"]
|
|
12
|
+
authors = [{ name = "CCC2C Inc.", email = "hello@constile.app" }]
|
|
13
|
+
requires-python = ">=3.9"
|
|
14
|
+
dependencies = []
|
|
15
|
+
classifiers = [
|
|
16
|
+
"Programming Language :: Python :: 3",
|
|
17
|
+
"Programming Language :: Python :: 3 :: Only",
|
|
18
|
+
"Framework :: Django",
|
|
19
|
+
"Framework :: Flask",
|
|
20
|
+
"Framework :: FastAPI",
|
|
21
|
+
"Topic :: Internet :: WWW/HTTP :: WSGI :: Middleware",
|
|
22
|
+
]
|
|
23
|
+
|
|
24
|
+
[project.urls]
|
|
25
|
+
Homepage = "https://constile.app"
|
|
26
|
+
Documentation = "https://constile.app/setup/python"
|
|
27
|
+
|
|
28
|
+
[tool.setuptools.packages.find]
|
|
29
|
+
where = ["src"]
|
|
30
|
+
|
|
31
|
+
[tool.setuptools.package-data]
|
|
32
|
+
constile_gate = ["py.typed"]
|
|
@@ -0,0 +1,23 @@
|
|
|
1
|
+
"""
|
|
2
|
+
The Constile gate for Python sites: a port of the reference gate with
|
|
3
|
+
WSGI and ASGI middleware, and wiring for Django, Flask, and FastAPI.
|
|
4
|
+
"""
|
|
5
|
+
from .agents import classify_client, signature_agent_origin
|
|
6
|
+
from .core import GATE_VERSION, GateOptions, GateRequest, Headers, clear_gate_cache, handle_gate, ip_prefix
|
|
7
|
+
from .page_meta import extract_page_meta
|
|
8
|
+
|
|
9
|
+
__version__ = "0.6.0"
|
|
10
|
+
|
|
11
|
+
__all__ = [
|
|
12
|
+
"GATE_VERSION",
|
|
13
|
+
"GateOptions",
|
|
14
|
+
"GateRequest",
|
|
15
|
+
"Headers",
|
|
16
|
+
"__version__",
|
|
17
|
+
"classify_client",
|
|
18
|
+
"clear_gate_cache",
|
|
19
|
+
"extract_page_meta",
|
|
20
|
+
"handle_gate",
|
|
21
|
+
"ip_prefix",
|
|
22
|
+
"signature_agent_origin",
|
|
23
|
+
]
|