Provide the three operations openkal 0.8 adds to openkal.process

ADDING TO AN EXISTING INTERFACE OBLIGES EVERY IMPLEMENTATION OF IT, and adding a
new interface obliges none. Clause 6.1 makes an interface an implementation does
not provide absent at the link and not a deviation; it makes one provided IN PART
a deviation. The five interfaces version 0.8 adds are therefore free for a
backend to decline, and the three names added to openkal.process are not.

The specification's own surface checker is what said so, before anything else
noticed:

    openkal.process is provided in part: 3 of 8 names are not exported --
        kal_process_channel
        kal_process_channel_close
        kal_process_spawn_with

kal_process_channel is pipe2 with O_CLOEXEC on both ends. The far end is placed
deliberately by the spawn that receives it; an end that leaked into every other
started program would keep the channel open after the intended reader had closed
it, and the writer would never see the end of input.

The streams are bare descriptors rather than packed handles, because
openkal.stream's transfer operations take what the environment takes.
kal_fs_stream reports a file's stream the same way and for the same reason.

kal_process_channel_close refuses descriptors below three. They are the standard
streams, which are borrowed; closing one through this operation would take a
stream away from the whole program.

kal_process_spawn_with places the grants as descriptors three and upward, which
is where kal_fs_preopen reads them back from. The inverse relationship clause
7.11 describes is between those two operations, which is why they must agree
about the numbering rather than each choosing one.

⚠️ dup3 refuses a duplication onto itself, and the ordinary case reaches that
whenever a granted directory already occupies the number it is destined for.
Refusing is correct of dup3 --- the flags could not be applied --- and here it
means the descriptor is already in place, so it is left alone rather than treated
as a failure.

The grants are resolved before the fork. A failure after it would leave a child
to be reaped and a caller holding an error it cannot act upon.

  surface      exported surface is complete and conforms: 90 names
  mcpp test    7 passed, 0 failed
  observed     a channel carries bytes, and closing the far end is observed as
               end of input on the near one

Author: speak-agent

src/process.cpp

@@ -101,6 +101,122 @@ int kal_process_spawn(kal_dir base,
     return kal_ok;
 }
 
