Merge pull request #71 from AjaniBilby/sock_serv_clarifications

Improved Socket API documentation

README.md

@@ -4,4 +4,4 @@
 
 First, run `pnpm i` to install the dependencies.
 
-Then, run `pnpm dev` to start the development server and visit `http://localhost:3000/introduction`.
+Then, run `pnpm dev` to start the development server and visit `http://localhost:3000/`.

pages/docs/api-reference/wasi/fd_close.mdx

@@ -42,4 +42,5 @@ This function has been instrumented with debug-level logging. It will log the fo
 
 ### Note
 
-The `fd_close()` function is used to close an open file descriptor. It releases any resources associated with the file descriptor. For sockets, it ensures that any pending data is flushed before closing the socket.
+The `fd_close()` function is used to close an open file descriptor. It releases any resources associated with the file descriptor.
+For sockets, it is best practise to run [`sock_shutdown()`](./sock_shutdown) before closing, because otherwise it can have unexpected runtime and latency side affects in some wasm runtimes.

pages/docs/api-reference/wasi/sock_shutdown.mdx

@@ -37,3 +37,12 @@ The function returns an `Errno` value. If the operation is successful, `Errno::S
   - `__WASI_SHUT_RD | __WASI_SHUT_WR`: Shut down both the send and receive channels.
 - The function maps the `how` value to the corresponding `std::net::Shutdown` enum variant and passes it to the underlying socket's `shutdown()` method.
 - The specific behavior of the `sock_shutdown()` function may vary depending on the runtime environment and underlying networking implementation.
+- This does not close the file descriptor, remember to `fd_close` afterwards
+
+#### How Flag Values
+
+| Type        | Value | Description                                   |
+| :-          |  :-:  | :-                                            |
+| `SHUT_RD`   |   1   | Shut down the receive channel                 |
+| `SHUT_WR`   |   2   | Shut down the send channel.                   |
+| `SHIT_RDWR` |   3   | Shut down both the send and receive channels. |

pages/docs/api-reference/wasix/sock_bind.mdx

@@ -39,3 +39,40 @@ The function returns an `Errno` value indicating the outcome of the operation. I
 - The behavior and limitations of the `sock_bind()` function may vary depending on the specific runtime environment and underlying networking implementation. It is important to consult the documentation or specifications of the specific environment to understand its behavior in that context.
 - In POSIX, the `bind` function can be used with different address families and protocols, such as IPv6 (PF_INET6) and Unix domain sockets (PF_UNIX). However, in the current context of WASI, the `sock_bind()` function specifically uses the PF_INET address family to bind the socket.
 - The `addr` parameter should contain the IP address and port number to which the socket will be bound.
+
+
+#### Sock Address In Layout
+
+For information on valid `sin_family` values refer to the documentation on [`sock_open()`](/docs/api-reference/wasix/sock_open#address-family-values)
+
+##### IPv4
+
+```typescript
+interface sockaddr_in {
+  sin_family: i16;
+  sin_port:   i16;
+  sin_addr:   i8[4]; // IPv4 address, i.e. 124.456.789.012
+  sin_zero:   i8[8]; // padding for size compatibility with sockaddr
+}
+```
+
+##### IPv6
+
+```typescript
+interface sockaddr_in6 {
+  sin6_family:   i16;
+  sin6_port:     i16;
+  sin6_flowinfo: i32;
+  sin6_addr:     i16[8];
+  sin6_scope_id: i32;
+}
+```
+
+##### IPC
+
+```typescript
+interface sockaddr_un {
+  sun_family: i16;
+  sun_path:   i8[108];
+}
+```

pages/docs/api-reference/wasix/sock_open.mdx

@@ -48,3 +48,24 @@ The function returns an `Errno` value indicating the outcome of the operation. I
 - The file descriptor will be the lowest-numbered file descriptor not currently open for the process.
 - The function `sock_open()` is similar to the `socket` function in POSIX, using the `PF_INET` address family.
 - The behavior and limitations of the `sock_open()` function may vary depending on the specific runtime environment and underlying networking implementation. It is important to consult the documentation or specifications of the specific environment to understand its behavior in that context.
+
+#### Address Family Values
+
+| Type        | Value | Description |
+|  :-         |  :-:  | :-          |
+| `AF_UNSPEC` |   0   | Unspecified placeholder |
+| `AF_INET`   |   1   | Represents a IPv4 address family, and will require a [`sockaddr_in`](./sock_bind#ipv4) when binding |
+| `AF_INET6`  |   2   | Represents a IPv6 address family, and will require a [`sockaddr_in6`](./sock_bind#ipv6) when binding |
+| `AF_LOCAL`  |   3   | Internal socket used for communicating within the same system for IPC calls, this will require a [`sockaddr_un`](./sock_bind#ipc) when binding |
+
+Please refer to [this file](https://github.com/wasix-org/wasix-libc/blob/main/expected/wasm32-wasi/predefined-macros.txt) in the case the value you are looking for isn't here
+
+#### Socket Type Values
+
+| Type           | Value | Description |
+| :-             |  :-:  | :-          |
+| `SOCK_STREAM`  |   1   | TCP Socket  |
+| `SOCK_DGRAM`   |   2   | UDP Socket  |
+| `SOCK_CLOEXEC` | `0x00002000` | This is a flag that can be combined with other socket types using the bitwise OR operator  `\|` |
+
+Please refer to [this file](https://github.com/wasix-org/wasix-libc/blob/main/expected/wasm32-wasi/predefined-macros.txt) in the case the value you are looking for isn't here