Skip to content

Use identifiers in properties. #107

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
PiotrSikora wants to merge 1 commit into
base: main
Choose a base branch
from
Open

Use identifiers in properties. #107

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
154 changes: 31 additions & 123 deletions abi-versions/vNEXT/README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -1950,144 +1950,52 @@ This function is gated on [`HAS_METRICS`] host feature.

### Functions exposed by the host

#### `proxy_get_property`
#### `proxy_get_supported_properties`

* params:
- `i32 (uint32_t) context_id`
- `i32 (const uint8_t *) path_data`
- `i32 (size_t) path_size`
- `i32 (uint8_t **) return_value_data`
- `i32 (size_t *) return_value_size`
- `i32 (uint8_t **) return_serialized_properties_data`
- `i32 (size_t *) return_serialized_properties_size`
* returns:
- `i32 (`[`proxy_status_t`]`) status`

Retrieves value (`return_value_data`, `return_value_size`)
of the property (`path_data`, `path_size`) of context `context_id`.
Retrieves a list of supported [properties].

`path_data` is a [serialized] list of path segments.
Returned list (`return_serialized_properties_data`,
`return_serialized_properties_size`) is [serialized].

Returned `status` value is:
- `OK` on success.
- `UNKNOWN_RESOURCE_ID` for unknown `context_id`.
- `NOT_FOUND` when there was no property found at the requested `path`.
- `SERIALIZATION_FAILURE` when host failed to serialize property.
- `INVALID_MEMORY_ACCESS` when `path_data`, `path_size`,
`return_value_data` and/or `return_value_size` point to invalid
memory address.
- `INVALID_MEMORY_ACCESS` when `return_serialized_features_data` and/or
`return_serialized_features_size` point to invalid memory address.

This function is gated on [`HAS_PROPERTIES`] host feature.


#### `proxy_set_property`
#### `proxy_get_property`

* params:
- `i32 (uint32_t) context_id`
- `i32 (const uint8_t *) path_data`
- `i32 (size_t) path_size`
- `i32 (const uint8_t *) value_data`
- `i32 (size_t) value_size`
- `i32 (uint32_t) property_id`
- `i32 (uint8_t **) return_value_data`
- `i32 (size_t *) return_value_size`
* returns:
- `i32 (`[`proxy_status_t`]`) status`

Sets value of the property (`path_data`, `path_size`) to the provided
value (`value_data`, `value_size`) in context `context_id`.

`path_data` is a [serialized] list of path segments.
Retrieves value (`return_value_data`, `return_value_size`)
of the property (`property_id`) of context `context_id`.

Returned `status` value is:
- `OK` on success.
- `UNKNOWN_RESOURCE_ID` for unknown `context_id`.
- `NOT_FOUND` when there was no property found at the requested `path`.
- `INVALID_MEMORY_ACCESS` when `path_data`, `path_size`, `value_data`
and/or `value_size` point to invalid memory address.
- `SERIALIZATION_FAILURE` when host failed to serialize property.
- `INVALID_MEMORY_ACCESS` when `path_data`, `path_size`,
`return_value_data` and/or `return_value_size` point to invalid
memory address.

This function is gated on [`HAS_PROPERTIES`] host feature.


### Well-known properties

> **Warning**
> Properties are implementation-dependent and not stable across
> different versions of the same host.
> When targeting a specific host implementation (discouraged),
> please refer to its official documentation for a complete list
> of supported properties.


#### Proxy-Wasm properties

* `plugin_name` (string) - plugin name
* `plugin_root_id` (string) - plugin root ID
* `plugin_vm_id` (string) - plugin VM ID


#### Downstream connection properties

* `connection.id` (uint) - connection ID
* `source.address` (string) - remote address
* `source.port` (int) - remote port
* `destination.address` (string) - local address
* `destination.port` (int) - local port
* `connection.tls_version` (string) - TLS version
* `connection.requested_server_name` (string) - TLS SNI
* `connection.mtls` (bool) - true if the TLS client certificate was validated
* `connection.subject_local_certificate` (string) - subject of
the local certificate
* `connection.subject_peer_certificate` (string) - subject of
the peer certificate
* `connection.dns_san_local_certificate` (string) - first DNS entry in
the local certificate
* `connection.dns_san_peer_certificate` (string) - first DNS entry in
the the peer certificate
* `connection.uri_san_local_certificate` (string) - first URI entry in
the local certificate
* `connection.uri_san_peer_certificate` (string) - first URI entry in
the peer certificate
* `connection.sha256_peer_certificate_digest` (string) - SHA256 digest of
the peer certificate


#### Upstream connection properties

* `upstream.address` (string) - remote address
* `upstream.port` (int) - remote port
* `upstream.local_address` (string) - local address
* `upstream.local_port` (int) - local port
* `upstream.tls_version` (string) - TLS version
* `upstream.subject_local_certificate` (string) - subject of
the local certificate
* `upstream.subject_peer_certificate` (string) - subject of
the peer certificate
* `upstream.dns_san_local_certificate` (string) - first DNS entry in
the local certificate
* `upstream.dns_san_peer_certificate` (string) - first DNS entry in
the peer certificate
* `upstream.uri_san_local_certificate` (string) - first URI entry in
the local certificate
* `upstream.uri_san_peer_certificate` (string) - first URI entry in
the peer certificate
* `upstream.sha256_peer_certificate_digest` (string) - SHA256 digest of
the peer certificate


