diff --git a/docs/ecosystem-open-items.md b/docs/ecosystem-open-items.md new file mode 100644 index 0000000..9fadae5 --- /dev/null +++ b/docs/ecosystem-open-items.md @@ -0,0 +1,192 @@ +# Ecosystem open items + +Parking lot for cross-repo design work that's been agreed on +or promised but not yet done. Lives in `fpc-msgbase/docs/` +because this repo is the anchor the rest of the ecosystem +depends on; pick up from here when you need something to +work on. + +Each entry: **what**, **why**, **where the prior context is**, +and **next step** so anyone reading can pick it up without a +full session replay. + +--- + +## Family-table auto-sync across sibling READMEs + +**What.** Every library README carries a `## Family` table listing +every shipped sibling with its pinned tag. With 9+ libraries, +any single release bumps all 9+ tables. Drift is inevitable. + +**Why it matters.** Consumer-facing source of truth for "what's the +current pin matrix." If it goes stale, downstream integrators +get wrong versions. The manual-every-release cost doesn't scale. + +**Prior context.** Flagged 2026-04-23 after Message 56 landed. +Script-based refresh + central doc discussed in chat. + +**Next step.** Two-part fix: +1. Move the canonical Family table to one file + (`fpc-msgbase/docs/family.md` or a new tiny `fpc-ecosystem` + repo). +2. Write a script (`scripts/refresh-family.sh` in the canonical + repo) that walks a hardcoded sibling list, does + `git ls-remote --tags ssh://git@kjgr.io:2222/kenjreno/.git` + per sibling, extracts the latest annotated tag, and rewrites + the table between `` / `` + markers in any README. Each sibling's README either links + to the central table OR has the script-refreshed block. + +Either approach reduces the maintenance tax from "edit 9 +READMEs carefully" to "run one script, commit once." + +--- + +## fpc-ftpmail library — proposed, awaiting session pickup + +**What.** FTP/SFTP server library that serves a file-tree via an +`IFileTreeProvider` interface. Provider implementations come +from consumers: fpc-ftn-transport ships `TFileboxTreeProvider`, +fpc-bbs ships `TFileAreaTreeProvider`, composites possible. + +**Why it matters.** Fills a deferred Family-table slot. Enables +"user sftps in and picks up their netmail" via fpc-ftn-transport +0.6.0's filebox queue; enables "user sftps in and browses BBS +file areas" via fpc-bbs. Also absorbs the port of +`xenia-mailer/ftpmail.c` (the client half). + +**Prior context.** Full design sketch in MSGS Message 38 +(unit layout, interface shape, portability split: +FTP builds everywhere, SFTP needs libssh so +`{$IFNDEF GO32V2}{$IFNDEF OS2}` guarded). + +**Next step.** Scaffold `fpc-ftpmail` repo on kjgr.io, drop +the ecosystem-standard template (build.sh, run_tests.sh, +README, CHANGELOG, docs/architecture.md with memory-ownership +section, version unit). `fm.provider.pas` declares +`IFileTreeProvider`. `fm.server.ftp` is the first +implementation target; SFTP slots in second. No blocker from +existing libs -- fpc-ftn-transport's `TFileboxQueue` already +ready to satisfy the provider contract. + +--- + +## Ecosystem-wide naming conventions doc + +**What.** Single authoritative doc codifying the +`..[.].pas` shape, the prefix +registry (`mb.` `tt.` `bp.` `cm.` `cr.` `log.` `bbs.` `fx.` +`em.` `fm.`), required `{$mode objfpc}{$H+}` + common +`{$modeswitch advancedrecords}`, and the "leaf unit" pattern +(`mb.address`, `log.types`, `cr.types`). + +**Why it matters.** Today each sibling declares its own prefix +in its own README. No central place says *how the registry +is decided* or *what a new library should do* when picking a +prefix. `fpc-crypto/docs/architecture.md` has the most +explicit statement cross-referencing other libraries. + +**Prior context.** Raised 2026-04-23; surveyed per-library +docs (each has a `## Naming` section). + +**Next step.** Write `fpc-msgbase/docs/ecosystem-naming.md` +~100 lines: + +- Prefix registry table (prefix, library, convention) +- `....pas` shape with examples +- Required `{$mode}` directives +- Leaf-unit pattern (pure types, zero deps beyond `SysUtils`) +- Re-export / transitive visibility gotcha (FPC does NOT + propagate record-field access through `uses` re-export -- + learned during the `mb.address` split, landed in 0.7.0) + +Then each sibling README's `## Naming` section becomes a +one-line link instead of per-lib restatement. + +--- + +## `INodelistLookup` interface — promised, not stubbed + +**What.** `fpc-ftn-transport/docs/scope.md` (landed 2026-04-21) +commits to a consumer-supplied `INodelistLookup` interface +instead of a library-shipped nodelist reader. Interface shape +sketched in chat (single `Resolve(Addr): TNodelistEntry`) +but no unit exists yet. + +**Why it matters.** First real consumer (a tosser that wants +"tell me this address's BinkP host / phone / flags") will need +somewhere to call into. Delaying until a consumer asks risks +that consumer picking a different shape and diverging. + +**Prior context.** scope.md row; chat sketch around 2026-04-21. + +**Next step.** When the first consumer surfaces, declare +`INodelistLookup` in `tt.nodelist.pas` (or consumer-picks-unit) +with the record shape from the chat sketch. No implementation +needed -- consumers supply. Ship as part of whatever +fpc-ftn-transport minor release picks it up. + +--- + +## Real-socket disconnect test for BSO queue + +**What.** Integration test that runs a BSO queue operation +against a real filesystem + real socket where the socket is +killed mid-operation, verifies no 100%-CPU spin or stuck +session. + +**Why it matters.** fpc-binkp's cff2997 bug (Recv returning +-1 on peer close, loop spinning the dead socket forever) +escaped in-memory unit tests because `TByteQueue.Close` +takes a different branch than a real OS socket. Same class +of bug could bite fpc-ftn-transport's BSO queue -- +BreakStaleBusy / AcquireBusy rely on filesystem races that +in-memory fakes elide. + +**Prior context.** Commitment in MSGS Message 37 +(2026-04-22): "Will add an equivalent real-socket disconnect +test to fpc-ftn-transport's BSO queue coverage the next time +that area gets touched." + +**Next step.** Next time any BSO code gets edited, add +`tests/test_bso_real_disconnect.pas` to the suite. Two +processes, real lock dir, one kills the lock-holding process +mid-busy; the other must recover via BreakStaleBusy without +spinning. + +--- + +## fpc-filexfer + fpc-emsi interface unification (IFXTransport vs IBPTransport) + +**What.** `IFXTransport` = `IBPTransport` + `Flush`. `IComTransport` +is the third. A consumer that wants a single TCP-socket wrapper +to serve all four libraries (binkp / comet / filexfer / emsi) +today has to implement three separate interfaces with overlapping +method sets. + +**Why it matters.** Consumer duplication; drift risk if the +overlapping methods diverge in signature/semantics over time. + +**Prior context.** MSGS Message 44 (Comet maintainer's +clarification on interface names) noted a single +`TInterfacedObject` can implement all three via multi-interface +inheritance. + +**Next step.** Long-term: factor a shared `ITransportBase` +into a tiny `fpc-transport-core` library (like how `fpc-log` +factors TLogProc, or `fpc-crypto` factors MD5). Consumers +implement once, each lib adds its own extensions. Not urgent +-- two consumers today is the same two-consumer threshold +crypto crossed before fpc-crypto landed. Revisit when a +third transport-consuming library shows up or when +signature drift starts hurting. + +--- + +## When to resurface these + +Any of these is a reasonable "what's next" when you want a +non-urgent piece of work. Family-table auto-sync has the +highest day-to-day payoff; fpc-ftpmail unblocks the most +user-visible feature (netmail over SFTP). Pick what fits +the session.