Add type state to ensure proper usage

[Sympatron]

This is a tracking issue for the proposed type state system to ensure only currently valid/sensible methods are callable.

@jonahd-g already put together some ideas in #31.

[jonahd-g]

Current working draft depends on an unstable nightly feature (generic associated types). We should try to come up with an alternate solution that doesn't require this.

pub struct Udp;
pub struct Closed;
pub struct Connected;
pub struct Bound;

pub trait Mode {}
impl Mode for Udp {}

pub trait Status {}
impl Status for Closed {}
impl Status for Connected {}
impl Status for Bound {}

pub trait OpenStatus: Status {}
impl OpenStatus for Connected {}
impl OpenStatus for Bound {}

pub trait UdpStack {]
    type UdpSocket<M: Mode, S: Status>;]
    type Error: core::fmt::Debug;
]
    fn socket(&self) -> Result<Self::UdpSocket<Udp, Closed>, Self::Error> where <Self as UdpStack>::UdpSocket<Udp, Closed>: core::marker::Sized;

    fn connect(&self, socket: Self::UdpSocket<Udp, Closed>, remote: SocketAddr) -> Result<Self::UdpSocket<Udp, Connected>, Self::Error> where <Self as UdpStack>::UdpSocket<Udp, Connected>: core::marker::Sized;

    fn bind(&self, socket: Self::UdpSocket<Udp, Closed>, local_port: u16) -> Result<Self::UdpSocket<Udp, Bound>, Self::Error> where <Self as UdpStack>::UdpSocket<Udp, Bound>: core::marker::Sized;

    fn send(&self, socket: &mut Self::UdpSocket<Udp, Connected>, buffer: &[u8]) -> nb::Result<(), Self::Error>;

    fn send_to(
        &self,
        socket: &mut Self::UdpSocket<Udp, impl OpenStatus>,
        remote: SocketAddr,
        buffer: &[u8],
    ) -> nb::Result<(), Self::Error>;

    fn receive(
        &self,
        socket: &mut Self::UdpSocket<Udp, impl OpenStatus>,
        buffer: &mut [u8],
    ) -> nb::Result<(usize, SocketAddr), Self::Error>;                                                                                                                                          

    fn close<S: Status>(&self, socket: Self::UdpSocket<Udp, S>) -> Result<(), Self::Error>;
}

[jonahd-g]

A solution that would omit the need for GAT would be to publish our own Socket struct with the needed generics. Something like this:

pub struct Socket<Mode, Status, Extra> {
  // Pretty sure PhantomData is necessary here, but maybe type parameters could be underscore prefixed instead
  mode: std::marker::PhantomData<Mode>;
  status: std::marker::PhantomData<Status>;
  pub extra: Extra;
}

The user would then provide an interior Extra type, instead of the Socket type itself. The extra would likely be necessary for encapsulating the socket's identity, and possibly other arbitrary data needed by the driver. We might also be able to do some trait implementation trickery to make it easier to work with... perhaps Deref it into its Extra type?

[eldruin]

Fallibility is often a difficult aspect of type-state interfaces since they consume resources.
For example, with the interface above if I want to bind a socket to one of the free ports within a range I need to open a new socket for each attempt:

let stack = StackImpl{};
let mut port = 8080;
let bound_socket_res = loop {
    let socket = stack.socket().unwrap(); // I need to open a new socket each time
    match stack.bind(socket, 8081) {
        Ok(s) => break Ok(s),
        Err(e) => { // socket was consumed
            if port > 8085 {
                break Err(e);
            }
            port += 1; // retry with next port
        }
    }
};

On the playground

One could say an implementation could return the socket in the error type but then you need recursion to implement something like that:

fn bind<S: UdpStack<Error = UdpSocket>>(
    stack: &S,
    socket: UdpSocket,
    port: u16,
    port_max: u16,
) -> Result<UdpSocket, UdpSocket> {
    match stack.bind(socket, port) {
        Ok(s) => Ok(s),
        Err(s) => {
            if port > port_max {
                Err(s)
            } else {
                bind(stack, s, port + 1, port_max)
            }
        }
    }
}

let bound_socket_res = bind(&stack, socket, 8080, 8085);

On the playground

Recursion is ok in this case but might not be as easy to do in other cases.

Have you thought about this?

[Sympatron]

Maybe a socket trait is enough to get around GAT. I think this would be better (if it works) than forcing a specific socket struct.

[jonahd-g]

@Sympatron I tried to use a trait, but it did not have the same effect. I couldn't get around needing to raise the generics up to the top-level of the Stack trait, which defeated the whole purpose. If you can figure out a way to apply it, I'd love to see a solution. I was unable to.

[jonahd-g]

@eldruin That's an interesting problem. Maybe it's because I haven't done much network programming, but that doesn't seem like a super common use-case. However, I did manage to create a solution that doesn't require recursion, just a loop (which is exactly what I'd expect to accomplish this task).

It's ugly; I stopped working on it as soon as the compiler was happy 😃

fn bind_range<S: UdpStack<Error = UdpSocket>>(
    stack: &S,
    socket: UdpSocket,
    port: u16,
    port_max: u16,
) -> Result<UdpSocket, UdpSocket> {
    let mut p = port;
    let mut loop_socket = socket;
    loop {
        match stack.bind(loop_socket, p) {
            Ok(s) => return Ok(s),
            Err(s) => {
                loop_socket = s;
                if p == port_max {
                    return Err(loop_socket);
                }
            }
        }
        p += 1;
    }
}

Playground

To solve this in general though, I'd be in favor of changing the signature of socket-consuming fallible functions to return a tuple of (Socket, Self::Error).

   fn connect(&self, socket: Self::UdpSocket<Udp, Closed>, remote: SocketAddr) -> Result<Self::UdpSocket<Udp, Connected>, (Self::UdpSocket<Udp, Closed>, Self::Error)> where <Self as UdpStack>::UdpSocket<Udp, Connected>: core::marker::Sized;