docs: add ecosystem-open-items parking lot
Single place to track 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 sibling. Entries: - Family-table auto-sync (reduce 9-README maintenance tax) - fpc-ftpmail library (proposed, awaiting session pickup) - Ecosystem-wide naming conventions doc - INodelistLookup interface (promised in scope.md, not stubbed) - Real-socket disconnect test for BSO queue (Message 37) - fpc-filexfer/fpc-emsi interface unification (long-term) Each entry carries what / why / prior-context / next-step so anyone reading can pick it up without a full chat replay.
This commit is contained in:
192
docs/ecosystem-open-items.md
Normal file
192
docs/ecosystem-open-items.md
Normal file
@@ -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/<name>.git`
|
||||
per sibling, extracts the latest annotated tag, and rewrites
|
||||
the table between `<!-- FAMILY-BEGIN -->` / `<!-- FAMILY-END -->`
|
||||
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
|
||||
`<prefix>.<category>.<name>[.<sub>].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)
|
||||
- `<prefix>.<category>.<name>.<sub>.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.
|
||||
Reference in New Issue
Block a user