#### HTTP request properties

* `request.protocol` (string) - HTTP version
(`HTTP/1.0`, `HTTP/1.1`, `HTTP/2`, `HTTP/3`)
* `request.time` (timestamp) - time of the first byte received
* `request.duration` (duration) - total duration of the HTTP request
* `request.size` (int) - size of the HTTP request body
* `request.total_size` (int) - total size of the HTTP request
(including HTTP headers and trailers)


#### HTTP response properties

* `response.size` (int) - size of the HTTP response body
* `response.total_size` (int) - total size of the HTTP response
(including HTTP headers and trailers)


## Foreign function interface (FFI)

### Functions exposed by the host
Expand Down Expand Up @@ -2200,6 +2108,16 @@ This function is never called.
> The encoding of integers is little-endian.


#### List of identifiers (e.g. properties)

A non-empty list of identifiers is serialized as:
- 32-bit integer containing the number of identifiers in the list,
- a series of pairs of 32-bit identifiers

An empty map may be represented either as an empty value (`size=0`), or as
a single `0x00` byte (`size=1`).


#### List with host features

A non-empty feature list is serialized as:
Expand Down Expand Up @@ -2227,18 +2145,6 @@ e.g. the map `{{"a": "1"}, {"b": "22"}}` would be serialized as:
An empty map may be represented either as an empty value (`size=0`), or as
a single `0x00` byte (`size=1`).

#### Property path names

Path data for the [proxy_get_property] and [property_set_property] hostcalls
consists of a sequence of path segments. The path segments are separated by
`NULL` (`0x00`) characters.

e.g. the path segments `["foo", "bar"]` would be serialized as:
- `0x66`, `0x6f`, `0x6f`, `0x00`, `0x62`, `0x61`, `0x72`

Host implementations should tolerate a `NULL` character at the end of the
combined path data string, if present.


# Security Considerations

Expand Down Expand Up @@ -2414,6 +2320,8 @@ changes to unrelated connections/requests.
[`HAS_CUSTOM_FUNCTIONS`]: ./registries/HOST_FEATURES.md
[`HAS_WASI_PREVIEW1_CORE`]: ./registries/HOST_FEATURES.md

[properties]: ./registries/PROPERTIES.md

[`proxy_abi_version_0_x_x`]: #proxy_abi_version_0_x_x
[`_initialize`]: #_initialize
[`main`]: #main
Expand Down Expand Up @@ -2478,8 +2386,8 @@ changes to unrelated connections/requests.
[`proxy_record_metric`]: #proxy_record_metric
[`proxy_increment_metric`]: #proxy_increment_metric
[`proxy_get_metric`]: #proxy_get_metric
[`proxy_get_supported_properties`]: #proxy_get_supported_properties
[`proxy_get_property`]: #proxy_get_property
[`proxy_set_property`]: #proxy_set_property
[`proxy_call_foreign_function`]: #proxy_call_foreign_function
[`proxy_on_foreign_function`]: #proxy_on_foreign_function

Expand Down
75 changes: 75 additions & 0 deletions abi-versions/vNEXT/registries/PROPERTIES.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,75 @@
# Properties

#### Proxy-Wasm properties

| Identifier | Name | Type | Description |
|:----------:|:--------------------------------------|:--------:|:--------------------------------------------------------------------------|
| 0x0001 | `PLUGIN_NAME` | `string` | Plugin name |
| 0x0002 | `PLUGIN_ROOT_ID` | `string` | Plugin root ID |
| 0x0003 | `PLUGIN_VM_ID` | `string` | Plugin VM ID |


#### Downstream connection properties

