Blog Docs Roadmap GitHub
October 25, 2021

Utilizing h/2 headers - cleaner, simpler, faster

Wireleap now uses built-in h/2 mechanisms instead of the previous implementation which encoded the initial payload (ie. next-hop and sharetoken) and the status messages on error or connection close in the request body.

This results in simplifying the code, simplifying the protocol, faster establishment and closing of connections, and improved performance. Traffic literally passes bytewise from client to target and back with no modification.

Please note, this is a backwards incompatible release.

HTTP/2 headers and trailers

Previously, when routing traffic through relays in the circuit, an h/2 connection was established, then communication would happen using the wlnet wire protocol in the “body” of the request. The initial payload (ie. next-hop and sharetoken) was encoded and included in the body of outgoing traffic. The incoming traffic from target back to client was encoded in chunks, each with its own header which denoted the size of the chunk and whether it was an “in-band” message (traffic to be relayed back to the client) or “out-of-band” (error message to be processed by wireleap itself).

This required the code to be aware of the status of the connection on two levels, as even if the relay accepted the headers and replied with a HTTP 200 OK, there was still no guarantee that there would not be an error immediately after (e.g., invalid sharetoken).

With this release, the outgoing initial payload is included in the standard h/2 request header, and the returning traffic distinction is made using the standard h/2 trailer mechanism which allows for headers to be sent on connection close (hence they are called trailers here, functionally they are identical to headers).

BEFORE: headers -> payload "bump" of a defined size -> streamed data
AFTER:  headers -> streamed data

As a bonus, this makes traffic look more like regular h/2 as there is no characteristic signature of sending the payload after the initial h/2 request anymore (previous side by side traffic comparison).

Upgrade channels

The directory supplied update_channels has been replaced with a more future proof upgrade_channels data structure.

-    "update_channels": {
-        "default": "0.4.0",
-        "client": "0.4.0"
-    },

+    "upgrade_channels": {
+        "relay": { "default": "0.5.0" },
+        "client": { "default": "0.5.0" }
+    },

Existing directory deployments may support both structures to allow for already deployed clients and relays to seamlessly upgrade with their relative upgrade mechanisms (client, relay).

Note: The wireleap-relay 0.5.0 includes a migration for updating the relay’s upgrade channel configuration if set.

Changes

common (0.2.2)

  • relayentry, dirinfo: added upgrade_channel support (deprecated update_channels).
  • wlnet: moved init payload to H/2 headers and status messages to H/2 trailers.
  • wlnet: removed obsolete wire protocol code.
  • ststore: fixed initial filepath.Walk not adding sharetokens to the store.
  • Includes interface versions:
    • clientcontract v0.1.0
    • clientdir v0.2.0 (new version)
    • clientrelay v0.2.0 (new version)
    • contractps v0.1.0
    • psauth v0.1.0
    • relaycontract v0.1.0
    • relaydir v0.2.0 (new version)
    • relayrelay v0.2.0 (new version)

wireleap (0.5.0)

  • Depends on wireleap/common v0.2.2.
  • Uses upgrade_channels instead of now deprecated update_channels.
  • Updated circuit dialer to use the new H/2 header/trailer payload code.
  • TUN permission check now verifies ownership before setuid bit.
  • Pre-release versions are not forced to upgrade on startup anymore.
  • Fixed relay version not being nil-checked when building circuit.
  • Uses interfaces:
    • clientdir v0.2.0 (new version)
    • clientcontract v0.1.0
    • clientrelay v0.2.0 (new version)

wireleap-relay (0.5.0)

  • Depends on wireleap/common v0.2.2.
  • Added upgrade_channels support and related migration code.
  • Deprecated update_channels, no longer used for relay upgrades.
  • Uses new H/2 header/trailer payload code.
  • All interface versions are now submitted to directory.
  • Uses interfaces:
    • clientrelay v0.2.0 (new version)
    • relaycontract v0.1.0
    • relayrelay v0.2.0 (new version)
    • relaydir v0.2.0 (new version)

wireleap-dir (0.5.0)

  • Depends on wireleap/common v0.2.2.
  • Relay enrollment ping now uses new H/2 header/trailer payload code.
  • Added upgrade_channels support, deprecated update_channels.
  • Presence of update_channels in config.json will trigger a deprecation message on startup.
  • Uses interfaces:
    • clientdir v0.2.0 (new version)
    • relaydir v0.2.0 (new version)

Version

0.5.0