From e2e36cc1e1c015fc517a179019184fdc81f3e809 Mon Sep 17 00:00:00 2001 From: "Mark S. Miller" Date: Sun, 14 Apr 2024 23:34:18 -0400 Subject: [PATCH] docs(eventual-send,pass-style): Add missing env var explanations (#9233) closes: #XXXX refs: https://github.com/endojs/endo/pull/2002 https://github.com/endojs/endo/pull/1860 ## Description Now that agoric-sdk depends on a version of endo that switches on these environment variables, it is time for `env.md`, where we gather all such explanations, to explain these additional env vars. ### Security Considerations none, since this PR only documents the existing situation. For the environment variable sensitive behavior itself, I think none as well. We should examine more closely in general whether env var sensitivity in our code opens up any opportunity for attackers. We think not though, because attackers should only ever execute in environments where these are not set to non-defensive settings. And attackers should never be in a position to set these. ### Scaling Considerations none. But the new text does explain the existing scaling consideration around the `ONLY_WELL_FORMED_STRINGS_PASSABLE` environment variable. ### Documentation Considerations the point. Since we gather all these explanations in agoric-sdk's env.md file, there is an inter-repo coordination problem after introducing new env vars into endo. ### Testing Considerations none ### Upgrade Considerations none --- docs/env.md | 47 +++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 47 insertions(+) diff --git a/docs/env.md b/docs/env.md index 4472af2ec28..5b510c4ba3d 100644 --- a/docs/env.md +++ b/docs/env.md @@ -80,6 +80,45 @@ console messages to enable, pass it to `makeConsole`. For example: - `DEBUG=SwingSet:vat` enable for user code, regardless of vat. - `DEBUG=SwingSet:vat,SwingSet:ls` enable for liveslots and user code, all vats +## ENDO_DELIVERY_BREAKPOINTS + +The value of this option should be a JSON string identifying for which +eventual-send message deliveries should a JS `debugger;` statement be executed. +The format of the JSON string is +```json +{ + : { + : , + : , + ... + }, + : { + : + ... + }, + ... +} +``` +Where +- `` is either `"*"` or an alleged string tag of the receiving + remotable (exo or far) object +- `` is either `"*"` or a method name. There is not yet a syntax for symbols to name symbol-named methods, but there may eventually be. +- `` is either `"*"` or a non-negative integer saying how many occurrences to ignore before breakpointing. + +When the program is run under a debugger, it will breakpoint when the JS +`debugger;` statement is executed. When run normally without a debugger, the +`debugger;` statement will have no effect. The `debugger;` statement +is executed *before* the method is entered. + +See https://github.com/endojs/endo/blob/master/packages/pass-style/test/prepare-breakpoints.js for an example. + +## ENDO_SEND_BREAKPOINTS + +The value of this option is a JSON string identifying for which eventual sends +should a JS `debugger;` statement be executed. The format is the same as +shown for `ENDO_DELIVERY_BREAKPOINTS` above, but the breakpoint happens +when and where the message is sent, rather than when and where it is delivered. + ## END_BLOCK_SPIN_MS Affects: cosmic-swingset @@ -106,6 +145,14 @@ Lifetime: until chain is mature enough not to need any pretend tokens For the environment variables beginning with `LOCKDOWN_` , see [`lockdown` Options](https://github.com/endojs/endo/blob/master/packages/ses/docs/lockdown.md). +## ONLY_WELL_FORMED_STRINGS_PASSABLE + +As part of the OCapN standards process, we have agreed that only so-called +"well formed" unicode strings should be considered `Passable`. However, we are +not yet confident about the performance impact of enforcing this ban, so it +is `"disabled"` by default for now. To turn it on, set this option to `"enabled"`. +See https://github.com/endojs/endo/blob/master/packages/pass-style/NEWS.md#v130-2024-03-19 for more explanation. + ## OTEL_EXPORTER_PROMETHEUS_PORT Affects: cosmic-swingset