Replacing stdlib net with lori

[SeanTAllen]

Replacing stdlib net with lori

Plan for replacing ponyc's stdlib net package with lori. Phase 0 (porting missing old-net tests into lori before the move) is tracked separately in lori.

Phase 1: ponyc — Replace the net package

1.1 Remove old net package

Delete all 15 files from packages/net/.

1.2 Copy lori source into packages/net/

• Copy all 58 non-test .pony files from lori into packages/net/
• Rename lori.pony to net.pony (package docstring file named after the package)
• Update all use "lori" to use "net" in docstring code examples (5 occurrences in the package docstring file)
• Update 44 documentation links in net.pony — 43 type links from [TypeName](/lori/lori-TypeName/) to [TypeName](/net/net-TypeName/) plus the notifier package index link (/lori/notifier--index/ → /net/notifier--index/)
• Update the hardcoded GitHub issues URL in _unreachable.pony: https://github.com/ponylang/lori/issues → https://github.com/ponylang/ponyc/issues
• Update any other prose references to "lori" in docstrings to reflect the new package name

1.3 Copy notifier subpackage

• Copy lori/notifier/ to packages/net/notifier/
• Update docstring code examples in notifier.pony:
  • 3 use "lori" → use "net"
  • 2 use "lori/notifier" → use "net/notifier" plus 1 use notifier = "lori/notifier" → use notifier = "net/notifier"
  • Prose references to "lori" and "lori/notifier" → "net" and "net/notifier"
• Rename the import alias in all 15 source files: use lori = ".." → use net = "..", and update all 201 qualified references (lori.TCPConnectionActor → net.TCPConnectionActor, etc.)
• Verify the use ".." relative import works in stdlib

1.4 Copy lori tests into packages/net/

• Copy all _test_*.pony files from lori into packages/net/
• Copy notifier/_test*.pony files too
• Copy lori's _test.pony — it already follows the stdlib convention (actor \nodoc\ Main is TestList with both new create(env: Env) => PonyTest(env, this) and new make() => None, plus notifier delegation)
• Plug into stdlib's parent test runner
• Verify no port conflicts with other stdlib tests

1.5 Update stdlib test runner

packages/stdlib/_test.pony already has use net = "net" and net.Main.make().tests(test) — the new net's test runner follows the same convention, so no structural changes are needed.

1.6 Update backpressure package

Rewrite the docstring example in packages/backpressure/backpressure.pony — it uses old-net types (TCPConnectionNotify, TCPConnection, TCPConnectAuth). Rewrite to use lori's TCPConnectionActor pattern. The actual backpressure code (primitives, FFI calls) doesn't reference net types and needs no code change.

1.7 Replace/add stress tests

• ponyc's existing test/rt-stress/tcp-swarm/ uses old-net types and will fail to compile. Replace it with lori's tcp-swarm stress test.
• Copy lori's UDP stress test (udp-flood) to test/rt-stress/udp-swarm/ (renamed for consistency with tcp-swarm).
• Include all supporting files: Pony source, Python orchestration scripts, Python test files, READMEs.
• CI scheduling: keep the existing ponyc tcp-swarm schedule for the replacement. Add the UDP stress test on lori's current schedule.

1.8 Remove ponyc CI breakage dispatches for lori

ponyc dispatches events to lori's repo via cloudsmith-package-sychronised.yml. Since lori's code is now inside ponyc, remove the lori dispatch from this workflow.

Phase 2: ponyc — Build system (CMake)

2.1 Add SSL detection

• Add find_package(OpenSSL) or manual detection to CMake
• SSL is required — fail the build if no SSL library is found
• Detect OpenSSL version and set the appropriate -D flag:
  • OpenSSL 1.1.x → -Dopenssl_1.1.x
  • OpenSSL 3.0.x → -Dopenssl_3.0.x
  • OpenSSL 4.0.x → -Dopenssl_4.0.x
  • LibreSSL → -Dlibressl

2.2 Pass SSL flag to ponyc invocations

Every script that invokes ponyc to compile code touching packages/net/ needs the SSL -D flag, or _ssl_init.pony will compile_error. Specifically:

• cmake/RunStdlibTest.cmake — stdlib test compilation
• cmake/RunExamples.cmake — example compilation
• Stress test Python orchestrators (orchestrate_tcp.py, orchestrate_udp.py) — ponyc invocation for stress test binaries

The SSL version detected in 2.1 must flow through to all of these. Document the flag in BUILD.md.

2.3 CI

The SSL flag must be passed in all CI test and example build steps.

Phase 3: ponyc — Examples

3.1 Delete old network examples

Delete the three old-net examples — each has a lori equivalent coming over in 3.2:

• examples/net/ (ping/pong TCP) → replaced by infinite-ping-pong
• examples/echo/ (echo server) → replaced by echo-server
• examples/under_pressure/ (backpressure) → replaced by backpressure

3.2 Bring over all 19 lori examples

All lori examples come over, adapted for stdlib (change use "lori" to use "net", etc.):

backpressure, connection-timeout, echo-server, framed-protocol, idle-timeout, infinite-ping-pong, ip-version, net-ssl-echo-server, net-ssl-infinite-ping-pong, notifier-echo-server, notifier-ping-pong, notifier-udp-echo-server, read-buffer-size, send-completion, socket-options, starttls-ping-pong, timer, udp-echo-server, yield-read

Each example has its file-level docstring, follows the Listener/Server/Client actor structure, and uses a unique port. Update examples/README.md.

