[shepherd] branch wip-goblinsify updated: Update design doc.

[Juliana Sims]

This is an automated email from the git hooks/post-receive script.

juli pushed a commit to branch wip-goblinsify
in repository shepherd.

The following commit(s) were added to refs/heads/wip-goblinsify by this push:
     new eef3774  Update design doc.
eef3774 is described below

commit eef377403d096bcf449efbe3591fb0c6dfc5c842
Author: Juliana Sims <juli@incana.org>
AuthorDate: Fri Oct 18 15:22:28 2024 -0400

    Update design doc.
    
    * goblins-port-design-doc.org: Cleanup typos, add concurrency section, 
clarify
    some explanations.
---
 goblins-port-design-doc.org | 120 +++++++++++++++++++++++++++++++++-----------
 1 file changed, 90 insertions(+), 30 deletions(-)

diff --git a/goblins-port-design-doc.org b/goblins-port-design-doc.org
index 4d6f884..5c7327b 100644
--- a/goblins-port-design-doc.org
+++ b/goblins-port-design-doc.org
@@ -1,6 +1,6 @@
 * Overview
 
-This purpose of this project is to rewrite 
[[https://www.gnu.org/software/shepherd/][the GNU Shepherd]] using the 
[[https://spritely.institute/goblins/][Spritely
+The purpose of this project is to rewrite 
[[https://www.gnu.org/software/shepherd/][the GNU Shepherd]] using the 
[[https://spritely.institute/goblins/][Spritely
 Goblins]] object-capability security (ocaps) library.  This rewrite is possible
 because both Goblins and the Shepherd are written in the 
[[https://www.gnu.org/software/guile/][Guile]] dialect of the
 [[https://www.scheme.org/][Scheme]] programming language.  The upshot of this 
rewrite will be both increased
@@ -42,6 +42,58 @@ final caveat, this document does not endeavor to discuss 
every change that will
 be part of this port but rather focuses on the major components which will see
 significant change.
 
+** Concurrency
+
+/Concurrency/ refers to the conceptual execution of code in separate contexts.
+This differs from /parallelism/ which refers to the simultaneous execution of
+two computations.  The two can and sometimes do go together, but are not
+necessarily the same.  As discussed below, the Shepherd intentionally avoids
+parallelism in its own code.
+
+As referenced above, both Goblins and the Shepherd use Fibers, a library
+implementing the communicating sequential processes (CSP) paradigm, to provide
+concurrency primitives.  As Fibers implements it, this means creating fibers
+(delimited continuations) which communicate through channels which send
+messages between fibers.  When a fiber sends or receives a messages, its
+computation is suspended until another fiber is ready to receive or send the
+message.  At this point the fibers are resumed to "rendezvous," exchange their
+message, and continue computation.
+
+*** Current Status
+
+Because Fibers is fundamentally a set of convenient but primitive abstractions
+over underling OS functionality, the Shepherd is responsible for creating and
+managing fibers when and as it needs them.  Typically, communication between
+actors happens in messages sent through channels which are frequently passed
+back and forth, sometimes in messages sent over channels.
+
+Importantly, the Shepherd does not enable parallelism in its core fiber.
+Fibers builds parallelism on top of POSIX threads, which are incompatible with
+the ~fork~ syscall.  Because the Shepherd is charged with spawning and
+monitoring processes, it needs to be able to safely call ~fork~.
+
+*** Rewrite Goals
+
+Goblins manages most concurrency complexity for library users.  The primary
+abstraction exposed to users is the vat.  The Goblins Shepherd will use a
+relatively small number of vats and spawn specific actors in different vats to
+avoid deadlocks.  In particular, the vats we foresee needing are for the main
+Shepherd dæmon REPL, for the service registry, for the process monitor, and
+possibly for ~herd~ instances.
+
+It's worth noting that Guile Goblins does not currently support automatically
+stopping vats when they are no longer needed which means that if we wish to
+reclaim the resources used by a vat, we need to stop it ourselves.  However,
+with the exception of the possible ~herd~ vats, vats will likely run for the
+lifetime of the dæmon itself and so not need to be stopped and collected in
+program code.  In the case of ~herd~ vats, execution of a given command will
+be synchronous which should allow traditional ~dynamic-wind~ to handle
+cleanup.
+
+Goblins does not disable parallelism in its default scheduler so it may be
+necessary to write a custom scheduler for the Shepherd's main process.
+Fortunately, Goblins allows constructing vats with different schedulers.
+
 ** Service and Service Controller Actor
 
 *** Current Status
@@ -78,14 +130,14 @@ responsible for starting new services during registration.
 
 *** Rewrite Goals
 
-The core service registry will be ported relatively directly.  The main
-difference is that the registry will need to pass a facet of itself to service
-actors so that they may communicate their current state.  Similarly, support 
for
-remote intercommunication between Shepherd dæmons will require the creation of 
a
-service registry facet which only exposes certain service actors.  This same
-facet can be used locally to allow multiple users to share the same Shepherd
-dæmon.  This will likely involve the creation of new methods for handshaking
-between registries and, by extension, Shepherd dæmons.
+The core service registry will be ported relatively directly.  Rather than
+alter the core service registry, support for remote intercommunication between
+Shepherd dæmons will rely on the creation of a service registry facet which
+only exposes certain service actors.  This same facet can be used locally to
+allow multiple users to share the same Shepherd dæmon.  This will likely
+involve the creation of new methods for handshaking between registries and, by
+extension, Shepherd dæmons.  These extensions will only be implemented as
+necessary.
 
 The exact interrelation between local and remote registry remains to be
 explored.  However, the general idea is that a local registry will check if it
@@ -97,13 +149,14 @@ registry to learn what capabilities it provides.
 One new mechanism of interest may be the ability to register remote services.
 This could take two forms: placing a reference to an extant remote service in
 the local registry, and asking a local registry to register and launch a 
service
-on a remote host.  This exact API remains to be explored based on need.
+on a remote host.  This exact API remains to be explored based on need and may
+not be implemented at all.
 
 *** Open Questions
 
 The service registry is the central point of control at the time when
 dependencies are resolved.  It is unclear how remote versus local dependencies
-should be resolved.  If a service asks for ~'sql~, for example, there are
+should be resolved.  If a service asks for ~'sql~, for example, and there are
 multiple services known to a registry to provide ~'sql~, which one should be
 chosen?
 
@@ -130,11 +183,10 @@ terminates.
 
 *** Rewrite Goals
 
-Starting services will look very similar to how they work now, with the primary
-changes being around spawning Goblins actors as opposed to Shepherd actors.  
The
-process monitor will become a Goblins actor.  ~waiters~ can be replaced using
-the pubsub idiom, and it may be possible to express most of the process monitor
-in terms of pubsub.
+Starting services will look very similar to how they work now, with the
+primary changes being around spawning Goblins actors as opposed to Shepherd
+actors.  The process monitor will become a Goblins actor which is essentially
+a specialized implementation of the pubsub pattern.
 
 ** Commandline Interface
 
@@ -172,7 +224,7 @@ they would be even without the transactionality.  Only the 
debugger causes
 Object-capability security inverts many ACL concepts of control flow and
 authority as part of its security mechanisms.  This can lead to unfamiliar code
 and imitate the situation known as "callback hell."  To mitigate this issue, 
the
-~let-on~ macro exists, allowing tradition-looking Scheme code that expands to
+~let-on~ macro exists, allowing traditional-looking Scheme code that expands to
 ocaps-style ~on~.
 
 * Open Questions
@@ -182,11 +234,13 @@ further consideration.
 
 ** Inbox Overflow
 
-Goblins message-passing could theoretically result in a situation where a given
-vat is unable to accept more messages, but remote actors don't know this -- are
-maliciously take advantage of this as part of an attack.  While this situation
-has never been encountered in practice, it is a subject of active consideration
-within Spritely and the broader [[https://ocapn.org/][OCapN]] community.
+Goblins message-passing over the network could theoretically result in a
+situation where a given vat is unable to accept more messages, but remote
+actors don't know this -- or maliciously take advantage of this as part of an
+attack.  While this situation has never been encountered in practice, it is a
+subject of active consideration within Spritely and the broader 
[[https://ocapn.org/][OCapN]]
+community.  It is beyond the design scope of the current project, but we
+mention it to clarify that is something we are aware of.
 
 * Ocaps Appendix
 
@@ -227,7 +281,7 @@ may then accept arguments as would any regular lambda.
 
 ** Asynchronous Message Passing and Promises
 
-Unlike the actor model, Goblins provide mechanisms for both 
[[https://spritely.institute/files/docs/guile-goblins/0.14.0/Synchronous-calls.html][synchronous
 message
+Unlike the actor model, Goblins provides mechanisms for both 
[[https://spritely.institute/files/docs/guile-goblins/0.14.0/Synchronous-calls.html][synchronous
 message
 passing]] represented by the ~$~ operator, which acts like normal function
 invocation in that it executes immediately and returns a normal value; and
 
[[https://spritely.institute/files/docs/guile-goblins/0.14.0/Asynchronous-calls.html][asynchronous
 message passing]] represented by the ~<-~, which returns a promise
@@ -251,12 +305,12 @@ or thread -- concurrency is achieved by communication 
between vats.
 
 Unlike JavaScript, ocaps has a concept of "promise pipelining" which allows
 local code to specify messages it would like to send in response to the
-resolution of a promise alongside the initial message.  This allows the 
creation
-of several idioms to cut down on so-called "callback hell," all built upon 
~on~.
-The most common central of these in Goblins is 
[[https://spritely.institute/files/docs/guile-goblins/0.14.0/Let_002dOn.html][~let-on~]].
  This macro allows
-users to write code that looks like regular Scheme ~let~ statements but which
-expands to use ~on~.  Relatedly, a variety of 
[[https://spritely.institute/files/docs/guile-goblins/0.14.0/Joiners.html][joiner]]
 macros facilitate promise
-pipelining across multiple actors.
+resolution of a promise alongside the initial message.  This allows the
+creation of several idioms to cut down on so-called "callback hell," all built
+upon ~on~.  The most common of these in Goblins is 
[[https://spritely.institute/files/docs/guile-goblins/0.14.0/Let_002dOn.html][~let-on~]].
  This macro
+allows users to write code that looks like regular Scheme ~let~ statements but
+which expands to use ~on~.  Relatedly, a variety of 
[[https://spritely.institute/files/docs/guile-goblins/0.14.0/Joiners.html][joiner]]
 macros facilitate
+promise pipelining across multiple actors.
 
 ** Cells
 
@@ -268,4 +322,10 @@ message, they either return or update their value.
 
 Proxies are actors which represent other actors.  Remote actors, for example,
 are represented by local proxies.  
[[https://spritely.institute/files/docs/guile-goblins/0.14.0/Facet.html][Facets]]
 are special proxies which limit which
-messages are passed to the proxied actor.
+messages may be passed to the proxied actor.
+
+** Pubsub
+
+The pubsub pattern is a convenient way to coordinate and synchronize between
+multiple disparate actors.  A pubsub actor holds capabilities on "subscribers"
+to which it can send a message simultaneously.