+// A channel: a pair of streams of which one end is meant to cross a spawn.
+//
+// WHY THIS IS A KERNEL FACILITY AND kal::kit's CHANNEL IS NOT. A started program
+// is another address space, so a pointer into this one is not something it can
+// be handed. The pair must therefore be made of whatever the environment carries
+// across a spawn, which here is a descriptor.
+//
+// BOTH ENDS ARE OWNED AND BOTH ARE RELEASED THROUGH kal_process_channel_close.
+// A parent that does not release the far end after the spawn never observes the
+// end of input on its own --- the classic deadlock of this arrangement, and the
+// reason the release is declared beside the operation rather than left to
+// openkal.stream, which has no release at all.
+int kal_process_channel(kal_stream* mine, kal_stream* theirs) {
+    if (mine == nullptr || theirs == nullptr) return kal_err_invalid;
+
+    int fds[2] = { -1, -1 };
+    // O_CLOEXEC on both. The far end is placed deliberately, by the spawn that
+    // receives it; an end that leaked into every other started program would
+    // keep the channel open after the intended reader had closed it, and the
+    // writer would then never see the end of input.
+    const okl_long r = okl::sys(okl::nr_pipe2, reinterpret_cast<okl_long>(fds),
+                                okl::o_cloexec);
+    if (okl::failed(r)) return okl::translate(r);
+
+    // THE STREAMS ARE BARE DESCRIPTORS AND NOT PACKED HANDLES, because
+    // openkal.stream's transfer operations take what the environment takes.
+    // kal_fs_stream reports a file's stream the same way and for the same
+    // reason.
+    *mine   = kal_stream{ static_cast<kal_uintptr>(fds[0]) };   // the reading end
+    *theirs = kal_stream{ static_cast<kal_uintptr>(fds[1]) };   // the writing end
+    return kal_ok;
+}
+
+void kal_process_channel_close(kal_stream s) {
+    // A bare descriptor, so there is no generation to retire. The standard
+    // streams are borrowed and are numbered 0, 1 and 2; closing one of those
+    // through this operation would take a stream away from the whole program,
+    // so they are refused rather than closed.
+    const okl_long fd = static_cast<okl_long>(s.h);
+    if (fd < 3) return;
+    okl::sys(okl::nr_close, fd);
+}
+
+// Starting a program that receives exactly the directories named.
+//
+// THE GRANTS ARE PLACED AS DESCRIPTORS THREE AND UPWARD, which is the
+// arrangement kal_fs_preopen reads them back from. The inverse relationship
+// clause 7.11 describes is therefore between this operation and that one, and
+// it is why the two must agree about the numbering rather than each choosing.
+//
+// A COUNT OF ZERO IS NOT THE SAME AS kal_process_spawn. It starts a program with
+// no preopens at all, which is the whole reason a caller reaches for this
+// operation, so the loop below is not skipped when there is nothing to place ---
+// what matters is that nothing else is inherited either.
+int kal_process_spawn_with(kal_dir base,
+                           const char* path, kal_uintptr path_len,
+                           const char** argv, const kal_uintptr* argv_lens, kal_uintptr argc,
+                           const char** envp, const kal_uintptr* envp_lens, kal_uintptr envc,
+                           const kal_spawn_streams* streams,
+                           const kal_preopen* grants, kal_uintptr grant_count,
+                           kal_process* out) {
+    const int b = okl::unpack(base.h);
+    if (b < 0 || out == nullptr) return kal_err_invalid;
+    if (!okl::acceptable(path, path_len)) return kal_err_invalid;
+    if (grant_count > 0 && grants == nullptr) return kal_err_invalid;
+    okl::terminated p(path, path_len);
+    if (!p.ok) return kal_err_invalid;
+
+    vector args, envs;
+    if (!args.build(argv, argv_lens, argc)) return kal_err_no_memory;
+    if (!envs.build(envp, envp_lens, envc)) return kal_err_no_memory;
+
+    // Resolved before the fork, because a failure after it would leave a child
+    // to be reaped and a caller with an error it cannot act upon.
+    constexpr kal_uintptr max_grants = 16;
+    if (grant_count > max_grants) return kal_err_invalid;
+    int granted[max_grants];
+    for (kal_uintptr i = 0; i < grant_count; ++i) {
+        granted[i] = okl::unpack(grants[i].dir.h);
+        if (granted[i] < 0) return kal_err_invalid;
+    }
+
+    const okl_long in = streams ? static_cast<okl_long>(streams->in)  : 0;
+    const okl_long ou = streams ? static_cast<okl_long>(streams->out) : 0;
+    const okl_long er = streams ? static_cast<okl_long>(streams->err) : 0;
+
+    const okl_long child = okl::sys(okl::nr_clone, 17 /* SIGCHLD */, 0, 0, 0, 0);
+    if (okl::failed(child)) return okl::translate(child);
+
+    if (child == 0) {
+        if (in != 0) okl::sys(okl::nr_dup3, in, 0, 0);
+        if (ou != 0) okl::sys(okl::nr_dup3, ou, 1, 0);
+        if (er != 0) okl::sys(okl::nr_dup3, er, 2, 0);
+
+        // ⚠️ dup3 REFUSES A DUPLICATION ONTO ITSELF, which the ordinary case
+        // reaches whenever a granted directory already occupies the number it
+        // is destined for. Refusing there is correct of dup3 --- the flags could
+        // not be applied --- and here it means the descriptor is already in
+        // place, so it is left alone rather than treated as a failure.
+        for (kal_uintptr i = 0; i < grant_count; ++i) {
+            const okl_long want = static_cast<okl_long>(3 + i);
+            if (granted[i] != want)
+                okl::sys(okl::nr_dup3, granted[i], want, 0);
+        }
+
+        okl::sys(okl::nr_execveat, b, reinterpret_cast<okl_long>(p.buf),
+                 reinterpret_cast<okl_long>(args.slots),
+                 reinterpret_cast<okl_long>(envs.slots), 0);
+        okl::sys(okl::nr_exit_group, 127);
+        for (;;) { }
+    }
+
+    *out = kal_process{ static_cast<kal_uintptr>(child) };
+    return kal_ok;
+}
+
 int kal_process_wait(kal_process h, int* status, int* terminated_by_environment) {
     if (h.h == 0) return kal_err_invalid;
     int st = 0;
@@ -137,6 +253,7 @@ void kal_process_close(kal_process) { }
 
 const kal_uintptr kal_process_props =
     KAL_PROCESS_PROP_TERMINATE | KAL_PROCESS_PROP_STREAM_PASSING
-  | KAL_PROCESS_PROP_EXIT_STATUS;
+  | KAL_PROCESS_PROP_EXIT_STATUS
+  | KAL_PROCESS_PROP_CHANNEL | KAL_PROCESS_PROP_GRANT_DIR;
 
 }

