Early in their career the author learned from Paula Hawthorn ↗︎ that developers will never stop coding and refactoring if left to their own devices because they can always find things that could be improved and testing will always find more bugs. So there comes a time in the development lifecycle that engineers have to be told to simply stop working on the code and focus instead on documenting what works, what doesn't and what they will do next.
Securepub v1 Release 2401 reflects what the author was able to complete before the end of March 2024. It is a work-in-progress with missing features and known issues and those who look closely will surely find more.
First Prototype
Two prototypes were built prior to this release.
The first prototype collapsed of its own weight trying to do too much. Collaboration pages had many Elm modules per page which used gRPC requests to communicate with a serverless nodejs process. State was distributed in many places and workflows relied on a complex set of state machines. All engagements relied on a single "api user" to perform resharing operations. The design was abandoned when the author realized such any such scheme was inherently insecure.
Second Prototype
The second prototype removed the nodejs cloud layer, eliminated the "api user", eliminated gRPC, moved the permission resharing operations into a Comlink ↗︎ web worker, changed collaboration pages to use a single Elm module per page and used Effect-ts ↗︎ instead of state machines for workflows.
Progress on the second prototype improved at a steady pace after these simplifications until it came time to implement more complex queries involving multiple sources. State management complexity and "callback hells" of Userbase changeHandlers threatened to derail things. Fortunately moving to a system of sources and views implemented with effect Fibers ↗︎, PubSubs ↗︎, and Streams ↗︎ eliminated the callbacks and made things managable again.
v1.r2401
The second prototype was a loose collection of independent programs in separate directories without source control tied together with Zola. The code was moved into the r2401 repository at GitLab ↗︎ once everything stabilized. Development continued until the end of March 2024.
Lessons
Building Securepub gave the author the opportunity to learn many things about browsers, javascript apis, web workers, service workers, origins, cors, bundlers, esbuild, tsconfig, npm, static sites, etc.
Here is a summary of technologies the author found worked well and didn't work well:
short-term long-term
╭────────────────┬────────────────╮
positive │ Bulma │ Bulma │
│ Typescript │ Typescript │
│ Zod │ Zod │
│ Zola │ Zola │
│ │ │
│ Javascript │ Elm │
│ │ Effect-ts │
│ │ Userbase │
├────────────────┼────────────────┤
negative │ Elm │ Javascript │
│ Effect-ts │ │
│ Userbase │ │
╰────────────────┴────────────────╯
overall positive
Bulma ↗︎, Typescript ↗︎, Zod ↗︎ and Zola ↗︎ delivered immediate value and good experiences throughout the entire development.
long-term positive
It took a while to learn Elm ↗︎ and Effect-ts ↗︎ but they eliminated many bugs and made the application much more reliable. They are excellent technologies for the "long-haul".
Likewise Userbase ↗︎ is incredible but its gaps and limits caused the author to spend more time then they should have figuring out how to accomplish their goals with it.
long-term negative
Short bits of Javascript generally delivered value quickly but often proved fragile.
The author finally settled on a "one strike" policy: working Javascript could stay but any bits that caused errors were declared "out" and replaced or rewritten in Typescript or Elm.