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.
Files changed (45) hide show
  1. package/LICENSE +21 -0
  2. package/README.md +702 -0
  3. package/dist/browser.d.ts +10 -0
  4. package/dist/browser.js +10544 -0
  5. package/dist/csrf-protection.d.ts +10 -0
  6. package/dist/diagnostics.d.ts +11 -0
  7. package/dist/index.d.ts +10 -0
  8. package/dist/index.js +10435 -0
  9. package/dist/node-loader.d.ts +3 -0
  10. package/dist/platform-browser.d.ts +2 -0
  11. package/dist/platform-node.d.ts +2 -0
  12. package/dist/platform.d.ts +48 -0
  13. package/dist/runtime/browser.d.ts +49 -0
  14. package/dist/runtime/pipeline.d.ts +49 -0
  15. package/dist/utils.d.ts +7 -0
  16. package/dist/vcl-accept.d.ts +8 -0
  17. package/dist/vcl-acl.d.ts +19 -0
  18. package/dist/vcl-address.d.ts +8 -0
  19. package/dist/vcl-binary.d.ts +5 -0
  20. package/dist/vcl-builtin-types.d.ts +10 -0
  21. package/dist/vcl-compiler.d.ts +513 -0
  22. package/dist/vcl-digest.d.ts +87 -0
  23. package/dist/vcl-esi.d.ts +32 -0
  24. package/dist/vcl-fetch.d.ts +6 -0
  25. package/dist/vcl-header.d.ts +18 -0
  26. package/dist/vcl-limits.d.ts +10 -0
  27. package/dist/vcl-math.d.ts +45 -0
  28. package/dist/vcl-misc.d.ts +29 -0
  29. package/dist/vcl-node.d.ts +2 -0
  30. package/dist/vcl-parser-impl.d.ts +126 -0
  31. package/dist/vcl-parser.d.ts +320 -0
  32. package/dist/vcl-querystring.d.ts +46 -0
  33. package/dist/vcl-ratelimit.d.ts +39 -0
  34. package/dist/vcl-security.d.ts +23 -0
  35. package/dist/vcl-std.d.ts +43 -0
  36. package/dist/vcl-strings.d.ts +47 -0
  37. package/dist/vcl-table.d.ts +27 -0
  38. package/dist/vcl-testing.d.ts +60 -0
  39. package/dist/vcl-time.d.ts +60 -0
  40. package/dist/vcl-utf8.d.ts +6 -0
  41. package/dist/vcl-uuid.d.ts +38 -0
  42. package/dist/vcl-value.d.ts +96 -0
  43. package/dist/vcl-waf.d.ts +14 -0
  44. package/dist/vcl.d.ts +7 -0
  45. 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";