src/sys.h

@@ -102,7 +102,7 @@ enum : okl_long {
     nr_socket = 41, nr_connect = 42, nr_accept = 43, nr_sendto = 44,
     nr_recvfrom = 45, nr_shutdown = 48, nr_bind = 49, nr_listen = 50,
     nr_getsockname = 51, nr_getpeername = 52, nr_accept4 = 288,
-    nr_setsockopt = 54,
+    nr_setsockopt = 54, nr_pipe2 = 293,
     // openkal.timeout. ppoll and not poll: the bound is stated in nanoseconds
     // and poll takes milliseconds, so poll could not express a bound finer than
     // the granularity this implementation reports.
@@ -185,7 +185,7 @@ enum : okl_long {
     nr_socket = 198, nr_connect = 203, nr_accept = 202, nr_sendto = 206,
     nr_recvfrom = 207, nr_shutdown = 210, nr_bind = 200, nr_listen = 201,
     nr_getsockname = 204, nr_getpeername = 205, nr_accept4 = 242,
-    nr_setsockopt = 208,
+    nr_setsockopt = 208, nr_pipe2 = 59,
     // openkal.timeout. This architecture has no `poll' at all, only `ppoll',
     // which is a second reason the bound is expressed through the latter.
     nr_ppoll = 73,

tests/conformance_v08.cpp

@@ -212,9 +212,53 @@ void timeout_section() {
     check(w.e == kal_ok, "a bounded transfer of zero bytes succeeds");
 }
 
+// The three operations openkal 0.8 adds to openkal.process.
+//
+// ADDING TO AN EXISTING INTERFACE OBLIGES EVERY IMPLEMENTATION OF IT, which is
+// not true of adding a new interface: clause 6.1 makes a new one optional and
+// clause 6.1 makes an incomplete one a deviation. The surface checker caught the
+// omission here before anything else did, and these observations are what says
+// the names do something rather than merely existing.
+void process_additions_section() {
+    // A channel carries bytes from one end to the other. Both ends are owned and
+    // both are released through kal_process_channel_close.
+    kal_stream mine{}, theirs{};
+    const int rc = kal_process_channel(&mine, &theirs);
+    check(rc == kal_ok, "a channel is created");
+    if (rc != kal_ok) return;
+
+    const char msg[] = "through the channel";
+    const auto w = kal_stream_write(theirs, msg, sizeof msg - 1);
+    check(w.e == kal_ok && w.n == sizeof msg - 1,
+          "the far end of a channel accepts bytes");
+
+    char buf[64] = {};
+    const auto r = kal_stream_read(mine, buf, sizeof buf);
+    check(r.e == kal_ok && r.n == sizeof msg - 1 &&
+              std::memcmp(buf, msg, sizeof msg - 1) == 0,
+          "the near end reads what the far end wrote");
+
+    // THE END OF INPUT IS WHAT THE RELEASE IS FOR. A parent that does not close
+    // the far end after a spawn never observes it, which is the deadlock this
+    // pair invites and the reason the release is declared beside the operation.
+    kal_process_channel_close(theirs);
+    const auto eof = kal_stream_read(mine, buf, sizeof buf);
+    check(eof.e == kal_ok && eof.n == 0,
+          "closing the far end is observed as end of input on the near one");
+    kal_process_channel_close(mine);
+
+    // The property word claims both additions, so both must be answered. Named
+    // through the module, because a macro does not cross a module boundary.
+    check(kal::process::has(kal::process::channel),
+          "the property word claims the channel it just provided");
+    check(kal::process::has(kal::process::grant_dir),
+          "the property word claims the directory grant");
+}
+
 }  // namespace
 
 int main() {
+    process_additions_section();
     terminal_section();
     net_section();
     datagram_section();