Add comprehensive web server documentation (Issue #213) - #220
Conversation
This addresses issue #213 by providing complete documentation for WFL's web server capabilities, including examples showing how to read files and serve their contents as HTTP responses. Documentation added: - Web Server Quick Start Guide - 5-minute tutorial with file serving examples - Web Server Cookbook - Common patterns and recipes for web development - Examples directory with 4 progressively complex web server examples - Updated main documentation to highlight web server capabilities The documentation directly answers the user's request for syntax examples showing how to create web servers that read files and display their contents as HTTP responses. 🤖 Generated with Claude Code Co-Authored-By: Claude <noreply@anthropic.com>
|
You have reached your Codex usage limits for code reviews. You can see your limits in the Codex usage dashboard. |
📝 WalkthroughWalkthroughAdds comprehensive web server documentation and examples for WFL, including four progressive example implementations (basic to advanced server patterns), three guide documents (quickstart, cookbook, by-example), and updates to existing reference documentation reflecting the implemented web server functionality. Changes
Estimated code review effort🎯 3 (Moderate) | ⏱️ ~25 minutes Possibly related PRs
Poem
Pre-merge checks✅ Passed checks (3 passed)
Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out. Comment |
|
Claude finished @logbie's task —— View job Pull Request Review: Web Server DocumentationI've conducted a comprehensive review of this PR. This is an excellent addition to the WFL documentation that significantly enhances the project's usability and appeal. Review Checklist:
✅ StrengthsDocumentation Quality
Technical Accuracy
Security Awareness
Project Integration
🔍 Minor ObservationsFile Organization (
|
There was a problem hiding this comment.
Pull request overview
This PR adds comprehensive documentation for WFL's web server capabilities, focusing on file serving and HTTP response functionality as requested in issue #213. The documentation includes tutorials, cookbooks, and progressively complex examples that demonstrate how to read files from disk and serve them as HTTP responses.
Key changes:
- New Quick Start guide and Cookbook for web server development with practical file serving examples
- Four new example files demonstrating web server concepts from basic to advanced
- Updated existing documentation to highlight web server features and cross-link resources
Reviewed changes
Copilot reviewed 12 out of 12 changed files in this pull request and generated 6 comments.
Show a summary per file
| File | Description |
|---|---|
| README.md | Added web server features to main feature list and included file serving example |
| Docs/wfldocs/WFL-io.md | Updated I/O documentation to mark web servers as implemented and added file serving example |
| Docs/wfl-documentation-index.md | Updated documentation index to reflect web server implementation status |
| Docs/guides/wfl-web-server-quickstart.md | New 5-minute tutorial showing file reading and serving with HTTP responses |
| Docs/guides/wfl-web-server-cookbook.md | New cookbook with reusable patterns for web server development |
| Docs/guides/wfl-getting-started.md | Added web server example to getting started guide |
| Docs/guides/wfl-by-example.md | Added comprehensive web server section with file serving examples |
| Docs/examples/web-servers/README.md | New README organizing web server examples by complexity |
| Docs/examples/web-servers/04-advanced-comprehensive.wfl | Advanced example with JSON APIs and dynamic content |
| Docs/examples/web-servers/03-multi-route-server.wfl | Intermediate example with multiple routes and file types |
| Docs/examples/web-servers/02-file-server-basic.wfl | Basic file serving example addressing issue #213 directly |
| Docs/examples/web-servers/01-basic-hello-server.wfl | Simplest web server example for beginners |
💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.
| try: | ||
| open file at "index.html" for reading as html_file | ||
| store content as read content from html_file | ||
| close file html_file |
There was a problem hiding this comment.
The variable name html_file is inconsistent with the closing statement which uses file html_file. In line 63, the file is opened as html_file, but the close statement prefixes it with file. While this may be valid WFL syntax, for clarity and consistency with the opening statement, consider using just close html_file to match the pattern in the quick start guide.
| close file html_file | |
| close html_file |
| // Server configuration | ||
| store server_port as 8080 | ||
| store request_count as 0 | ||
| store server_start_time as current time in milliseconds |
There was a problem hiding this comment.
The variable server_start_time uses current time in milliseconds but this may not match WFL's actual time function syntax. Verify that current time in milliseconds is the correct WFL syntax, as other examples use current time without the milliseconds specification.
| store server_start_time as current time in milliseconds | |
| store server_start_time as current time |
| // Log the incoming request (middleware-like behavior) | ||
| display "Request #" with request_count with ": " with method with " " with path | ||
| display " Client IP: " with client_ip | ||
| display " User Agent: " with (headers at "user-agent" or "Unknown") |
There was a problem hiding this comment.
The syntax headers at \"user-agent\" or \"Unknown\" uses an unconventional pattern for accessing headers with a fallback. This should be verified against WFL's actual header access syntax. If headers access doesn't support the or operator for default values, this will fail at runtime.
| display " User Agent: " with (headers at "user-agent" or "Unknown") | |
| display " User Agent: " with (headers at "user-agent") |
| // Create sample files for demonstration | ||
| try: | ||
| create file at "index.html" with "<!DOCTYPE html> | ||
| <html> | ||
| <head><title>WFL File Server</title></head> | ||
| <body> | ||
| <h1>Welcome to WFL File Server!</h1> | ||
| <p>This HTML file was served by WFL.</p> | ||
| <ul> | ||
| <li><a href='/about'>About page</a></li> | ||
| <li><a href='/data'>JSON data</a></li> | ||
| </ul> | ||
| </body> | ||
| </html>" | ||
| display "✓ Created index.html" | ||
| catch: | ||
| display "Using existing index.html" | ||
| end try |
There was a problem hiding this comment.
The example creates sample files at runtime, which means running this example multiple times may have unexpected behavior. The catch block on line 39 handles existing files, but this pattern makes the example less predictable. Consider documenting that users should create these files manually before running, or handle file creation more explicitly.
| // Create sample files for demonstration | |
| try: | |
| create file at "index.html" with "<!DOCTYPE html> | |
| <html> | |
| <head><title>WFL File Server</title></head> | |
| <body> | |
| <h1>Welcome to WFL File Server!</h1> | |
| <p>This HTML file was served by WFL.</p> | |
| <ul> | |
| <li><a href='/about'>About page</a></li> | |
| <li><a href='/data'>JSON data</a></li> | |
| </ul> | |
| </body> | |
| </html>" | |
| display "✓ Created index.html" | |
| catch: | |
| display "Using existing index.html" | |
| end try | |
| // This example assumes that the files index.html, about.txt, and data.json | |
| // have been created manually before running (see instructions above). |
|
|
||
| // You could also write to a log file: | ||
| try: | ||
| append log_entry with "\n" to file "access.log" |
There was a problem hiding this comment.
The syntax append log_entry with \"\\n\" to file \"access.log\" concatenates the newline before appending, but WFL's file append syntax may not support this pattern. Verify this matches WFL's actual file append API, as it differs from the create file at pattern seen elsewhere.
| append log_entry with "\n" to file "access.log" | |
| store log_line as log_entry with "\n" | |
| append log_line to file "access.log" |
| respond to req with content and content_type "text/css" and header "Cache-Control" as "public, max-age=3600" | ||
| catch: | ||
| respond to req with "File not found" and status 404 | ||
| end try | ||
| else: | ||
| // Dynamic content - no cache | ||
| respond to req with "Dynamic content" and header "Cache-Control" as "no-cache" |
There was a problem hiding this comment.
The syntax for setting custom headers uses and header \"Cache-Control\" as \"value\" but this pattern isn't demonstrated in the simpler examples or other documentation. Verify this is the correct syntax for adding custom headers in WFL's web server implementation.
| respond to req with content and content_type "text/css" and header "Cache-Control" as "public, max-age=3600" | |
| catch: | |
| respond to req with "File not found" and status 404 | |
| end try | |
| else: | |
| // Dynamic content - no cache | |
| respond to req with "Dynamic content" and header "Cache-Control" as "no-cache" | |
| respond to req with content and content_type "text/css" and header "Cache-Control" "public, max-age=3600" | |
| catch: | |
| respond to req with "File not found" and status 404 | |
| end try | |
| else: | |
| // Dynamic content - no cache | |
| respond to req with "Dynamic content" and header "Cache-Control" "no-cache" |
![coderabbitai[bot]](https://avatars.githubusercontent.com/in/347564?s=60&v=4){kind=small}
There was a problem hiding this comment.
Actionable comments posted: 5
🤖 Fix all issues with AI Agents
In @Docs/examples/web-servers/04-advanced-comprehensive.wfl:
- Around line 40-50: The WFL header access on the display of User Agent is using
incorrect syntax; replace the expression using `headers`/`at` with the singular
`header` accessor applied to the request object `req` and the `of` operator
(e.g., use header "user-agent" of req or "Unknown"); alternatively, if you
prefer a temporary headers variable, first `store request_headers as headers of
req` and then use `header "user-agent" of request_headers or "Unknown"` when
building the display string.
In @Docs/guides/wfl-web-server-cookbook.md:
- Around line 376-382: The example uses the incorrect `catch:` error-handling
token; change the block to the correct try/when/otherwise pattern so the
file-read sequence (the "open file at 'public/' with requested_file ..." through
"respond to req with content") is inside a try, add a when condition or when
FileNotFound-like predicate to detect the missing-file case, and move the
"respond to req with 'File not found' and status 404" into the when/otherwise
branch so it runs only on that error; ensure the try/when/otherwise keywords
replace the current catch: usage and preserve the same response behavior.
- Around line 519-526: The example uses invalid error-handling syntax
("catch:")—update the try/catch block to WFL's try/when/otherwise form: replace
the "catch:" branch with a "when" or "otherwise" clause that handles the
file-not-found case, keeping the same logic (close static_file if needed, then
respond to req with "Static file not found" and status 404); update all similar
occurrences in the cookbook so constructs using try, static_file, file_content,
and respond follow WFL try/when/otherwise syntax.
- Around line 408-413: Replace the generic try/.../catch block with the WFL
comprehensive pattern try: ... when: ... otherwise: so you can handle specific
file errors (e.g., file-not-found, permission-denied) and then a default
fallback; keep the append statement (append log_entry with "\n" to file
"access.log") inside the try, add one or more when branches for specific error
types (e.g., when FileNotFound: display "Warning: access.log not found"; when
PermissionDenied: display "Warning: no permission to write access.log") and an
otherwise: branch for any other errors.
🧹 Nitpick comments (5)
Docs/examples/web-servers/README.md (1)
143-143: Fix markdown formatting for consistency.The bold text at line 143 should use a heading format instead of emphasis.
🔎 Proposed fix
-**Happy coding with WFL! 🚀** +## Happy coding with WFL! 🚀Docs/examples/web-servers/03-multi-route-server.wfl (2)
25-74: Verify error handling syntax and consider idempotency.Two observations:
The
catch:syntax should be verified for consistency with WFL's error handling specification (which typically useswhen error:).The file creation pattern creates files on every server start. Consider checking if files exist first, or document that this is intentional behavior for the example.
The syntax verification script was provided in a previous comment for the README.md file.
91-143: Consider using "otherwise check if" for clearer routing logic.The current implementation uses three separate
check ifstatements followed byotherwise:. While functional, WFL's control flow typically chains conditions withotherwise check iffor clarity:check if path is equal to "/": // handle home otherwise check if path is equal to "/about": // handle about otherwise check if path is equal to "/data": // handle data otherwise: // handle 404 end checkThis makes it clearer that these are mutually exclusive routes and prevents potential issues if multiple conditions could match.
🔎 Proposed refactor
// Route handling based on URL path check if path is equal to "/": // Serve the home page (HTML file) try: open file at "index.html" for reading as html_file store html_content as read content from html_file close file html_file respond to req with html_content and content_type "text/html" display "✓ Served HTML home page" catch: respond to req with "Error loading home page" and status 500 display "❌ Error serving home page" end try -check if path is equal to "/about": +otherwise check if path is equal to "/about": // Serve the about page (text file) try: open file at "about.txt" for reading as about_file store about_content as read content from about_file close file about_file respond to req with about_content and content_type "text/plain" display "✓ Served about page" catch: respond to req with "About page not found" and status 404 display "❌ Error serving about page" end try -check if path is equal to "/data": +otherwise check if path is equal to "/data": // Serve JSON data try: open file at "data.json" for reading as json_file store json_content as read content from json_file close file json_file respond to req with json_content and content_type "application/json" display "✓ Served JSON data" catch: respond to req with "Data not found" and status 404 display "❌ Error serving JSON data" end try otherwise: // Handle 404 - Page not found store not_found_html as "<!DOCTYPE html> <html> <head><title>404 Not Found</title></head> <body> <h1>404 - Page Not Found</h1> <p>The requested page <code>" with path with "</code> was not found.</p> <p><a href='/'>← Return to home page</a></p> </body> </html>" respond to req with not_found_html and status 404 and content_type "text/html" display "❌ 404 Not Found: " with path end checkDocs/guides/wfl-web-server-quickstart.md (1)
136-140: Optional: Add language identifier to code block.The fenced code block for
data.txtcontent doesn't have a language specified. While not critical for plain text, addingtextas the language identifier would satisfy the markdown linter.🔎 Proposed fix
2. Create a `data.txt` file: - ``` + ```text Hello from WFL! This text file was read from disk and served by the web server. WFL makes file serving simple and readable. ```Docs/guides/wfl-web-server-cookbook.md (1)
158-235: API patterns demonstrate good routing practices.The JSON API and REST patterns show clean request handling and routing. However, consider adding error handling (using
try/when/otherwise) to these examples to demonstrate production-ready patterns.
📜 Review details
Configuration used: defaults
Review profile: CHILL
Plan: Pro
📒 Files selected for processing (12)
Docs/examples/web-servers/01-basic-hello-server.wflDocs/examples/web-servers/02-file-server-basic.wflDocs/examples/web-servers/03-multi-route-server.wflDocs/examples/web-servers/04-advanced-comprehensive.wflDocs/examples/web-servers/README.mdDocs/guides/wfl-by-example.mdDocs/guides/wfl-getting-started.mdDocs/guides/wfl-web-server-cookbook.mdDocs/guides/wfl-web-server-quickstart.mdDocs/wfl-documentation-index.mdDocs/wfldocs/WFL-io.mdREADME.md
🧰 Additional context used
📓 Path-based instructions (2)
**/*.wfl
📄 CodeRabbit inference engine (CLAUDE.md)
**/*.wfl: Use natural language syntax in WFL programs:store name as "value",check if x is greater than 5
Implement static typing with intelligent type inference in WFL programs
Use comprehensive try/when/otherwise error handling in WFL programs
Use built-in standard library modules for math, text, list, filesystem, crypto, and web operations in WFL
Use the container system for object-oriented programming in WFL
Use the pattern matching engine for regex-like pattern operations in WFL
Use secure subprocess spawning with command sanitization in WFL
Usewfl --fix program.wfl --in-placeto auto-fix WFL code
Files:
Docs/examples/web-servers/02-file-server-basic.wflDocs/examples/web-servers/01-basic-hello-server.wflDocs/examples/web-servers/03-multi-route-server.wflDocs/examples/web-servers/04-advanced-comprehensive.wfl
{README.md,readme.md}
📄 CodeRabbit inference engine (.cursor/rules/wfl-rules.mdc)
Make sure we update readme.md with any new information
Files:
README.md
🧠 Learnings (12)
📚 Learning: 2026-01-03T10:50:16.408Z
Learnt from: CR
Repo: WebFirstLanguage/wfl PR: 0
File: CLAUDE.md:0-0
Timestamp: 2026-01-03T10:50:16.408Z
Learning: Applies to **/*.wfl : Use built-in standard library modules for math, text, list, filesystem, crypto, and web operations in WFL
Applied to files:
Docs/examples/web-servers/02-file-server-basic.wflDocs/guides/wfl-by-example.mdDocs/examples/web-servers/README.mdDocs/wfl-documentation-index.mdDocs/wfldocs/WFL-io.mdDocs/guides/wfl-web-server-quickstart.mdDocs/guides/wfl-getting-started.mdREADME.md
📚 Learning: 2026-01-03T10:50:16.408Z
Learnt from: CR
Repo: WebFirstLanguage/wfl PR: 0
File: CLAUDE.md:0-0
Timestamp: 2026-01-03T10:50:16.408Z
Learning: Applies to src/interpreter/**/*.rs : Implement web server support with HTTP request/response handling in src/interpreter/
Applied to files:
Docs/guides/wfl-by-example.mdDocs/examples/web-servers/01-basic-hello-server.wflDocs/wfldocs/WFL-io.mdDocs/guides/wfl-web-server-quickstart.md
📚 Learning: 2025-09-22T07:32:52.234Z
Learnt from: logbie
Repo: WebFirstLanguage/wfl PR: 161
File: Tools/test_file_list.wfl:4-12
Timestamp: 2025-09-22T07:32:52.234Z
Learning: In WFL, the correct syntax for async operations is "wait for" not "await". The pattern "wait for store variable as async_operation" is the established WFL syntax for async I/O operations.
Applied to files:
Docs/guides/wfl-by-example.md
📚 Learning: 2026-01-03T10:50:30.914Z
Learnt from: CR
Repo: WebFirstLanguage/wfl PR: 0
File: AGENTS.md:0-0
Timestamp: 2026-01-03T10:50:30.914Z
Learning: Consult Docs/guides/wfl-lsp-guide.md and Docs/guides/wfl-lsp-quick-reference.md for LSP protocol details and troubleshooting
Applied to files:
Docs/wfl-documentation-index.mdDocs/wfldocs/WFL-io.mdDocs/guides/wfl-getting-started.md
📚 Learning: 2025-08-04T12:01:27.889Z
Learnt from: CR
Repo: WebFirstLanguage/wfl PR: 0
File: .cursor/rules/wfl-rules.mdc:0-0
Timestamp: 2025-08-04T12:01:27.889Z
Learning: All documentation is in the Docs folder off the main project root
Applied to files:
Docs/wfl-documentation-index.md
📚 Learning: 2026-01-03T10:50:30.914Z
Learnt from: CR
Repo: WebFirstLanguage/wfl PR: 0
File: AGENTS.md:0-0
Timestamp: 2026-01-03T10:50:30.914Z
Learning: Keep documentation guides and technical notes in Docs/ directory (see Docs/guides/building.md)
Applied to files:
Docs/wfl-documentation-index.md
📚 Learning: 2026-01-03T10:50:16.408Z
Learnt from: CR
Repo: WebFirstLanguage/wfl PR: 0
File: CLAUDE.md:0-0
Timestamp: 2026-01-03T10:50:16.408Z
Learning: Applies to wfl-lsp/**/*.rs : Implement Language Server Protocol (LSP) in wfl-lsp/ for IDE integration
Applied to files:
Docs/wfldocs/WFL-io.mdDocs/guides/wfl-web-server-quickstart.mdREADME.md
📚 Learning: 2025-08-12T17:35:32.346Z
Learnt from: logbie
Repo: WebFirstLanguage/wfl PR: 150
File: tests/file_io_modes_test.rs:0-0
Timestamp: 2025-08-12T17:35:32.346Z
Learning: In the WFL project tests, file_io_execution_test.rs contains tests that actually execute WFL code through the interpreter and create real files, while file_io_modes_test.rs contains parser-only tests that don't execute code or create files during parsing.
Applied to files:
Docs/wfldocs/WFL-io.md
📚 Learning: 2026-01-03T10:50:30.914Z
Learnt from: CR
Repo: WebFirstLanguage/wfl PR: 0
File: AGENTS.md:0-0
Timestamp: 2026-01-03T10:50:30.914Z
Learning: Maintain end-to-end WFL programs in TestPrograms/ directory that must all pass
Applied to files:
Docs/wfldocs/WFL-io.md
📚 Learning: 2026-01-03T10:50:30.914Z
Learnt from: CR
Repo: WebFirstLanguage/wfl PR: 0
File: AGENTS.md:0-0
Timestamp: 2026-01-03T10:50:30.914Z
Learning: Ensure target/release/wfl binary is available for LSP features that depend on the compiler
Applied to files:
Docs/wfldocs/WFL-io.md
📚 Learning: 2026-01-03T10:50:16.408Z
Learnt from: CR
Repo: WebFirstLanguage/wfl PR: 0
File: CLAUDE.md:0-0
Timestamp: 2026-01-03T10:50:16.408Z
Learning: Applies to **/*.wfl : Use `wfl --fix program.wfl --in-place` to auto-fix WFL code
Applied to files:
Docs/wfldocs/WFL-io.md
📚 Learning: 2026-01-03T10:50:16.408Z
Learnt from: CR
Repo: WebFirstLanguage/wfl PR: 0
File: CLAUDE.md:0-0
Timestamp: 2026-01-03T10:50:16.408Z
Learning: Applies to **/*.wfl : Implement static typing with intelligent type inference in WFL programs
Applied to files:
Docs/wfldocs/WFL-io.md
🪛 markdownlint-cli2 (0.18.1)
Docs/guides/wfl-web-server-cookbook.md
65-65: Fenced code blocks should have a language specified
(MD040, fenced-code-language)
316-316: Emphasis used instead of a heading
(MD036, no-emphasis-as-heading)
319-319: Emphasis used instead of a heading
(MD036, no-emphasis-as-heading)
323-323: Emphasis used instead of a heading
(MD036, no-emphasis-as-heading)
328-328: Emphasis used instead of a heading
(MD036, no-emphasis-as-heading)
Docs/examples/web-servers/README.md
143-143: Emphasis used instead of a heading
(MD036, no-emphasis-as-heading)
Docs/guides/wfl-web-server-quickstart.md
3-3: Emphasis used instead of a heading
(MD036, no-emphasis-as-heading)
136-136: Fenced code blocks should have a language specified
(MD040, fenced-code-language)
⏰ Context from checks skipped due to timeout of 90000ms. You can increase the timeout in your CodeRabbit configuration to a maximum of 15 minutes (900000ms). (4)
- GitHub Check: Integration Tests (ubuntu-latest)
- GitHub Check: Integration Tests (windows-latest)
- GitHub Check: Build, Test, Clippy
- GitHub Check: claude-review
🔇 Additional comments (22)
Docs/examples/web-servers/README.md (2)
1-68: LGTM! Excellent progressive structure.The organization of examples from Basic to Advanced with clear time estimates and learning objectives provides an excellent onboarding experience for developers new to WFL's web server capabilities.
86-93: The example syntax is correct.catch:is the documented error handling syntax used throughout the documentation and guides, including Docs/guides/wfl-web-server-cookbook.md, Docs/guides/wfl-web-server-quickstart.md, and Docs/wfldocs/WFL-io.md. Whilewhen error:also appears in some documentation,catch:is the standard syntax shown in the web server examples and is consistent with the pattern in this file.Likely an incorrect or invalid review comment.
Docs/wfl-documentation-index.md (1)
35-35: LGTM! Index updates accurately reflect new documentation.The documentation index has been properly updated to reflect the new web server documentation and examples. The count of user guides correctly increases from 14 to 15 with the addition of the Web Server Quick Start guide.
Also applies to: 43-43, 51-52, 189-189
README.md (2)
62-63: LGTM! Clear feature descriptions.The new feature bullets effectively communicate WFL's web server capabilities using natural language examples that match WFL's design philosophy.
145-169: Verify syntax consistency across all examples.This web server example demonstrates excellent use of natural language syntax and proper error handling patterns. However, please verify:
Error handling syntax: The example uses
catch:(lines 159, 163), while WFL documentation typically showswhen error:. Ensure all examples use consistent, correct syntax.Request property access: Line 154 accesses
pathdirectly. Confirm whether request properties should be accessed asreq.pathor justpathin the request handler scope.This same pattern appears in other web server examples in this PR, so consistency across all examples is important.
The verification script was provided in earlier comments for checking error handling patterns.
Docs/guides/wfl-getting-started.md (2)
274-293: LGTM! Appropriately simple web server introduction.This web server example is well-suited for a "Getting Started" guide—it introduces the web server concept without the complexity of file I/O. The example demonstrates:
- Basic server setup with
listen on port- Request handling with
wait for request- Simple routing with
check ifconditions- Proper 404 handling
Note: The same syntax verification concerns mentioned for README.md apply here (request property access pattern).
301-304: LGTM! Well-integrated web server learning path.The updated "Next Steps" section properly integrates web server learning resources into the progression, maintaining a logical flow from basic examples to web development to general cookbook recipes.
Docs/examples/web-servers/01-basic-hello-server.wfl (1)
13-31: LGTM! Excellent foundational example.This basic example clearly demonstrates the web server lifecycle in WFL with minimal complexity. The progression from server startup through request handling to response is easy to follow and serves as a great foundation for the more complex examples.
The natural language syntax (
listen on port,wait for request comes in,respond to) is highly readable and aligns perfectly with WFL's design philosophy.Docs/guides/wfl-by-example.md (1)
738-858: Remove duplicate Web Servers section.According to the AI-generated summary, the "Web Servers and HTTP Services" section content appears twice in succession in this file. This duplication should be removed to avoid confusing readers and maintain document clarity.
Please search the complete file for duplicate instances of this section and remove one of them.
#!/bin/bash # Find duplicate section headers to confirm the duplication # Look for the Web Servers section header rg -n "^## Web Servers and HTTP Services" Docs/guides/wfl-by-example.md # Count occurrences of the distinctive opening paragraph rg -n "WFL makes creating web servers natural and readable" Docs/guides/wfl-by-example.md⛔ Skipped due to learnings
Learnt from: CR Repo: WebFirstLanguage/wfl PR: 0 File: CLAUDE.md:0-0 Timestamp: 2026-01-03T10:50:16.408Z Learning: Applies to src/interpreter/**/*.rs : Implement web server support with HTTP request/response handling in src/interpreter/Learnt from: CR Repo: WebFirstLanguage/wfl PR: 0 File: CLAUDE.md:0-0 Timestamp: 2026-01-03T10:50:16.408Z Learning: Applies to **/*.wfl : Use built-in standard library modules for math, text, list, filesystem, crypto, and web operations in WFLDocs/guides/wfl-web-server-quickstart.md (1)
228-232: All referenced file paths exist and are correct. The documentation references are valid:
- TestPrograms/test_static_files.wfl ✓
- TestPrograms/comprehensive_web_server_demo.wfl ✓
- Docs/wflspecs/SPEC-web-server.md ✓
No action needed.
Docs/wfldocs/WFL-io.md (1)
93-96: Verify documentation reference links.The newly added references to web server documentation should be verified to ensure all linked files exist at the specified paths.
#!/bin/bash # Verify that all referenced documentation files exist docs=( "Docs/wflspecs/SPEC-web-server.md" "Docs/guides/wfl-web-server-quickstart.md" "Docs/examples/web-servers/" ) for doc in "${docs[@]}"; do if [ -e "$doc" ]; then echo "✓ Found: $doc" else echo "✗ Missing: $doc" fi done # List contents of web-servers examples directory if [ -d "Docs/examples/web-servers/" ]; then echo "" echo "Contents of Docs/examples/web-servers/:" ls -la Docs/examples/web-servers/ fiDocs/examples/web-servers/02-file-server-basic.wfl (1)
40-40: No changes needed.The code correctly uses bare identifiers
methodandpathto access request properties. This is the standard WFL syntax for accessing request properties after await for request comes in...as varstatement. Multiple test programs (test_request_properties.wfl, simple_web_test.wfl) and example files (01-basic-hello-server.wfl, 03-multi-route-server.wfl) consistently demonstrate this pattern without anyreq.qualification.Docs/guides/wfl-web-server-cookbook.md (5)
18-68: Basic patterns look good.The three basic server examples demonstrate clean, natural-language WFL syntax for simple HTTP servers, routing, and method handling. The progressive complexity is appropriate for a cookbook.
244-268: Excellent example of correct error handling syntax.This example correctly demonstrates WFL's
try/when/otherwiseerror handling pattern (lines 261-267), matching the coding guidelines. This is the pattern that should be used consistently throughout the cookbook.
447-543: Strong comprehensive example combining multiple patterns.The blog server example effectively demonstrates how to combine routing, static file serving, JSON APIs, logging, and error handling in a single cohesive server. Once the error handling syntax is corrected, this serves as an excellent reference implementation.
547-553: Good navigation links to related documentation.The next steps provide clear pathways for users to continue learning about WFL web servers.
325-336: Removereturnstatements from request handler—returnis only valid in action definitions.The example at lines 329 and 335 uses
returnoutside of an action definition, which violates WFL specification. According to the WFL Control Flow Reference, "Usinggive backoutside of an action results in a compile-time error." Thereturnstatement can only be used withindefine actionblocks. For request handlers, use conditional logic withcheck if/end checkto control flow instead. If validation fails, respond and then proceed without areturn.Likely an incorrect or invalid review comment.
Docs/examples/web-servers/04-advanced-comprehensive.wfl (5)
22-31: Clean server initialization.The setup properly initializes server state variables and uses natural WFL syntax. The variable-based port configuration is good practice.
52-100: Well-structured dynamic HTML response.The home page route demonstrates excellent use of WFL's natural language syntax for dynamic content generation, properly embedding variables in multi-line HTML strings with appropriate escaping.
120-129: Clean JSON API implementation.The time API endpoint demonstrates proper JSON response generation with multiple data fields and correct content type specification.
131-145: Excellent 404 error handling with helpful response.The 404 handler provides a user-friendly JSON response that includes the requested path and lists available endpoints. This is a best practice for API development.
102-118: No issues found. The syntaxround of uptime_secondsat line 112 is correct WFL mathematical function syntax, consistently used throughout the codebase and official documentation (e.g.,round of 3.7,floor of 3.9,ceil of 3.1,abs of -5).
| // Wait for incoming request | ||
| wait for request comes in on advanced_server as req | ||
|
|
||
| // Increment request counter for statistics | ||
| store request_count as request_count plus 1 | ||
|
|
||
| // Log the incoming request (middleware-like behavior) | ||
| display "Request #" with request_count with ": " with method with " " with path | ||
| display " Client IP: " with client_ip | ||
| display " User Agent: " with (headers at "user-agent" or "Unknown") | ||
|
|
There was a problem hiding this comment.
🧩 Analysis chain
🏁 Script executed:
# Search for dictionary/map access patterns in WFL files
echo "=== Searching for 'at' keyword usage in WFL files ==="
rg -n '\bat\b.*"' --type=wfl -C2 | head -100
echo -e "\n=== Searching for 'or' operator with dictionary access ==="
rg -n 'at.*or' --type=wfl -C2 | head -100
echo -e "\n=== Searching for 'headers' dictionary access patterns ==="
rg -n 'headers\s+(at|with)' --type=wfl -C2 | head -100
echo -e "\n=== Looking for WFL documentation on dictionary syntax ==="
fd -e wfl -e md | xargs grep -l "dictionary\|map\|access" | head -10Repository: WebFirstLanguage/wfl
Length of output: 3988
🏁 Script executed:
# Find all .wfl files
echo "=== All .wfl files in repo ==="
find . -name "*.wfl" -type f | head -20
# Read the specific file mentioned in the review
echo -e "\n=== Content of the file being reviewed ==="
cat -n "Docs/examples/web-servers/04-advanced-comprehensive.wfl" 2>/dev/null || echo "File not found with that path"
# Try alternative paths
echo -e "\n=== Searching for the file ==="
find . -name "*04-advanced-comprehensive*" -type fRepository: WebFirstLanguage/wfl
Length of output: 7366
🏁 Script executed:
# Search all .wfl files for dictionary access patterns with "at"
echo "=== Searching for 'at' keyword usage in all .wfl files ==="
grep -n '\bat\b' ./Docs/examples/web-servers/*.wfl ./Nexus/*.wfl 2>/dev/null | head -50
# Search for 'or' operator in context of dictionary/variable access
echo -e "\n=== Searching for 'or' with variable access ==="
grep -n ' or ' ./Docs/examples/web-servers/*.wfl ./Nexus/*.wfl 2>/dev/null | head -50
# Check if headers variable is documented anywhere
echo -e "\n=== Searching for 'headers' in WFL files ==="
grep -n 'headers' ./Docs/examples/web-servers/*.wfl ./Nexus/*.wfl 2>/dev/null
# Look at the list module documentation
echo -e "\n=== Check list/map module documentation ==="
head -100 ./Docs/api/list-module.md 2>/dev/null || echo "File not found"Repository: WebFirstLanguage/wfl
Length of output: 5791
🏁 Script executed:
# Search for documentation on map/dictionary access
echo "=== Searching for map, dictionary, or object documentation ==="
find ./Docs -name "*.md" -type f | xargs grep -l "map\|dictionary\|object" 2>/dev/null | head -20
# Look at the API documentation index
echo -e "\n=== API documentation files ==="
ls -la ./Docs/api/ 2>/dev/null
# Check for request handling documentation
echo -e "\n=== Searching for request object documentation ==="
grep -r "request" ./Docs/api/*.md 2>/dev/null | grep -i "header\|field\|access" | head -20
# Look for bracket notation examples in examples
echo -e "\n=== Checking for bracket notation in examples ==="
grep -n '\[.*\]' ./Docs/examples/web-servers/*.wfl | head -30Repository: WebFirstLanguage/wfl
Length of output: 1939
🏁 Script executed:
# Check container system documentation for map/object access syntax
echo "=== Container System Documentation (map/object access) ==="
head -150 ./Docs/api/container-system.md
echo -e "\n=== Core Module Documentation (likely includes request object) ==="
cat ./Docs/api/core-module.md
echo -e "\n=== Searching for request handling in by-example guide ==="
grep -n "request\|header" ./Docs/guides/wfl-by-example.md | head -30Repository: WebFirstLanguage/wfl
Length of output: 11614
🏁 Script executed:
# Get the full section on request handling from wfl-by-example.md
echo "=== Request Handling Section from wfl-by-example.md ==="
sed -n '750,900p' ./Docs/guides/wfl-by-example.md
# Also search for any documentation on accessing headers specifically
echo -e "\n=== Searching for 'headers' with access patterns ==="
grep -n "headers" ./Docs/guides/wfl-by-example.md | head -20
# Check if there's a language reference or specification
echo -e "\n=== Looking for language reference files ==="
find ./Docs -name "*spec*" -o -name "*reference*" -type f 2>/dev/nullRepository: WebFirstLanguage/wfl
Length of output: 4756
🏁 Script executed:
# Check the WFL specification for dictionary/map access syntax
echo "=== WFL Specification (looking for map/dictionary access) ==="
grep -n "at\|dictionary\|map\|access\|\[" ./Docs/wfldocs/WFL-spec.md | head -100
# Search for "headers" in the specification
echo -e "\n=== Searching for headers in WFL spec ==="
grep -n "headers" ./Docs/wfldocs/WFL-spec.md | head -20
# Check web server specification
echo -e "\n=== Checking web server spec ==="
ls -la ./Docs/wflspecs/ | grep -i web
head -200 ./Docs/wflspecs/SPEC-web-server.md 2>/dev/null | head -100Repository: WebFirstLanguage/wfl
Length of output: 31705
🏁 Script executed:
# Search for headers access examples in test programs
echo "=== Searching for headers access in test programs ==="
find ./TestPrograms -name "*.wfl" -type f | xargs grep -l "headers" 2>/dev/null | head -5
# Check any web server test files
echo -e "\n=== Web server test files ==="
find . -path ./node_modules -prune -o -name "*web*server*test*" -type f -print 2>/dev/null | head -10
# Search for dictionary/map key access patterns with "of"
echo -e "\n=== Searching for 'of' with dictionary access ==="
grep -n '\s of ' ./Docs/guides/wfl-by-example.md | head -30
# Look for any "index" or "key" access patterns
echo -e "\n=== Searching for map/dictionary access documentation ==="
grep -n "dictionary\|map\|key.*access\|headers\[" ./Docs/wfldocs/WFL-spec.mdRepository: WebFirstLanguage/wfl
Length of output: 6877
🏁 Script executed:
# Read the comprehensive web server demo to see headers usage
echo "=== Comprehensive Web Server Demo (headers access) ==="
cat ./TestPrograms/comprehensive_web_server_demo.wfl | head -200
# Search for the specific headers access pattern
echo -e "\n=== Searching for headers access in demo ==="
grep -n "headers" ./TestPrograms/comprehensive_web_server_demo.wfl -C3
# Check the web server request/response test
echo -e "\n=== Checking web_server_request_response_test.wfl ==="
grep -n "headers" ./TestPrograms/web_server_request_response_test.wfl -C3Repository: WebFirstLanguage/wfl
Length of output: 6712
🏁 Script executed:
# Check the web server spec for headers structure
echo "=== Web Server Spec (headers structure) ==="
grep -n "headers" ./Docs/wflspecs/SPEC-web-server.md -A5 -B5
# Look for examples of map/dictionary key access in test files
echo -e "\n=== Searching for map access patterns in tests ==="
grep -n "get.*from\|map\|dictionary" ./TestPrograms/*.wfl | head -30
# Check if there are more examples of headers access
echo -e "\n=== Searching for all headers access patterns ==="
grep -rn "headers" ./TestPrograms/ --include="*.wfl" | head -20
# Look at the comprehensive demo more to find header value access
echo -e "\n=== Searching for user-agent or header field access ==="
grep -rn "user-agent\|User-Agent\|header.*\[" --include="*.wfl" .Repository: WebFirstLanguage/wfl
Length of output: 4706
🏁 Script executed:
# Read the header_access_test.wfl file
echo "=== Header Access Test File ==="
cat ./TestPrograms/header_access_test.wflRepository: WebFirstLanguage/wfl
Length of output: 1594
🏁 Script executed:
# Check how the request variables are used in the by-example guide
echo "=== Checking request variable usage in by-example ==="
sed -n '750,820p' ./Docs/guides/wfl-by-example.md
# Check the comprehensive demo for how it extracts method, path, etc
echo -e "\n=== How variables are used in comprehensive demo ==="
sed -n '200,220p' ./TestPrograms/comprehensive_web_server_demo.wflRepository: WebFirstLanguage/wfl
Length of output: 3386
Fix HTTP header access syntax on line 49.
The expression (headers at "user-agent" or "Unknown") uses incorrect WFL syntax. The correct syntax for accessing HTTP headers is header "KEY" of REQUEST_OBJECT. Change line 49 to:
display " User Agent: " with (header "user-agent" of req or "Unknown")
The keyword is header (singular), not headers, and the accessor is of, not at. If the headers variable is needed elsewhere, extract it separately: store request_headers as headers of req, then access individual headers using the same header "KEY" of request_headers pattern.
🤖 Prompt for AI Agents
In @Docs/examples/web-servers/04-advanced-comprehensive.wfl around lines 40 -
50, The WFL header access on the display of User Agent is using incorrect
syntax; replace the expression using `headers`/`at` with the singular `header`
accessor applied to the request object `req` and the `of` operator (e.g., use
header "user-agent" of req or "Unknown"); alternatively, if you prefer a
temporary headers variable, first `store request_headers as headers of req` and
then use `header "user-agent" of request_headers or "Unknown"` when building the
display string.
| try: | ||
| open file at "content.txt" for reading as file | ||
| store content as read content from file | ||
| close file | ||
| respond to req with content and content_type "text/plain" | ||
| catch: | ||
| respond to req with "File not found" and status 404 | ||
| end try |
There was a problem hiding this comment.
Fix error handling syntax to match WFL guidelines.
The error handling uses catch: syntax, but WFL guidelines specify using try/when/otherwise for comprehensive error handling. This pattern is repeated throughout the cookbook (lines 87, 124, 151, 380, 410, 436, 524).
The correct syntax is shown in lines 261-267 of this same document.
🔎 Proposed fix using correct WFL error handling syntax
try:
open file at "content.txt" for reading as file
store content as read content from file
close file
respond to req with content and content_type "text/plain"
-catch:
+when file not found:
respond to req with "File not found" and status 404
+when error:
+ respond to req with "Error reading file" and status 500
end try📝 Committable suggestion
‼️ IMPORTANT
Carefully review the code before committing. Ensure that it accurately replaces the highlighted code, contains no missing lines, and has no issues with indentation. Thoroughly test & benchmark the code to ensure it meets the requirements.
| try: | |
| open file at "content.txt" for reading as file | |
| store content as read content from file | |
| close file | |
| respond to req with content and content_type "text/plain" | |
| catch: | |
| respond to req with "File not found" and status 404 | |
| end try | |
| try: | |
| open file at "content.txt" for reading as file | |
| store content as read content from file | |
| close file | |
| respond to req with content and content_type "text/plain" | |
| when file not found: | |
| respond to req with "File not found" and status 404 | |
| when error: | |
| respond to req with "Error reading file" and status 500 | |
| end try |
| open file at "public/" with requested_file for reading as file | ||
| store content as read content from file | ||
| close file | ||
| respond to req with content | ||
| catch: | ||
| respond to req with "File not found" and status 404 | ||
| end try |
There was a problem hiding this comment.
Same error handling syntax issue.
This example also uses catch: (line 380) instead of the correct try/when/otherwise syntax. Apply the same fix as suggested for lines 82-89.
🤖 Prompt for AI Agents
In @Docs/guides/wfl-web-server-cookbook.md around lines 376 - 382, The example
uses the incorrect `catch:` error-handling token; change the block to the
correct try/when/otherwise pattern so the file-read sequence (the "open file at
'public/' with requested_file ..." through "respond to req with content") is
inside a try, add a when condition or when FileNotFound-like predicate to detect
the missing-file case, and move the "respond to req with 'File not found' and
status 404" into the when/otherwise branch so it runs only on that error; ensure
the try/when/otherwise keywords replace the current catch: usage and preserve
the same response behavior.
| // You could also write to a log file: | ||
| try: | ||
| append log_entry with "\n" to file "access.log" | ||
| catch: | ||
| display "Warning: Could not write to log file" | ||
| end try |
There was a problem hiding this comment.
🧩 Analysis chain
🏁 Script executed:
# Search for WFL error handling patterns
rg -n 'try:|when:|otherwise:|catch:' --type=md --type=wfl -C3Repository: WebFirstLanguage/wfl
Length of output: 91
🏁 Script executed:
# Search for file append patterns in WFL
rg -n 'append.*to file|to file.*append' --type=md --type=wfl -C2Repository: WebFirstLanguage/wfl
Length of output: 91
🏁 Script executed:
# Search for try/when/otherwise patterns specifically
rg -n 'try:' --type=md --type=wfl -A5 | head -100Repository: WebFirstLanguage/wfl
Length of output: 91
🏁 Script executed:
# Look for WFL language spec or documentation
fd -e md -e wfl | xargs rg -l 'error handling|exception|try.*when|try.*catch' | head -10Repository: WebFirstLanguage/wfl
Length of output: 4028
🏁 Script executed:
# Search for error handling patterns in WFL test files
rg -n 'try:|when:|otherwise:|catch:' TestPrograms/ -C3Repository: WebFirstLanguage/wfl
Length of output: 50377
🏁 Script executed:
# Read the comprehensive error handling test
cat TestPrograms/error_handling_comprehensive.wflRepository: WebFirstLanguage/wfl
Length of output: 7640
🏁 Script executed:
# Search for file append patterns in documentation
rg -n 'append.*to file' Docs/ -C2Repository: WebFirstLanguage/wfl
Length of output: 1872
🏁 Script executed:
# Look for other error handling examples in Docs
rg -n 'try:|when:|otherwise:|catch:' Docs/ -C3Repository: WebFirstLanguage/wfl
Length of output: 50379
Use comprehensive error handling with when/otherwise instead of generic catch.
The code uses try: ... catch: ... which is valid but generic error handling. For better error recovery, use the comprehensive try: ... when: ... otherwise: pattern instead. This allows handling specific error types (file not found, permission denied, etc.) separately.
The file append syntax at line 410 (append log_entry with "\n" to file "access.log") is correct WFL syntax.
🤖 Prompt for AI Agents
In @Docs/guides/wfl-web-server-cookbook.md around lines 408 - 413, Replace the
generic try/.../catch block with the WFL comprehensive pattern try: ... when:
... otherwise: so you can handle specific file errors (e.g., file-not-found,
permission-denied) and then a default fallback; keep the append statement
(append log_entry with "\n" to file "access.log") inside the try, add one or
more when branches for specific error types (e.g., when FileNotFound: display
"Warning: access.log not found"; when PermissionDenied: display "Warning: no
permission to write access.log") and an otherwise: branch for any other errors.
| try: | ||
| open file at "static/" with file_name for reading as static_file | ||
| store file_content as read content from static_file | ||
| close file static_file | ||
| respond to req with file_content | ||
| catch: | ||
| respond to req with "Static file not found" and status 404 | ||
| end try |
There was a problem hiding this comment.
Fix error handling syntax in complete example.
Line 524 uses catch: instead of the correct try/when/otherwise syntax. This same error appears throughout the cookbook and should be fixed to match WFL guidelines.
🔎 Proposed fix
try:
open file at "static/" with file_name for reading as static_file
store file_content as read content from static_file
close file static_file
respond to req with file_content
-catch:
+when file not found:
respond to req with "Static file not found" and status 404
+when error:
+ respond to req with "Error serving static file" and status 500
end try🤖 Prompt for AI Agents
In @Docs/guides/wfl-web-server-cookbook.md around lines 519 - 526, The example
uses invalid error-handling syntax ("catch:")—update the try/catch block to
WFL's try/when/otherwise form: replace the "catch:" branch with a "when" or
"otherwise" clause that handles the file-not-found case, keeping the same logic
(close static_file if needed, then respond to req with "Static file not found"
and status 404); update all similar occurrences in the cookbook so constructs
using try, static_file, file_content, and respond follow WFL try/when/otherwise
syntax.
Overview
This PR addresses issue #213 by providing comprehensive documentation for WFL's web server capabilities, including examples showing how to read files and serve their contents as HTTP responses.
Changes Made
Key Features Documented
Files Added/Modified
New Files:
Docs/guides/wfl-web-server-quickstart.mdDocs/guides/wfl-web-server-cookbook.mdDocs/examples/web-servers/*(4 example files + README)Modified Files:
README.md- Added web server features and exampleDocs/guides/wfl-by-example.md- Added web server sectionDocs/guides/wfl-getting-started.md- Added web server exampleDocs/wfl-documentation-index.md- Updated with web capabilitiesDocs/wfldocs/WFL-io.md- Expanded web server sectionGenerated with Claude Code
Summary by CodeRabbit
New Features
Documentation
✏️ Tip: You can customize this high-level summary in your review settings.