In DOOR_CALL(3C) it says (emphasis mine):

The door_call() function is not a restartable system call. It returns EINTR if a signal was caught and handled by this thread. If the door invocation is not idempotent the caller should mask any signals that may be generated during a door_call() operation.

Or maybe the default door_call should say in the docs that it expects the server procedure to be idempotent, and we could have a separate door_call_nonidempotent call that masks signals to make sure that signals received by the client do not cause the server to be interrupted.

So that servers can see the identity (uid) of the invoking client.

https://keepachangelog.com/en/1.1.0/

Once #15 is done

Let's go ahead and get in front of that. We don't have very many dependencies in this crate, so it will not be hard to get them in line.

According to DOOR_RETURN(3C), door_return can actually fail and return to the calling process in certain situations:

   Upon successful completion, door_return() does not return to the calling
   process. Otherwise, door_return() returns -1 to the calling process and
   sets errno to indicate the error.

   ...

   The door_return() function fails and returns to the calling process if:

   E2BIG
             Arguments were too big for client.


   EFAULT
             The address of data_ptr or desc_ptr is invalid.


   EINVAL
             Invalid door_return() arguments were passed or a thread is
             bound to a door that no longer exists.


   EMFILE
             The client has too many open descriptors.

So! It would be neat to be able to turn this into a function that produces a Result type

Like in https://github.com/robertdfrench/portunusd/blob/trunk/illumos/src/door_h.rs#L197

Like https://github.com/oxidecomputer/rusty-doors/blob/main/macros/src/lib.rs#L23

This breaks the proc macros, so requires a coordinated fix.

This should make it easier for people to find what they want without having to dig around.

Don't add logic to anything that we don't own in this crate. The types that are defined in doors.h, etc have to be imported literally, but should only be accessed using the foreign type pattern. This will keep us from needing to have references to door_desc_t in all parts of the code.

They should own (and therefore manage) the Vec<door_desc_t> that is passed to door_Call or door_return. Creating this vector for them leads to memory leaks, I think. No new heap allocations should happen in the door_call / door_return wrappers

There are lots of tests that have one name which rely on server with a slightly different name, and rendezvous at door paths that have a third variant. All of these should be renamed something like this:

• $test_name <- integration test client
• "$test_name_test_server" <- integration test server
• "$test_name_test.door" <- rendezvous path

https://illumos.org/man/3C/door_server_create

Like https://github.com/oxidecomputer/rusty-doors/blob/main/lib/src/lib.rs#L1

Like https://github.com/oxidecomputer/rusty-doors/blob/main/lib/src/lib.rs#L77

Although this raises some problems of its own -- namely, how to ensure that clients do not cause runtime errors just because they can pass arbitrary types to a door call? The server procedure will certainly be expecting a well-defined type. Maybe something roughly along these lines would be more appropriate:

In Server

#[door]
fn greet(name: CString) -> CString {
  // construct a greeting response
}

In Client

let door = Door::open<CString, CString>("/path/to/door")?;
let greeting = door.call(CString::from("robert"))?;

That way, instead of door_call being generic (and thus seeming to compile against more or less whatever type), you have to explicitly state the types you expect when opening a file descriptor for the door client. That would at least ensure that putting the wrong variable into door.call results in a compile error. I am assuming that people will be less likely to get the type names wrong since those will come from the documentation for the server procedure.

Would be cool to be able to test PRs against an OmniOS system before merging

The errors mean different things depending on what function you just invoked. They don't all need to be in a big category, because they already are (in libc namespace). Further, each man page for each door function says what kinds of errors it can set to errno if it fails, so that list needs to be the enumeration.

The current door_call interface is sortof busted -- it doesn't handle rbuf correctly, or cleanly.

I think we need a DoorArgumentsBuffer type which has a to_door_args() method that will emit the current type. That way we still can have a single thing to own each of these buffers -- if folks don't want or need to use that, they can construct a door_args_t themselves.

If rbuf.ptr() doesn't match the storage allocated for rbuf by the DoorArgumentsBuffer, then somebody will need to deallocate the old rbuf (since it wasn't used) and munmap the new rbuf (since it was mapped into the client's address space by the kernel) once it is no longer needed.

Originally posted by @robertdfrench in #6 (comment)

This is another packed structure, so there will be some unaligned access issues. But this can be leveraged in tests to assert that door_create calls were made with the correct arguments.

Currently we use a system of trait-based server procedures, where every server procedure needs to be associated with a type, and that type needs to implement a trait called ServerProcedure. This requires consumers of this crate to cook up an empty type just to hold on to a function, which isn't terrible, but it isn't great.

Incorporating proc-macro-based server procedures will make for less boilerplate for the user, but it will require the proc-macro definition to be extended to cover file descriptors. Also, the ServerProcedure trait is aware of the lifetime of the return data, so the proc-macro will need to account for that as well (to avoid memory leaks, or at least force the developers to admit that they are leaking data).

Neither doors nor door-macros have a readme on crates.io right now:

• https://crates.io/crates/doors/0.5.0
• https://crates.io/crates/door-macros/0.1.0

Tokio seems to have the same or nearly the same README.md for both its repo and the tokio crate: https://github.com/tokio-rs/tokio

• Can that be accomplished with symlinks?
• What needs to be done about the social media preview image?

Somehow we'll need to specify what type the door data is. Something like:

doorfn!(Func, i32, {
   // data is available as a vec<i32> now
})

https://github.com/robertdfrench/revolving-doors is a good tutorial, but it doesn't apply to Rust, and won't leverage the Rust-friendly abstractions in this crate. A separate tutorial (separate from the documentation, which will read more like a reference manual) will be useful for folks who might be approaching doors for the first time in Rust.

Like https://github.com/robertdfrench/rusty-doors-oxide/tree/main/lib/examples

Here are the memory layout scenarios if we ignore descriptors:

1. Door call is empty and return is empty
2. Door call is empty and return maps $M$ bytes into the address space (since rbuf is NULL)
3. Door call references $D$ bytes of data, $0$ bytes of rbuf, and return is empty
4. Door call references $D$ bytes of data, $0$ bytes of rbuf, and return maps $M$ bytes into the address space
5. Door call references $D$ bytes of data, $R$ bytes of rbuf, and return copies $C &lt; R$ bytes into rbuf
6. Door call references $D$ bytes of data within rbuf. rbuf has length $R &gt; D$, and return copies $C &lt; R$ bytes into rbuf
7. Door call references $D$ bytes of data within rbuf. rbuf has length $R &gt; D$, but return data has length $M &gt; R$, so return maps $M$ bytes into the address space.

Door procedures could look like this:

door::server_procedure!(|UserType data, Vec<RawFd> descriptors| {
    println!("I received {}", data);
    println!("I also got {} file descriptors", descriptors.len());
})

but that leaves open the question of where to name the server procedure (and the resulting type). Maybe this:

door::server_procedure!(|UserType data, Vec<RawFd> descriptors| {
    println!("I received {}", data);
    println!("I also got {} file descriptors", descriptors.len());
}, DoorName)

or

door::fn!(DoorName = |UserType data, Vec<RawFd> descriptors| {
    println!("I received {}", data);
    println!("I also got {} file descriptors", descriptors.len());
})

which has the advantage of being most reminiscent of the lambda syntax, but doesn't strictly stand out clearly in the code as an identifier.

Decided to use the proc macros instead

Like in https://github.com/oxidecomputer/rusty-doors/blob/main/lib/src/lib.rs#L127