3.3 Update PonyCheck async TCP property example

examples/pony_check/async_tcp_property.pony uses old net API — rewrite for new API.

3.4 Example CMake integration

Examples using SSL need the SSL -D flag during build. Update CMakeLists.txt for examples accordingly.

Phase 4: ponyc — Documentation

4.1 Update ponyc README

Note that the net package requires an SSL library. Document how to pass the SSL flag when building.

4.2 Update BUILD.md

Document the SSL detection in CMake. Explain how to specify SSL version if manual override is needed.

4.3 Release note and label

The PR gets a changelog - changed label. Write a release note covering: what changed, why, how to migrate from old net, how to migrate from lori, how to migrate from ponylang/ssl. This is a breaking change — all code using use "net" must be updated.

4.4 Carry over AGENTS.md

Copy lori's AGENTS.md to packages/net/AGENTS.md as a standalone file (not @-included from ponyc's top-level CLAUDE.md). Update lori→net references and convert bare #NNN issue/PR/discussion references to full URLs (e.g., Discussion #219 → https://github.com/ponylang/lori/discussions/219) so they resolve correctly from the ponyc repo. This scopes the architectural documentation (connection lifecycle, state machine, traps, platform differences, conventions) to load only when working on net package code.

Phase 5: Downstream libraries (after ponyc release)

Each library that depends on lori needs a PR to switch to stdlib net. These can be done in parallel after a ponyc release containing the new net.

For each: remove lori from corral.json, change use "lori" to use "net", verify the types match (they should — same names moving into stdlib).

1. ponylang/postgres — depends on lori AND ponylang/ssl. Remove lori dependency, remove ssl net dependency, switch to stdlib net.
2. ponylang/stallion — depends on lori. Remove, switch to stdlib net.
3. ponylang/courier — depends on lori. Remove, switch to stdlib net.
4. ponylang/mare — depends on lori AND ponylang/ssl. Remove lori dependency, remove ssl net dependency, switch to stdlib net.
5. ponylang/redis — depends on lori. Remove, switch to stdlib net.

Other consumers

6. ponylang/pony-tutorial — docs/object-capabilities/derived-authority.md and its three code samples use old-net types (TCPConnectionNotify, TCPConnection). Rewrite to actor-trait pattern. Auth hierarchy discussion stays valid.
7. ponylang/pony-patterns — four files reference old net:
   • docs/resource-management/disposable-actor.md — two full code examples with TCPListenNotify, TCPListener, TCPConnectionNotify, TCPConnection. Needs full rewrite.
   • docs/testing/notifier-interactions.md — prose mention of UDPNotify/TCPNotify.
   • docs/code-sharing/embed-and-delegate.md — references lori as external library, update to "stdlib net".
   • docs/async/batch-and-yield.md — one sentence about TCPConnection.received, update to on_received.

Phase 6: Website updates

Update package descriptions for mare, stallion, redis in docs/use/packages.md if they mention lori as a dependency.

Phase 7: Remove net subpackage from ponylang/ssl

ponylang/ssl's net subpackage wraps the old stdlib net with SSL. Since SSL is now built into the new stdlib net, this subpackage is both broken (old API gone) and redundant. The rest of ponylang/ssl (crypto wrappers) stays.

1. Remove the ssl/net subpackage from ponylang/ssl
2. Update ponylang/ssl README to note that networking SSL is now in stdlib net
3. Update ponylang/ssl's tests/examples if they reference the removed subpackage

Phase 8: Archive ponylang/lori

1. Transfer open issues to ponyc:
   • LLVM compiler abort for FFI call to pony_alloc. #388 (Multicast convenience methods)
   • Only define snprintf for versions older than VS2015 #389 (Connected UDP mode)
2. Update README:
   • Note that lori is now part of ponyc's stdlib as the net package. leave "what it was" and just say it graduated to the standard library.
3. Archive the repo

Phase 9: Website cleanup

After lori is archived:

• docs/use/packages.md — remove lori entry
• docs/contribute/ci/triggered-jobs.md — remove lori breakage CI job references
• docs/contribute/ci/scheduled-jobs.md — remove lori stress test schedule
• docs/contribute/labels.md — remove lori as example code repo

Existing blog posts (pony-networking-take-two, LWIP posts) are historical records — leave as-is.

Phase 10: Rework ponylang/ssl into ponylang/crypto

After all the above, ponylang/ssl contains only crypto functionality — the networking SSL parts have been removed (Phase 7) and replaced by stdlib net. Rework the repo into ponylang/crypto:

1. Create ponylang/crypto repo
2. Move the crypto code from ponylang/ssl
3. Update all downstream consumers (postgres, mare, ponyup, hobby, action-testing) to depend on ponylang/crypto instead of ponylang/ssl
4. Update ponylang/ssl README to redirect to ponylang/crypto
5. Archive ponylang/ssl

Phase 11: Blog post

Write a blog post covering what changed and why, how to migrate from old net, how to migrate from lori, how to migrate from ponylang/ssl's net subpackage.

[SeanTAllen]

Phase 1 to 4 have been merged to main. Phases 5 and 6 are queued to merge on their relevant schedules.

[SeanTAllen]

phase 7 is prepped and ready to go.

[SeanTAllen]

phase 8 issue transfering is done

[SeanTAllen]

phases 5, 6, 7 are done.

[SeanTAllen]

phase 9 is done

[SeanTAllen]

phase 8 is done.

that leaves 10 and 11.