| Identifier | Name | Type | Description |
|:----------:|:--------------------------------------|:--------:|:--------------------------------------------------------------------------|
| 0x0101 | `DOWNSTREAM_CONNECTION_ID` | `uint` | Connection ID |
| 0x0102 | `DOWNSTREAM_REMOTE_IP` | `string` | Remote address |
| 0x0103 | `DOWNSTREAM_REMOTE_PORT` | `int` | Remote port |
| 0x0104 | `DOWNSTREAM_LOCAL_IP` | `string` | Local address |
| 0x0105 | `DOWNSTREAM_LOCAL_PORT` | `int` | Local port |
| 0x0106 | `DOWNSTREAM_TLS_VERSION` | `string` | Negotiated TLS version |
| 0x0107 | `DOWNSTREAM_TLS_REQUESTED_SNI` | `string` | Requested TLS Server Name Indication (SNI) |
| 0x0108 | `DOWNSTREAM_TLS_PEER_CERT_VALIDATED` | `bool` | Peer's TLS certificate validation status |
| 0x0109 | `DOWNSTREAM_TLS_PEER_CERT_SUBJECT` | `string` | Peer's TLS certificate Subject |
| 0x010A | `DOWNSTREAM_TLS_PEER_CERT_DNS_SAN` | `string` | First DNS entry in peer's TLS certificate Subject Alternative Name (SAN) |
| 0x010B | `DOWNSTREAM_TLS_PEER_CERT_URI_SAN` | `string` | First URI entry in peer's TLS certificate Subject Alternative Name (SAN) |
| 0x010C | `DOWNSTREAM_TLS_PEER_CERT_SHA256` | `string` | SHA256 digest of peer's TLS certificate |
| 0x010D | `DOWNSTREAM_TLS_LOCAL_CERT_SUBJECT` | `string` | Local TLS certificate Subject |
| 0x010E | `DOWNSTREAM_TLS_LOCAL_CERT_DNS_SAN` | `string` | First DNS entry in local TLS certificate Subject Alternative Name (SAN) |
| 0x010F | `DOWNSTREAM_TLS_LOCAL_CERT_URI_SAN` | `string` | First URI entry in local TLS certificate Subject Alternative Name (SAN) |
| 0x0110 | `DOWNSTREAM_TLS_LOCAL_CERT_SHA256` | `string` | SHA256 digest of local TLS certificate |


#### Upstream connection properties

| Identifier | Name | Type | Description |
|:----------:|:--------------------------------------|:--------:|:--------------------------------------------------------------------------|
| 0x0201 | `UPSTREAM_CONNECTION_ID` | `uint` | Connection ID |
| 0x0202 | `UPSTREAM_REMOTE_IP` | `string` | Remote address |
| 0x0203 | `UPSTREAM_REMOTE_PORT` | `int` | Remote port |
| 0x0204 | `UPSTREAM_LOCAL_IP` | `string` | Local address |
| 0x0205 | `UPSTREAM_LOCAL_PORT` | `int` | Local port |
| 0x0206 | `UPSTREAM_TLS_VERSION` | `string` | Negotiated TLS version |
| 0x0207 | `UPSTREAM_TLS_REQUESTED_SNI` | `string` | Requested TLS Server Name Indication (SNI) |
| 0x0208 | `UPSTREAM_TLS_PEER_CERT_VALIDATED` | `bool` | Peer's TLS certificate validation status |
| 0x0209 | `UPSTREAM_TLS_PEER_CERT_SUBJECT` | `string` | Peer's TLS certificate Subject |
| 0x020A | `UPSTREAM_TLS_PEER_CERT_DNS_SAN` | `string` | First DNS entry in peer's TLS certificate Subject Alternative Name (SAN) |
| 0x020B | `UPSTREAM_TLS_PEER_CERT_URI_SAN` | `string` | First URI entry in peer's TLS certificate Subject Alternative Name (SAN) |
| 0x020C | `UPSTREAM_TLS_PEER_CERT_SHA256` | `string` | SHA256 digest of peer's TLS certificate |
| 0x020D | `UPSTREAM_TLS_LOCAL_CERT_SUBJECT` | `string` | Local TLS certificate Subject |
| 0x020E | `UPSTREAM_TLS_LOCAL_CERT_DNS_SAN` | `string` | First DNS entry in local TLS certificate Subject Alternative Name (SAN) |
| 0x020F | `UPSTREAM_TLS_LOCAL_CERT_URI_SAN` | `string` | First URI entry in local TLS certificate Subject Alternative Name (SAN) |
| 0x0210 | `UPSTREAM_TLS_LOCAL_CERT_SHA256` | `string` | SHA256 digest of local TLS certificate |


#### HTTP properties

| Identifier | Name | Type | Description |
|:----------:|:--------------------------------------|:--------:|:--------------------------------------------------------------------------|
| 0x0301 | `HTTP_REQUEST_PROTOCOL` | `string` | HTTP protocol version (`HTTP/1.0`, `HTTP/1.1`, `HTTP/2`, `HTTP/3`) |
| 0x0302 | `HTTP_REQUEST_START_TIME` | `??????` | Time of the first byte received |
| 0x0303 | `HTTP_REQUEST_DURATION` | `??????` | Total duration of HTTP request |
| 0x0304 | `HTTP_REQUEST_CONTENT_SIZE` | `int` | Size of HTTP request body |
| 0x0305 | `HTTP_REQUEST_TOTAL_SIZE` | `int` | Total size of HTTP request (including HTTP headers and trailers) |
| 0x0306 | `HTTP_RESPONSE_CONTENT_SIZE` | `int` | Size of HTTP response body |
| 0x0307 | `HTTP_RESPONSE_TOTAL_SIZE` | `int` | Total size of HTTP response (including HTTP headers and trailers) |


Identifiers below 0x2000 are reserved for standardized properties.

Numbers above that range are considered private and can be used without assignment in the registry.

Random number in the private range should be used for private extensions and properties under active development.

Once the property is finalized and implemented in a subset of hosts and SDKs, it will be assigned identifier in the standardized range.
Loading