Add Plack::Handler::Netty implementation plan

[fglock]

Summary

Proposes implementing Plack::Handler::Netty - a PSGI server handler that bridges Perl web frameworks (Dancer2, Catalyst, Mojolicious) to Java's Netty HTTP server. This enables any PSGI-compatible application to run on PerlOnJava with async I/O performance.

Motivation

• Universal framework support: One handler serves Dancer2, Catalyst, Mojolicious, and any PSGI app
• Performance: Netty's async I/O handles 10k+ concurrent connections on a single thread
• Compatibility: Single-threaded event loop works with PerlOnJava's current constraints (no threads/fork)
• Proven prototype: examples/http_server/ already demonstrates Netty + PerlOnJava integration

Approach

Target Framework: Dancer2

Starting with Dancer2 because:

• Simplest to test (5-line apps possible)
• Pure Perl, already installed on PerlOnJava
• PSGI-native (built on Plack)
• Once working, Catalyst/Mojolicious work automatically via PSGI

Architecture

Browser → Netty (async I/O) → Plack::Handler::Netty (adapter)
         → PSGI App (Dancer2/etc) → Response → Netty → Browser

Key mapping: Convert Netty HttpRequest → PSGI %env hash → call $app->(\%env) → convert PSGI [status, headers, body] → Netty HttpResponse

Why Netty?

• Battle-tested (powers Twitter, Elasticsearch, Cassandra)
• Single-threaded event loop (no PerlOnJava thread-safety issues)
• Async I/O (many concurrent connections, one thread)
• Zero dependencies (single JAR)

Changes in This PR

This PR contains planning only - no implementation yet:

✅ dev/modules/plack_handler_netty.md - Complete implementation plan with:

• Background and motivation
• Architecture and PSGI mapping
• 5-phase implementation plan (5 weeks)
• Risk assessment and success metrics
• Extension plan for Catalyst/Mojolicious

✅ dev/sandbox/http_server/ - Test scaffolding:

• test_netty_handler.pl - Minimal PSGI app test
• dancer_app.pl - Sample Dancer2 application
• test_dancer.pl - Dancer2 integration runner
• README.md - Test documentation

Implementation Phases (Post-Approval)

1. Week 1: Core PSGI handler (NettyPSGIServer.java + Plack::Handler::Netty.pm)
2. Week 2: Dancer2 integration (real app testing)
3. Week 3: Streaming responses (chunked encoding)
4. Week 4: Production features (config, error handling, perf testing)
5. Week 5: Documentation and final PR

Prerequisites

• Dancer2 Type::Tiny scoping bug must be fixed first (see dev/modules/dancer2_support.md Issue 3)
• PerlOnJava built with make
• Netty JAR available (already used in examples/http_server/)

Testing Plan

# Phase 1: Minimal PSGI
./jperl dev/sandbox/http_server/test_netty_handler.pl

# Phase 2: Dancer2
./jperl dev/sandbox/http_server/test_dancer.pl
curl http://localhost:5000/user/123

# Phase 4: Performance
wrk -t4 -c100 -d30s http://localhost:5000/

Questions for Review

1. Does the phased approach make sense?
2. Should we fix Dancer2 Type::Tiny bug first, or proceed with minimal PSGI tests?
3. Any concerns about the PSGI environment mapping?
4. Should streaming support (Phase 3) be mandatory, or optional for v0.1?

Related Work

• dev/modules/dancer2_support.md - Dancer2 installed, blocked by Type::Tiny scoping
• examples/http_server/ - Working Netty + Perl prototype
• dev/modules/mojo_ioloop.md - Mojolicious 55/108 tests passing

Success Metrics

• Minimal PSGI app runs (Phase 1)
• Dancer2 app with routes/params/JSON works (Phase 2)
• Performance ≥ 5,000 req/s for "Hello World" (Phase 4)
• Documentation complete with examples

Next Steps After Approval

1. Implement NettyPSGIServer.java (refactor from prototype)
2. Implement Plack::Handler::Netty.pm
3. Test with minimal PSGI app
4. Open follow-up PR with implementation

---

This PR is request for feedback on the plan. Implementation will come in a follow-up PR after review.