fastly.js 0.9.0
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.
- package/LICENSE +21 -0
- package/README.md +702 -0
- package/dist/browser.d.ts +10 -0
- package/dist/browser.js +10544 -0
- package/dist/csrf-protection.d.ts +10 -0
- package/dist/diagnostics.d.ts +11 -0
- package/dist/index.d.ts +10 -0
- package/dist/index.js +10435 -0
- package/dist/node-loader.d.ts +3 -0
- package/dist/platform-browser.d.ts +2 -0
- package/dist/platform-node.d.ts +2 -0
- package/dist/platform.d.ts +48 -0
- package/dist/runtime/browser.d.ts +49 -0
- package/dist/runtime/pipeline.d.ts +49 -0
- package/dist/utils.d.ts +7 -0
- package/dist/vcl-accept.d.ts +8 -0
- package/dist/vcl-acl.d.ts +19 -0
- package/dist/vcl-address.d.ts +8 -0
- package/dist/vcl-binary.d.ts +5 -0
- package/dist/vcl-builtin-types.d.ts +10 -0
- package/dist/vcl-compiler.d.ts +513 -0
- package/dist/vcl-digest.d.ts +87 -0
- package/dist/vcl-esi.d.ts +32 -0
- package/dist/vcl-fetch.d.ts +6 -0
- package/dist/vcl-header.d.ts +18 -0
- package/dist/vcl-limits.d.ts +10 -0
- package/dist/vcl-math.d.ts +45 -0
- package/dist/vcl-misc.d.ts +29 -0
- package/dist/vcl-node.d.ts +2 -0
- package/dist/vcl-parser-impl.d.ts +126 -0
- package/dist/vcl-parser.d.ts +320 -0
- package/dist/vcl-querystring.d.ts +46 -0
- package/dist/vcl-ratelimit.d.ts +39 -0
- package/dist/vcl-security.d.ts +23 -0
- package/dist/vcl-std.d.ts +43 -0
- package/dist/vcl-strings.d.ts +47 -0
- package/dist/vcl-table.d.ts +27 -0
- package/dist/vcl-testing.d.ts +60 -0
- package/dist/vcl-time.d.ts +60 -0
- package/dist/vcl-utf8.d.ts +6 -0
- package/dist/vcl-uuid.d.ts +38 -0
- package/dist/vcl-value.d.ts +96 -0
- package/dist/vcl-waf.d.ts +14 -0
- package/dist/vcl.d.ts +7 -0
- package/package.json +90 -0
package/README.md
ADDED
|
@@ -0,0 +1,702 @@
|
|
|
1
|
+
# Fastly.JS
|
|
2
|
+
|
|
3
|
+
A reimplementation of the Fastly platform, in JavaScript.
|
|
4
|
+
|
|
5
|
+
## Project Overview
|
|
6
|
+
|
|
7
|
+
This project aims to provide a local development environment for testing and deploying Fastly VCL configurations without requiring the actual Fastly infrastructure. Fastly.JS allows you to run and test your VCL configurations locally, making it easier to develop, debug, and iterate on your Fastly configurations.
|
|
8
|
+
|
|
9
|
+
## Documentation
|
|
10
|
+
|
|
11
|
+
For comprehensive documentation, tutorials, and examples, please visit the [documentation](docs/README.md).
|
|
12
|
+
|
|
13
|
+
- [Getting Started Guide](docs/getting-started.md)
|
|
14
|
+
- [Tutorials](docs/README.md#tutorials)
|
|
15
|
+
- [Examples](docs/README.md#examples)
|
|
16
|
+
- [API Reference](docs/README.md#api-reference)
|
|
17
|
+
- [Troubleshooting](docs/troubleshooting.md)
|
|
18
|
+
|
|
19
|
+
## Features
|
|
20
|
+
|
|
21
|
+
- Complete VCL Implementation: Parse and execute Fastly VCL scripts with support for all standard subroutines
|
|
22
|
+
- HTTP Request Pipeline: Implements the full Fastly request flow (vcl_recv, vcl_hash, vcl_hit, vcl_miss, vcl_fetch, vcl_deliver, etc.)
|
|
23
|
+
- Standard Library: Comprehensive implementation of Fastly's VCL standard library functions
|
|
24
|
+
- Edge Computing: Execute logic at the edge, closer to users
|
|
25
|
+
- Caching: Advanced caching capabilities with fine-grained control
|
|
26
|
+
- Backend Configuration: Support for multiple backends, health checks, and load balancing
|
|
27
|
+
- Error Handling: Comprehensive error handling with custom error pages
|
|
28
|
+
- Edge Side Includes (ESI): Processing of ESI tags (include, remove, comment, choose/when/otherwise) in HTML responses; includes are resolved with simulated content locally
|
|
29
|
+
- Random Functions: Generate random values with deterministic seeded options
|
|
30
|
+
- UUID Functions: Generate and validate UUIDs (v3, v4, v5) with namespace support
|
|
31
|
+
- WAF Functions: Web Application Firewall with attack detection and rate limiting
|
|
32
|
+
- Director Management: Implement load balancing across multiple backends
|
|
33
|
+
- Goto Statements: Control flow with goto statements and labels
|
|
34
|
+
- Request Restart: Support for restarting requests with the restart statement
|
|
35
|
+
- Browser Playground: A self-contained VCL simulator that runs entirely in the browser, with request/response tracing, cache inspection, and shareable links
|
|
36
|
+
|
|
37
|
+
## Requirements
|
|
38
|
+
|
|
39
|
+
- [Bun](https://bun.sh) runtime (v1.0.0 or higher) for the proxy server and development
|
|
40
|
+
- Node.js 18+ when using the published library
|
|
41
|
+
|
|
42
|
+
## Installation
|
|
43
|
+
|
|
44
|
+
Fastly.JS is published on npm as [`fastly.js`](https://www.npmjs.com/package/fastly.js).
|
|
45
|
+
To use it as a library in your own project:
|
|
46
|
+
|
|
47
|
+
```bash
|
|
48
|
+
npm install fastly.js
|
|
49
|
+
# or
|
|
50
|
+
bun add fastly.js
|
|
51
|
+
```
|
|
52
|
+
|
|
53
|
+
To hack on Fastly.JS itself, clone this repository and install the dependencies:
|
|
54
|
+
|
|
55
|
+
```bash
|
|
56
|
+
bun install
|
|
57
|
+
```
|
|
58
|
+
|
|
59
|
+
## Using as a library
|
|
60
|
+
|
|
61
|
+
The package exposes the VCL engine and the request pipeline, and runs on Node.js 18+ as well as Bun.
|
|
62
|
+
Compile a VCL program with `loadVCLContent`, then drive it through `runPipeline` with your own backend fetcher:
|
|
63
|
+
|
|
64
|
+
```ts
|
|
65
|
+
import { createVCLContext, loadVCLContent, runPipeline } from "fastly.js";
|
|
66
|
+
|
|
67
|
+
const subroutines = loadVCLContent(`
|
|
68
|
+
sub vcl_deliver {
|
|
69
|
+
set resp.http.X-Hello = "world";
|
|
70
|
+
}
|
|
71
|
+
`);
|
|
72
|
+
|
|
73
|
+
const context = createVCLContext();
|
|
74
|
+
context.req.url = "/";
|
|
75
|
+
context.req.method = "GET";
|
|
76
|
+
const cache = new Map();
|
|
77
|
+
context.cache = cache;
|
|
78
|
+
|
|
79
|
+
const result = await runPipeline({
|
|
80
|
+
subroutines,
|
|
81
|
+
context,
|
|
82
|
+
cache,
|
|
83
|
+
maxRestarts: 3,
|
|
84
|
+
getBackendResponse: async () => ({
|
|
85
|
+
status: 200,
|
|
86
|
+
statusText: "OK",
|
|
87
|
+
headers: { "content-type": "text/plain" },
|
|
88
|
+
body: new TextEncoder().encode("hello"),
|
|
89
|
+
}),
|
|
90
|
+
});
|
|
91
|
+
|
|
92
|
+
console.log(result.response.headers["X-Hello"]); // "world"
|
|
93
|
+
```
|
|
94
|
+
|
|
95
|
+
Browsers get their own entry point, `fastly.js/browser`, which avoids Node built-ins entirely.
|
|
96
|
+
It also exports `runBrowserSimulation`, the same self-contained simulator that powers the web playground: give it a VCL program, a synthetic request, and a canned backend response, and it returns the final response along with diagnostics, a full execution trace, and the cache state.
|
|
97
|
+
|
|
98
|
+
## Usage
|
|
99
|
+
|
|
100
|
+
### Basic Usage
|
|
101
|
+
|
|
102
|
+
Start the proxy server with one or more VCL configuration files:
|
|
103
|
+
|
|
104
|
+
```bash
|
|
105
|
+
bun run index.ts [path-to-vcl-file-1] [path-to-vcl-file-2] ...
|
|
106
|
+
```
|
|
107
|
+
|
|
108
|
+
If no VCL files are specified, it will use the default `filter.vcl` in the project root.
|
|
109
|
+
|
|
110
|
+
When multiple VCL files are provided, they are concatenated in the order they are specified, and the result is treated as a single VCL file. This allows you to split your VCL configuration into multiple files for better organization.
|
|
111
|
+
|
|
112
|
+
Then, open your browser and navigate to:
|
|
113
|
+
|
|
114
|
+
```text
|
|
115
|
+
http://127.0.0.1:8000
|
|
116
|
+
```
|
|
117
|
+
|
|
118
|
+
All requests will be processed according to your VCL configuration.
|
|
119
|
+
|
|
120
|
+
### Examples
|
|
121
|
+
|
|
122
|
+
#### Example 1: Basic Caching
|
|
123
|
+
|
|
124
|
+
Create a file named `basic-cache.vcl` with the following content:
|
|
125
|
+
|
|
126
|
+
```vcl
|
|
127
|
+
sub vcl_recv {
|
|
128
|
+
# Pass dynamic content directly to the backend
|
|
129
|
+
if (req.url ~ "^/api/" || req.url ~ "\?") {
|
|
130
|
+
return(pass);
|
|
131
|
+
}
|
|
132
|
+
|
|
133
|
+
# Continue to cache lookup for static content
|
|
134
|
+
return(lookup);
|
|
135
|
+
}
|
|
136
|
+
|
|
137
|
+
sub vcl_fetch {
|
|
138
|
+
# Cache static assets for 1 hour
|
|
139
|
+
if (req.url ~ "\.(jpg|jpeg|png|gif|ico|css|js)$") {
|
|
140
|
+
set beresp.ttl = 1h;
|
|
141
|
+
} else {
|
|
142
|
+
# Cache other content for 5 minutes
|
|
143
|
+
set beresp.ttl = 5m;
|
|
144
|
+
}
|
|
145
|
+
return(deliver);
|
|
146
|
+
}
|
|
147
|
+
```
|
|
148
|
+
|
|
149
|
+
Run the proxy with this configuration:
|
|
150
|
+
|
|
151
|
+
```bash
|
|
152
|
+
bun run index.ts basic-cache.vcl
|
|
153
|
+
```
|
|
154
|
+
|
|
155
|
+
#### Example 2: A/B Testing
|
|
156
|
+
|
|
157
|
+
Create a file named `ab-test.vcl` with the following content:
|
|
158
|
+
|
|
159
|
+
```vcl
|
|
160
|
+
sub vcl_recv {
|
|
161
|
+
# Randomly assign users to A or B variant (50/50 split)
|
|
162
|
+
if (!req.http.X-ABTest) {
|
|
163
|
+
if (std.random.randombool(0.5)) {
|
|
164
|
+
set req.http.X-ABTest = "A";
|
|
165
|
+
} else {
|
|
166
|
+
set req.http.X-ABTest = "B";
|
|
167
|
+
}
|
|
168
|
+
}
|
|
169
|
+
|
|
170
|
+
return(lookup);
|
|
171
|
+
}
|
|
172
|
+
|
|
173
|
+
sub vcl_hash {
|
|
174
|
+
# Add the variant to the cache key so each variant is cached separately
|
|
175
|
+
hash_data(req.url);
|
|
176
|
+
hash_data(req.http.host);
|
|
177
|
+
hash_data(req.http.X-ABTest);
|
|
178
|
+
return(hash);
|
|
179
|
+
}
|
|
180
|
+
|
|
181
|
+
sub vcl_deliver {
|
|
182
|
+
# Add the variant to the response headers
|
|
183
|
+
set resp.http.X-ABTest = req.http.X-ABTest;
|
|
184
|
+
|
|
185
|
+
return(deliver);
|
|
186
|
+
}
|
|
187
|
+
```
|
|
188
|
+
|
|
189
|
+
Run the proxy with this configuration:
|
|
190
|
+
|
|
191
|
+
```bash
|
|
192
|
+
bun run index.ts ab-test.vcl
|
|
193
|
+
```
|
|
194
|
+
|
|
195
|
+
#### Example 3: Error Handling
|
|
196
|
+
|
|
197
|
+
Create a file named `error-handling.vcl` with the following content:
|
|
198
|
+
|
|
199
|
+
```vcl
|
|
200
|
+
sub vcl_recv {
|
|
201
|
+
# Block access to admin area from non-internal IPs
|
|
202
|
+
if (req.url ~ "^/admin/" && client.ip !~ "^(127\.0\.0\.1|192\.168\.)") {
|
|
203
|
+
error 403 "Forbidden";
|
|
204
|
+
}
|
|
205
|
+
|
|
206
|
+
return(lookup);
|
|
207
|
+
}
|
|
208
|
+
|
|
209
|
+
sub vcl_error {
|
|
210
|
+
# Custom error page
|
|
211
|
+
if (obj.status == 403) {
|
|
212
|
+
set obj.http.Content-Type = "text/html; charset=utf-8";
|
|
213
|
+
synthetic {"
|
|
214
|
+
<!DOCTYPE html>
|
|
215
|
+
<html>
|
|
216
|
+
<head>
|
|
217
|
+
<title>Access Denied</title>
|
|
218
|
+
</head>
|
|
219
|
+
<body>
|
|
220
|
+
<h1>Access Denied</h1>
|
|
221
|
+
<p>You do not have permission to access this area.</p>
|
|
222
|
+
</body>
|
|
223
|
+
</html>
|
|
224
|
+
"};
|
|
225
|
+
return(deliver);
|
|
226
|
+
}
|
|
227
|
+
|
|
228
|
+
return(deliver);
|
|
229
|
+
}
|
|
230
|
+
```
|
|
231
|
+
|
|
232
|
+
Run the proxy with this configuration:
|
|
233
|
+
|
|
234
|
+
```bash
|
|
235
|
+
bun run index.ts error-handling.vcl
|
|
236
|
+
```
|
|
237
|
+
|
|
238
|
+
#### Example 4: WAF and Rate Limiting
|
|
239
|
+
|
|
240
|
+
Create a file named `waf-protection.vcl` with the following content:
|
|
241
|
+
|
|
242
|
+
```vcl
|
|
243
|
+
sub vcl_recv {
|
|
244
|
+
# Block SQL injection attempts
|
|
245
|
+
if (waf.detect_attack(req.url, "sql")) {
|
|
246
|
+
waf.log("SQL injection attempt detected in URL: " + req.url);
|
|
247
|
+
error 403 "Forbidden";
|
|
248
|
+
}
|
|
249
|
+
|
|
250
|
+
# Block XSS attempts (incoming header names are stored lowercase,
|
|
251
|
+
# and header lookups are case-sensitive)
|
|
252
|
+
if (waf.detect_attack(req.http.user-agent, "xss")) {
|
|
253
|
+
waf.log("XSS attempt detected in User-Agent: " + req.http.user-agent);
|
|
254
|
+
error 403 "Forbidden";
|
|
255
|
+
}
|
|
256
|
+
|
|
257
|
+
# Rate limit by client IP (no more than 100 requests per 60 seconds)
|
|
258
|
+
if (!waf.rate_limit(client.ip, 100, 60)) {
|
|
259
|
+
waf.log("Rate limit exceeded for IP: " + client.ip);
|
|
260
|
+
error 429 "Too Many Requests";
|
|
261
|
+
}
|
|
262
|
+
|
|
263
|
+
return(lookup);
|
|
264
|
+
}
|
|
265
|
+
|
|
266
|
+
sub vcl_error {
|
|
267
|
+
# Custom error page for rate limiting
|
|
268
|
+
if (obj.status == 429) {
|
|
269
|
+
set obj.http.Content-Type = "text/html; charset=utf-8";
|
|
270
|
+
set obj.http.Retry-After = "5";
|
|
271
|
+
synthetic {"
|
|
272
|
+
<!DOCTYPE html>
|
|
273
|
+
<html>
|
|
274
|
+
<head>
|
|
275
|
+
<title>Rate Limit Exceeded</title>
|
|
276
|
+
</head>
|
|
277
|
+
<body>
|
|
278
|
+
<h1>Rate Limit Exceeded</h1>
|
|
279
|
+
<p>You have made too many requests. Please try again in 5 seconds.</p>
|
|
280
|
+
</body>
|
|
281
|
+
</html>
|
|
282
|
+
"};
|
|
283
|
+
return(deliver);
|
|
284
|
+
}
|
|
285
|
+
|
|
286
|
+
return(deliver);
|
|
287
|
+
}
|
|
288
|
+
```
|
|
289
|
+
|
|
290
|
+
Run the proxy with this configuration:
|
|
291
|
+
|
|
292
|
+
```bash
|
|
293
|
+
bun run index.ts waf-protection.vcl
|
|
294
|
+
```
|
|
295
|
+
|
|
296
|
+
#### Example 5: Rate Limiting
|
|
297
|
+
|
|
298
|
+
Create a file named `rate-limiting.vcl` with the following content:
|
|
299
|
+
|
|
300
|
+
```vcl
|
|
301
|
+
# Declare the rate counter and penalty box this VCL uses
|
|
302
|
+
ratecounter requests {}
|
|
303
|
+
penaltybox rate_violators {}
|
|
304
|
+
|
|
305
|
+
sub vcl_recv {
|
|
306
|
+
# Count this request against the client's rate. check_rate increments the
|
|
307
|
+
# "requests" counter by 1 over a 60-second window, and if the client crosses
|
|
308
|
+
# 100 requests in that window it drops them into the "rate_violators" penalty
|
|
309
|
+
# box for 300 seconds. It returns true the moment the threshold is exceeded.
|
|
310
|
+
if (ratelimit.check_rate(client.ip, requests, 100, 60, 1, rate_violators, 300s)) {
|
|
311
|
+
error 429 "Too Many Requests";
|
|
312
|
+
}
|
|
313
|
+
|
|
314
|
+
# Reject anyone already serving time in the penalty box
|
|
315
|
+
if (ratelimit.penaltybox_has(rate_violators, client.ip)) {
|
|
316
|
+
error 429 "Too Many Requests";
|
|
317
|
+
}
|
|
318
|
+
|
|
319
|
+
return(lookup);
|
|
320
|
+
}
|
|
321
|
+
|
|
322
|
+
sub vcl_error {
|
|
323
|
+
# Custom error page for rate limiting
|
|
324
|
+
if (obj.status == 429) {
|
|
325
|
+
set obj.http.Content-Type = "text/html; charset=utf-8";
|
|
326
|
+
set obj.http.Retry-After = "60";
|
|
327
|
+
synthetic {"
|
|
328
|
+
<!DOCTYPE html>
|
|
329
|
+
<html>
|
|
330
|
+
<head>
|
|
331
|
+
<title>Rate Limit Exceeded</title>
|
|
332
|
+
</head>
|
|
333
|
+
<body>
|
|
334
|
+
<h1>Rate Limit Exceeded</h1>
|
|
335
|
+
<p>You have made too many requests. Please try again in 60 seconds.</p>
|
|
336
|
+
</body>
|
|
337
|
+
</html>
|
|
338
|
+
"};
|
|
339
|
+
return(deliver);
|
|
340
|
+
}
|
|
341
|
+
|
|
342
|
+
return(deliver);
|
|
343
|
+
}
|
|
344
|
+
```
|
|
345
|
+
|
|
346
|
+
Run the proxy with this configuration:
|
|
347
|
+
|
|
348
|
+
```bash
|
|
349
|
+
bun run index.ts rate-limiting.vcl
|
|
350
|
+
```
|
|
351
|
+
|
|
352
|
+
#### Example 6: Flow Control with Goto
|
|
353
|
+
|
|
354
|
+
Create a file named `goto-flow.vcl` with the following content:
|
|
355
|
+
|
|
356
|
+
```vcl
|
|
357
|
+
sub vcl_recv {
|
|
358
|
+
if (req.http.cookie ~ "logged_in=true") {
|
|
359
|
+
# Jump to logged-in user processing
|
|
360
|
+
goto logged_in_user;
|
|
361
|
+
} else {
|
|
362
|
+
# Jump to anonymous user processing
|
|
363
|
+
goto anonymous_user;
|
|
364
|
+
}
|
|
365
|
+
|
|
366
|
+
# Logged-in user processing
|
|
367
|
+
logged_in_user:
|
|
368
|
+
set req.http.X-User-Type = "logged_in";
|
|
369
|
+
|
|
370
|
+
if (req.http.cookie ~ "user_role=admin") {
|
|
371
|
+
# Jump to admin user processing
|
|
372
|
+
goto admin_user;
|
|
373
|
+
} else {
|
|
374
|
+
# Jump to regular user processing
|
|
375
|
+
goto regular_user;
|
|
376
|
+
}
|
|
377
|
+
|
|
378
|
+
# Anonymous user processing
|
|
379
|
+
anonymous_user:
|
|
380
|
+
set req.http.X-User-Type = "anonymous";
|
|
381
|
+
goto user_end;
|
|
382
|
+
|
|
383
|
+
# Admin user processing
|
|
384
|
+
admin_user:
|
|
385
|
+
set req.http.X-User-Role = "admin";
|
|
386
|
+
goto user_end;
|
|
387
|
+
|
|
388
|
+
# Regular user processing
|
|
389
|
+
regular_user:
|
|
390
|
+
set req.http.X-User-Role = "regular";
|
|
391
|
+
|
|
392
|
+
# End of user processing
|
|
393
|
+
user_end:
|
|
394
|
+
set req.http.X-User-Processing-Complete = "true";
|
|
395
|
+
|
|
396
|
+
return(lookup);
|
|
397
|
+
}
|
|
398
|
+
|
|
399
|
+
sub vcl_deliver {
|
|
400
|
+
# Add user information to response headers
|
|
401
|
+
if (req.http.X-User-Type) {
|
|
402
|
+
set resp.http.X-User-Type = req.http.X-User-Type;
|
|
403
|
+
}
|
|
404
|
+
|
|
405
|
+
if (req.http.X-User-Role) {
|
|
406
|
+
set resp.http.X-User-Role = req.http.X-User-Role;
|
|
407
|
+
}
|
|
408
|
+
|
|
409
|
+
return(deliver);
|
|
410
|
+
}
|
|
411
|
+
```
|
|
412
|
+
|
|
413
|
+
Run the proxy with this configuration:
|
|
414
|
+
|
|
415
|
+
```bash
|
|
416
|
+
bun run index.ts goto-flow.vcl
|
|
417
|
+
```
|
|
418
|
+
|
|
419
|
+
#### Example 7: Request Restart
|
|
420
|
+
|
|
421
|
+
Create a file named `restart-example.vcl` with the following content:
|
|
422
|
+
|
|
423
|
+
```vcl
|
|
424
|
+
sub vcl_recv {
|
|
425
|
+
# Track restarts
|
|
426
|
+
set req.http.X-Restart-Count = req.restarts;
|
|
427
|
+
|
|
428
|
+
# First pass
|
|
429
|
+
if (req.restarts == 0) {
|
|
430
|
+
# First pass: Add a custom header
|
|
431
|
+
set req.http.X-Custom-Header = "First Pass";
|
|
432
|
+
set req.http.X-Restart-Reason = "first_pass";
|
|
433
|
+
restart;
|
|
434
|
+
}
|
|
435
|
+
|
|
436
|
+
# Second pass
|
|
437
|
+
if (req.restarts == 1) {
|
|
438
|
+
# Second pass: Modify the custom header
|
|
439
|
+
set req.http.X-Custom-Header = req.http.X-Custom-Header + ", Second Pass";
|
|
440
|
+
set req.http.X-Restart-Reason = "second_pass";
|
|
441
|
+
restart;
|
|
442
|
+
}
|
|
443
|
+
|
|
444
|
+
# Third pass
|
|
445
|
+
if (req.restarts == 2) {
|
|
446
|
+
# Third pass: Finalize the custom header
|
|
447
|
+
set req.http.X-Custom-Header = req.http.X-Custom-Header + ", Final Pass";
|
|
448
|
+
set req.http.X-Restart-Reason = "final_pass";
|
|
449
|
+
}
|
|
450
|
+
|
|
451
|
+
# Defensive cap inside VCL. The proxy itself enforces MAX_RESTARTS = 3
|
|
452
|
+
# in index.ts and will return its own 503 if that limit is reached, so
|
|
453
|
+
# this branch is mostly there to demonstrate the pattern.
|
|
454
|
+
if (req.restarts >= 3) {
|
|
455
|
+
set req.http.X-Max-Restarts-Reached = "true";
|
|
456
|
+
error 503 "Maximum number of restarts reached";
|
|
457
|
+
}
|
|
458
|
+
|
|
459
|
+
return(lookup);
|
|
460
|
+
}
|
|
461
|
+
|
|
462
|
+
sub vcl_deliver {
|
|
463
|
+
# Add headers to show restart information
|
|
464
|
+
set resp.http.X-Restart-Count = req.restarts;
|
|
465
|
+
set resp.http.X-Custom-Header = req.http.X-Custom-Header;
|
|
466
|
+
|
|
467
|
+
if (req.http.X-Restart-Reason) {
|
|
468
|
+
set resp.http.X-Restart-Reason = req.http.X-Restart-Reason;
|
|
469
|
+
}
|
|
470
|
+
|
|
471
|
+
return(deliver);
|
|
472
|
+
}
|
|
473
|
+
```
|
|
474
|
+
|
|
475
|
+
Run the proxy with this configuration:
|
|
476
|
+
|
|
477
|
+
```bash
|
|
478
|
+
bun run index.ts restart-example.vcl
|
|
479
|
+
```
|
|
480
|
+
|
|
481
|
+
#### Example 8: URL Normalization with Restart
|
|
482
|
+
|
|
483
|
+
Create a file named `url-normalization.vcl` with the following content:
|
|
484
|
+
|
|
485
|
+
```vcl
|
|
486
|
+
sub vcl_recv {
|
|
487
|
+
# Track restarts
|
|
488
|
+
set req.http.X-Restart-Count = req.restarts;
|
|
489
|
+
|
|
490
|
+
# First time through, save the original URL
|
|
491
|
+
if (req.restarts == 0) {
|
|
492
|
+
# Initialize headers
|
|
493
|
+
set req.http.X-Original-URL = req.url;
|
|
494
|
+
set req.http.X-Current-URL = req.url;
|
|
495
|
+
|
|
496
|
+
# First pass: Handle double slashes
|
|
497
|
+
if (req.http.X-Current-URL ~ "//") {
|
|
498
|
+
set req.http.X-Current-URL = regsub(req.http.X-Current-URL, "//", "/");
|
|
499
|
+
# Important: Update the actual URL with the normalized version
|
|
500
|
+
set req.url = req.http.X-Current-URL;
|
|
501
|
+
set req.http.X-Restart-Reason = "double_slash_removal";
|
|
502
|
+
restart;
|
|
503
|
+
}
|
|
504
|
+
}
|
|
505
|
+
# Second pass: Add trailing slash if needed
|
|
506
|
+
else if (req.restarts == 1) {
|
|
507
|
+
# Only add trailing slash if not a file (no extension)
|
|
508
|
+
if (!req.http.X-Current-URL ~ "\\.") {
|
|
509
|
+
# Only add trailing slash if not already present
|
|
510
|
+
if (!req.http.X-Current-URL ~ "/$") {
|
|
511
|
+
set req.http.X-Current-URL = req.http.X-Current-URL + "/";
|
|
512
|
+
# Important: Update the actual URL with the normalized version
|
|
513
|
+
set req.url = req.http.X-Current-URL;
|
|
514
|
+
set req.http.X-Restart-Reason = "add_trailing_slash";
|
|
515
|
+
restart;
|
|
516
|
+
}
|
|
517
|
+
}
|
|
518
|
+
}
|
|
519
|
+
# Third pass: Add index.html if URL ends with slash
|
|
520
|
+
else if (req.restarts == 2) {
|
|
521
|
+
if (req.http.X-Current-URL ~ "/$") {
|
|
522
|
+
set req.http.X-Current-URL = req.http.X-Current-URL + "index.html";
|
|
523
|
+
# Important: Update the actual URL with the normalized version
|
|
524
|
+
set req.url = req.http.X-Current-URL;
|
|
525
|
+
set req.http.X-Restart-Reason = "add_index_html";
|
|
526
|
+
# No restart here, continue processing
|
|
527
|
+
}
|
|
528
|
+
}
|
|
529
|
+
|
|
530
|
+
# The proxy enforces MAX_RESTARTS = 3, so this is just defensive.
|
|
531
|
+
if (req.restarts >= 3) {
|
|
532
|
+
set req.http.X-Max-Restarts-Reached = "true";
|
|
533
|
+
error 503 "Maximum number of restarts reached";
|
|
534
|
+
}
|
|
535
|
+
|
|
536
|
+
return(lookup);
|
|
537
|
+
}
|
|
538
|
+
|
|
539
|
+
sub vcl_deliver {
|
|
540
|
+
# Add headers to show URL normalization information
|
|
541
|
+
set resp.http.X-Restart-Count = req.restarts;
|
|
542
|
+
set resp.http.X-Original-URL = req.http.X-Original-URL;
|
|
543
|
+
set resp.http.X-Current-URL = req.http.X-Current-URL;
|
|
544
|
+
|
|
545
|
+
if (req.http.X-Restart-Reason) {
|
|
546
|
+
set resp.http.X-Restart-Reason = req.http.X-Restart-Reason;
|
|
547
|
+
}
|
|
548
|
+
|
|
549
|
+
return(deliver);
|
|
550
|
+
}
|
|
551
|
+
```
|
|
552
|
+
|
|
553
|
+
Run the proxy with this configuration:
|
|
554
|
+
|
|
555
|
+
```bash
|
|
556
|
+
bun run index.ts url-normalization.vcl
|
|
557
|
+
```
|
|
558
|
+
|
|
559
|
+
### Using with Custom Backends
|
|
560
|
+
|
|
561
|
+
You can configure multiple backends in your VCL file:
|
|
562
|
+
|
|
563
|
+
```vcl
|
|
564
|
+
backend api {
|
|
565
|
+
.host = "api.example.com";
|
|
566
|
+
.port = "443";
|
|
567
|
+
.ssl = true;
|
|
568
|
+
}
|
|
569
|
+
|
|
570
|
+
backend static {
|
|
571
|
+
.host = "static.example.com";
|
|
572
|
+
.port = "443";
|
|
573
|
+
.ssl = true;
|
|
574
|
+
}
|
|
575
|
+
|
|
576
|
+
sub vcl_recv {
|
|
577
|
+
# Route requests to appropriate backends
|
|
578
|
+
if (req.url ~ "^/api/") {
|
|
579
|
+
set req.backend = api;
|
|
580
|
+
} else if (req.url ~ "^/static/") {
|
|
581
|
+
set req.backend = static;
|
|
582
|
+
}
|
|
583
|
+
|
|
584
|
+
return(lookup);
|
|
585
|
+
}
|
|
586
|
+
```
|
|
587
|
+
|
|
588
|
+
This configuration will route requests to different backends based on the URL path.
|
|
589
|
+
|
|
590
|
+
### Web Playground
|
|
591
|
+
|
|
592
|
+
Fastly.JS also ships as a browser playground: a VCL simulator that runs the exact
|
|
593
|
+
same request pipeline as the CLI, entirely client-side. There is no proxying or
|
|
594
|
+
network access — you supply the VCL, the request, and a synthetic backend
|
|
595
|
+
response, and the simulator shows you what the engine does with them.
|
|
596
|
+
|
|
597
|
+
Build the playground and serve it locally:
|
|
598
|
+
|
|
599
|
+
```bash
|
|
600
|
+
bun run web
|
|
601
|
+
```
|
|
602
|
+
|
|
603
|
+
This builds `web/main.ts` for the browser and starts a static server (open the
|
|
604
|
+
URL it prints). From there you can:
|
|
605
|
+
|
|
606
|
+
- Edit VCL, the request, and the backend response, then run the pipeline and see
|
|
607
|
+
the resulting response, the cache decision, a statement-level execution trace,
|
|
608
|
+
any `log` output, and structured parse diagnostics.
|
|
609
|
+
- Inspect the in-memory cache and watch a request go from MISS to HIT across runs.
|
|
610
|
+
- Share a session: the VCL, request, and backend response are encoded into the
|
|
611
|
+
URL hash, so copying the link reproduces the exact run.
|
|
612
|
+
|
|
613
|
+
To produce a standalone, minified copy you can drop on any static host:
|
|
614
|
+
|
|
615
|
+
```bash
|
|
616
|
+
bun run web:dist
|
|
617
|
+
```
|
|
618
|
+
|
|
619
|
+
The result lands in `web/site/`. Because the simulator has no host crypto, RSA
|
|
620
|
+
and JWT signature verification are deliberately unsupported in the browser and
|
|
621
|
+
surface a loud "unsupported feature" error rather than a silent failure.
|
|
622
|
+
|
|
623
|
+
## Testing
|
|
624
|
+
|
|
625
|
+
Run the main test suite to verify VCL functionality:
|
|
626
|
+
|
|
627
|
+
```bash
|
|
628
|
+
bun run test
|
|
629
|
+
```
|
|
630
|
+
|
|
631
|
+
This executes the standard suite, covering basic VCL syntax, standard library
|
|
632
|
+
functions, caching behavior, backend error handling, random/accept/address/binary
|
|
633
|
+
/digest/query-string/UUID/WAF/rate-limiting/ESI functions, goto statements,
|
|
634
|
+
request restarts, and real-world VCL configurations.
|
|
635
|
+
|
|
636
|
+
To run everything, including the root, integration, table, crypto-compatibility,
|
|
637
|
+
limits, browser-simulation, and browser-bundle suites:
|
|
638
|
+
|
|
639
|
+
```bash
|
|
640
|
+
bun run test:all
|
|
641
|
+
```
|
|
642
|
+
|
|
643
|
+
Individual suites are available as `test:basic`, `test:stdlib`, `test:caching`,
|
|
644
|
+
`test:backend`, `test:root`, `test:integration`, `test:tables`, `test:compat`,
|
|
645
|
+
`test:limits`, `test:sim`, and `test:browser` (see `package.json` for the full list).
|
|
646
|
+
|
|
647
|
+
## Project Structure
|
|
648
|
+
|
|
649
|
+
- `index.ts`: CLI entry point — the Bun proxy server that loads VCL, configures the example backends, and drives the request pipeline against a real backend
|
|
650
|
+
- `src/`: Core implementation files
|
|
651
|
+
- `vcl.ts`: Main VCL interface for loading and executing VCL files; also exports `createVCLContext` and the runtime types (`VCLContext`, `VCLSubroutines`)
|
|
652
|
+
- `node-loader.ts`: Node-only `loadVCL` helper that reads VCL from the filesystem (kept out of the engine graph so the browser build stays free of `node:fs`)
|
|
653
|
+
- `vcl-parser.ts`: VCL lexer, AST node definitions, and the high-level `parseVCL` entry point
|
|
654
|
+
- `vcl-parser-impl.ts`: Recursive-descent parser implementation
|
|
655
|
+
- `vcl-compiler.ts`: Compiles a parsed VCL program into executable JavaScript functions; defines the runtime context and standard library shape
|
|
656
|
+
- `runtime/pipeline.ts`: The host-agnostic request lifecycle (`runPipeline`) shared by the CLI and the browser simulator — recv/restart loop, hash, hit/miss/pass, fetch, deliver, cache store, and error handling
|
|
657
|
+
- `runtime/browser.ts`: `runBrowserSimulation`, the headless simulator the playground is built on
|
|
658
|
+
- `platform.ts`, `platform-node.ts`, `platform-browser.ts`: The `VCLPlatform`/`CryptoProvider` host interface and its Node and browser implementations (crypto, clock, randomness, hostname, env, logging)
|
|
659
|
+
- `vcl-*.ts`: Individual standard library modules (digest, strings, time, querystring, address, accept, ratelimit, waf, etc.)
|
|
660
|
+
- `web/`: The browser playground — a static single-page VCL simulator (`main.ts`, `index.html`, `serve.ts`, `dist.ts`)
|
|
661
|
+
- `test/`: Test suites and framework
|
|
662
|
+
- `fastly-vcl/`: Documentation and specifications for Fastly VCL
|
|
663
|
+
- `vcl-functions/`: Detailed documentation for all VCL functions
|
|
664
|
+
|
|
665
|
+
## Configuration
|
|
666
|
+
|
|
667
|
+
The proxy currently uses a few hardcoded constants at the top of `index.ts`:
|
|
668
|
+
|
|
669
|
+
- `PROXY_HOST`: The host to listen on (default: `"127.0.0.1"`)
|
|
670
|
+
- `PROXY_PORT`: The port to listen on (default: `8000`)
|
|
671
|
+
- `DEFAULT_VCL_FILE`: The VCL file used when none is specified on the command line (default: `"filter.vcl"`)
|
|
672
|
+
- `MAX_RESTARTS`: The maximum number of times a request may be restarted before the proxy gives up with a 503 (default: `3`)
|
|
673
|
+
|
|
674
|
+
The list of VCL files to load is taken from the command-line arguments rather than a single constant — pass one or more paths after `bun run index.ts` and they are concatenated in order.
|
|
675
|
+
|
|
676
|
+
The development server in `index.ts` also pre-registers three example backends (`main` → `perdu.com:443` over TLS, `api` → `httpbin.org:80`, `static` → `example.com:80`) and two directors (`main_director`, `fallback_director`). These exist purely so the bundled `filter.vcl` and the example VCL snippets in this README have something to talk to; you will normally want to replace them with your own `backend` declarations in VCL.
|
|
677
|
+
|
|
678
|
+
## Development Status
|
|
679
|
+
|
|
680
|
+
The project implements all core VCL functionality for local development and testing. All tests are passing, and the implementation supports:
|
|
681
|
+
|
|
682
|
+
1. Complete VCL Syntax: All standard VCL statements and expressions, including control flow with if/else and goto/labels
|
|
683
|
+
2. Full Standard Library: Comprehensive implementation of all VCL standard library functions
|
|
684
|
+
3. Advanced Features: Caching, multiple backends, error handling, ESI, directors, security features, and more
|
|
685
|
+
|
|
686
|
+
## Contributing
|
|
687
|
+
|
|
688
|
+
Contributions are welcome! Please feel free to submit a Pull Request.
|
|
689
|
+
|
|
690
|
+
1. Fork the repository
|
|
691
|
+
2. Create your feature branch (`git checkout -b feature/amazing-feature`)
|
|
692
|
+
3. Commit your changes (`git commit -m 'Add some amazing feature'`)
|
|
693
|
+
4. Push to the branch (`git push origin feature/amazing-feature`)
|
|
694
|
+
5. Open a Pull Request
|
|
695
|
+
|
|
696
|
+
## Disclaimer
|
|
697
|
+
|
|
698
|
+
This is an independent, community project and is not affiliated with, endorsed by, or sponsored by Fastly, Inc. It was built based on publicly available Fastly documentation.
|
|
699
|
+
|
|
700
|
+
## License
|
|
701
|
+
|
|
702
|
+
This project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.
|
|
@@ -0,0 +1,10 @@
|
|
|
1
|
+
import "./platform-browser.js";
|
|
2
|
+
export type { VCLDiagnostic } from "./diagnostics.js";
|
|
3
|
+
export { VCLDiagnosticError } from "./diagnostics.js";
|
|
4
|
+
export type { TraceEvent, VCLPlatform } from "./platform.js";
|
|
5
|
+
export { UnsupportedFeatureError } from "./platform.js";
|
|
6
|
+
export type { SimBackendResponse, SimErrorKind, SimPlatformOptions, SimRequest, SimResponse, SimulationOptions, SimulationResult, } from "./runtime/browser.js";
|
|
7
|
+
export { runBrowserSimulation } from "./runtime/browser.js";
|
|
8
|
+
export type { BackendResponse, CacheDecision, CacheEntry, CacheOutcome } from "./runtime/pipeline.js";
|
|
9
|
+
export { createVCLContext, executeVCL, executeVCLByName, loadVCLContent } from "./vcl.js";
|
|
10
|
+
export type { VCLContext, VCLSubroutines } from "./vcl-compiler.js";
|