# Overview

MicroEJ Add-on Library: `WASI`.

This addon library implements [WASI 0.1 APIs](https://github.com/WebAssembly/WASI/blob/main/legacy/preview1/docs.md)

All the implemented functions are exported under the module name `wasi_snapshot_preview1`.

The APIs are extended to support certain POSIX functions that are not available in [wasi-libc](https://github.com/WebAssembly/wasi-libc) such as `socket`, `bind`, `connect` etc.

The sections below list the WASI APIs and the high level WASI-based POSIX APIs that are currently supported.

# WASI APIs

| **API Group**   | **WASI Functions**                                                                                                                                                                                                                                                                                                                                                          |
|-----------------|-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
| **FileSystem**  | `path_create_directory`, `path_open`, `path_rename`, `path_unlink_file`, `path_remove_directory`, `path_filestat_get`, `path_filestat_set_times`, `fd_readdir`, `fd_close`, `fd_read`, `fd_pread`, `fd_write`, `fd_pwrite`, `fd_seek`, `fd_tell`, `fd_filestat_get`, `fd_filestat_set_size`, `fd_fdstat_get`, `fd_fdstat_set_flags`, `fd_prestat_get`, `fd_prestat_dir_name`, `fd_renumber`, `fd_datasync`\*, `fd_sync`\* |
| **Process**     | `proc_exit`                                                                                                                                                                                                                                                                                                                                                                 |
| **Clocks**      | `clock_time_get`, `clock_res_get`                                                                                                                                                                                                                                                                                                                                           |
| **Sockets**     | `sock_accept`, `sock_shutdown`, `sock_recv`, `sock_send`, `poll_oneoff`                                                                                                                                                                                                                                                                                                     |
| **Environment** | `environ_sizes_get`, `environ_get`, `args_sizes_get`\*, `args_get`\*                                                                                                                                                                                                                                                                                                        |
| **Scheduling**  | `sched_yield`                                                                                                                                                                                                                                                                                                                                                               |
| **Random**      | `random_get`                                                                                                                                                                                                                                                                                                                                                                |
| **Threads**     | `thread-spawn`                                                                                                                                                                                                                                                                                                                                                              |
| **Unsupported** | `path_readlink`\*\*, `path_link`\*\*, `path_symlink`\*\*                                                                                                                                                                                                                                                                                                                   |

\* Stub — returns success with no effect.
\*\* Returns `ERRNO_NOSYS`.

# High-Level WASI-Based POSIX APIs

These functions are provided by [wasi-libc](https://github.com/WebAssembly/wasi-libc) on top of the WASI APIs above.

| **API Group**     | **POSIX Functions**                                                                                                                                                                               |
|-------------------|---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
| **FileSystem**    | `open`, `fopen`, `fdopendir`, `close`, `fclose`, `read`, `write`, `fread`, `fwrite`, `lseek`, `stat`, `fstat`, `readdir`, `fstatat`, `fileno`, `fflush`, `access`, `rename`, `mkdir`, `rmdir`, `unlink`, `chdir`, `fsync` |
| **Process**       | `exit`                                                                                                                                                                                            |
| **StdIO**         | `printf`                                                                                                                                                                                          |
| **Clocks**        | `clock_getres`, `clock_gettime`, `gettimeofday`                                                                                                                                                   |
| **Sockets**       | `send`, `recv`, `accept`, `shutdown`, `poll`, `select`, `getsockopt`\*                                                                                                                             |
| **Environment**   | `getenv`                                                                                                                                                                                          |
| **Threads**       | `pthread_create`, `pthread_join`, `pthread_detach`, `pthread_mutex_*`, `pthread_rwlock_*`, `pthread_cond_*`, `pthread_barrier_*`, `sem_*`                                                           |

# High-Level Extended WASI POSIX APIs

These functions are not available in wasi-libc and are provided by the WASI extension library (`wasi-ext`).

| **API Group**  | **POSIX Functions**                                                                                                                                                                                   |
|----------------|-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
| **Sockets**    | `socket`, `bind`, `listen`, `connect`, `setsockopt`, `getpeername`, `getsockname`, `sendto`, `recvfrom`                                                                                               |
| **DNS**        | `getaddrinfo`, `freeaddrinfo`, `getnameinfo`\*\*                                                                                                                                                      |
| **Network**    | `gethostname`, `getifaddrs`, `freeifaddrs`                                                                                                                                                            |
| **FileSystem** | `dup`, `dup2`, `pipe`, `fchdir`                                                                                                                                                                       |
| **SSL/TLS**    | `SSL_new`, `SSL_free`, `SSL_set_fd`, `SSL_set_tlsext_host_name`, `SSL_connect`, `SSL_accept`, `SSL_read`, `SSL_write`, `SSL_pending`, `SSL_shutdown`, `SSL_want_read`, `SSL_want_write`, `SSL_CTX_free` |

\* `getsockopt` supports `SO_TYPE` only (wasi-libc queries `fd_fdstat_get`); other options return `ENOPROTOOPT`.
\*\* Numeric-only (no reverse DNS lookup).

# Notes

- **Stubs**: `fd_datasync`, `fd_sync`, `args_sizes_get`, and `args_get` return success without performing any operation. `path_link`, `path_symlink`, and `path_readlink` return `ERRNO_NOSYS`.
- **Environment variables**: Requires calling `Wasi.setEnvironment()` before `Wasi.init()` for environment variables to be visible to the WASM module.
- **Threading**: Thread support uses the wasi-threads proposal. The full pthreads API (mutexes, rwlocks, condition variables, barriers, semaphores) is available through wasi-libc.
- **SSL/TLS**: SSL functions are exported under the `wasi_ssl` module name, separate from the `wasi_snapshot_preview1` module.
- **IPv4 and IPv6**: Socket operations (`bind`, `connect`, `sendto`, `recvfrom`, `getaddrinfo`) support both IPv4 and IPv6 addresses.
- **`getnameinfo`**: Numeric-only — returns the numeric address and port strings. Reverse DNS lookup is not supported.

# Usage

Add the following line to your `build.gradle.kts`:

```
dependencies {
    implementation("ej.library.runtime:wasi:1.0.0")
}
```

# Requirements

None.

# Dependencies

_All dependencies are retrieved transitively by Gradle_.

# Source

N/A.

# Restrictions

None.

_Copyright 2024-2026 MicroEJ Corp. All rights reserved._
_Use of this source code is governed by a BSD-style license that can be found with this software._
_Build: 7E4D1F7C_
