Chili Palmer
f0fd975d0f
Some checks failed
Native code generation / deterministic (push) Successful in 18m9s
Imaging and meshing gate / native (push) Successful in 5m45s
JPEG 2000 feature / linux (push) Successful in 2m45s
Native Rust workspace compile / compile (push) Has been cancelled
Skia feature / linux (push) Successful in 31m33s
103 lines
4.4 KiB
Markdown
103 lines
4.4 KiB
Markdown
# Native programs
|
||
|
||
The `libremetaverse-programs` package owns one native Rust binary for every
|
||
program in the pinned LibreMetaverse source snapshot. The source inventory and
|
||
hashes remain in `upstream-programs.json`; implementation status is tracked
|
||
here so a source entry is never mistaken for a completed port.
|
||
|
||
| Binary | Upstream project | Status |
|
||
| --- | --- | --- |
|
||
| `osd-inspector` | OSDInspector | Implemented and tested offline |
|
||
| `simple-bot` | SimpleBot | Implemented with live and deterministic fake-grid modes |
|
||
| `packet-dump` | PacketDump | Pending milestone 11 issue #87 |
|
||
| `prim-inspector` | PrimInspector | Pending milestone 11 issue #88 |
|
||
| `inventory-explorer` | InventoryExplorer | Pending milestone 11 issue #89 |
|
||
| `irc-gateway` | IRCGateway | Pending milestone 11 issue #90 |
|
||
| `test-client` | TestClient | Pending milestone 11 issues #91–#94 |
|
||
| `vivox-test` | VivoxTest | Pending milestone 11 issue #95 |
|
||
| `webrtc-test` | WebRtcTest | Pending milestone 11 issue #96 |
|
||
|
||
## OSDInspector
|
||
|
||
`osd-inspector` is a bounded, offline command-line client of the public native
|
||
StructuredData and Primitive APIs. It does not initialize a grid client, read
|
||
credentials, load a native codec, or invoke a .NET process.
|
||
|
||
```text
|
||
osd-inspector inspect <file> # alias: i
|
||
osd-inspector convert <input> <format> <out> # alias: c
|
||
osd-inspector validate <file> # alias: v
|
||
osd-inspector prim-to-osd
|
||
osd-inspector osd-to-prim <file>
|
||
```
|
||
|
||
The supported output formats are `json` (`j`), `xml` (`x`), `binary`
|
||
(`bin` or `b`), and `notation` (`llsd` or `n`). Use `-` as an input or output
|
||
path for standard input or standard output. Format detection uses the filename
|
||
extension as a hint and then checks every native parser, so binary and notation
|
||
LLSD work through files and pipes as well as JSON and XML.
|
||
|
||
Input is read through a bounded buffer and is limited to the StructuredData
|
||
binary allocation limit by default. `--max-input-bytes <BYTES>` can lower that
|
||
ceiling for constrained callers. StructuredData also enforces its depth, node,
|
||
and aggregate allocation limits while parsing.
|
||
|
||
Normal results are written to stdout and diagnostics to stderr. Exit status is
|
||
stable for scripts:
|
||
|
||
| Status | Meaning |
|
||
| --- | --- |
|
||
| 0 | Success |
|
||
| 2 | Command-line usage error |
|
||
| 3 | File or standard-stream I/O error |
|
||
| 4 | Invalid or oversized OSD input |
|
||
| 5 | Primitive conversion or output serialization error |
|
||
|
||
Run the issue-focused CLI suite and the related translated StructuredData cases
|
||
with:
|
||
|
||
```sh
|
||
cargo test -p libremetaverse-programs --test osd_inspector_cli --locked
|
||
cargo test --manifest-path tests/compat/Cargo.toml --test structured_data --locked
|
||
```
|
||
|
||
## SimpleBot
|
||
|
||
`simple-bot` is an asynchronous native Rust client with the command surface of
|
||
the upstream example. A live session accepts the original positional
|
||
credentials, or reads them from the environment:
|
||
|
||
```text
|
||
simple-bot FIRSTNAME LASTNAME PASSWORD [--login-uri URL]
|
||
GRID_FIRST_NAME=... GRID_LAST_NAME=... GRID_PASSWORD=... simple-bot
|
||
```
|
||
|
||
`GRID_LOGIN_URL` supplies the endpoint when `--login-uri` is absent, and
|
||
`--login-timeout-seconds` bounds login to 30 seconds by default. Credentials,
|
||
authorization values, capability URLs, and token values are redacted from
|
||
output. After login the bot answers `help`/`?`, `where`/`location`, `sit`,
|
||
`stand`, `dance`, `fly`, `walk`, `jump`, and `hello`/`hi`/`hey` instant
|
||
messages. It also greets other avatars that say hello in local chat. Ctrl-C
|
||
cancels pending greetings and login work, releases an in-progress jump,
|
||
unsubscribes event handlers, logs out, and disposes the client before exit.
|
||
|
||
For offline validation, `--fake-script FILE` runs the same command handlers
|
||
against a deterministic fake grid. Scripts contain no credentials. Blank
|
||
lines and lines beginning with `#` are ignored; remaining lines use one of:
|
||
|
||
```text
|
||
im<TAB>source-uuid<TAB>source-name<TAB>message
|
||
chat<TAB>source-uuid<TAB>source-name<TAB>message
|
||
status<TAB>message
|
||
```
|
||
|
||
The reader accepts at most 1 MiB, 1,024 events, 256-byte names, and 4,096-byte
|
||
messages. The fake transcript records every client call, uses the real DANCE1
|
||
UUID, and finishes with zero active tasks and sockets. Run the issue-focused
|
||
suite and the related runtime compatibility cases with:
|
||
|
||
```sh
|
||
cargo test -p libremetaverse-programs --test simple_bot_cli --locked
|
||
cargo test --manifest-path tests/compat/Cargo.toml --test core_runtime_shims --locked
|
||
```
|