openc3 7.3.0 → 7.4.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 787269f06fae8562e23d790d3c4887e2f913841dc818570fdafa06b29fd1b8e6
-  data.tar.gz: c6630dbc9c61bf71f96015db09ca9246ef80247f4f1b5de429c97b537551c4e4
+  metadata.gz: 3d94ef0547084256ba519d150e9e7637fe2623ad68703fb56ff43579ceb1119b
+  data.tar.gz: bb907222d40154d622e73fb8732ff2715186183f5ce097f58832839ea3621fb3
 SHA512:
-  metadata.gz: b72db91c6fd2febea1855d452a30e496b33bc5c19010ebc674ef044fea01d8cff1c921abcee824c39f32434e66fa9b4ed040bc1f164e9ea7cec99be431aec03a
-  data.tar.gz: 0ffeaa70a064e4d23cd49326e87b85e4eafefd0d4fa61a3db60fc503a8e48593c349588f4f28e374f4c7ba87408a66c072e822101f689bfc58cb3bcf567af966
+  metadata.gz: d59f2a554a6fd751533736e12088e85958e9fe8569ccc2ffde017e68c00626b39ddd7f08334e9e9f83fa47a599b8c0a803c0da248b945a7dff3f8e41a41085cc
+  data.tar.gz: 54c6fc8f881f6ccfef18dd8e37ebbe99b078e199f95738b9f6da5d24183d279252a9ee563c2be338d4f4e2cf32bb0299b4761727b40ffb5f771e354ba3877538

data/Gemfile

@@ -1,6 +1,6 @@
 # encoding: ascii-8bit
 
-source ENV['RUBYGEMS_URL'] || "https://rubygems.org"
+source "https://rubygems.org"
 
 gemspec :name => 'openc3'
 

data/bin/openc3cli

@@ -20,6 +20,7 @@
 
 require 'openc3'
 require 'openc3/bridge/bridge'
+require 'openc3/models/bridge_model'
 require 'openc3/models/gem_model'
 require 'openc3/models/migration_model'
 require 'openc3/models/plugin_model'
@@ -78,6 +79,7 @@ def print_usage
   puts "  cli xtce_converter                # Convert to and from the XTCE format. Run with --help for more info."
   puts "  cli cstol_converter               # Converts CSTOL files (.prc) to COSMOS. Run with --help for more info."
   puts "  cli setpassword                   # Set the initial password from OPENC3_API_PASSWORD env var"
+  puts "  cli initsettings                  # Seed settings from OPENC3_SETTING_* env vars"
   puts "  cli migratetouv PLUGIN_NAME SCOPE # Migrate plugin to per-plugin UV virtual environment"
   puts ""
 end
@@ -1269,6 +1271,42 @@ if not ARGV[0].nil? # argument(s) given
     params = [] unless params
     run_bridge(filename, params)
 
+  when 'bridgeenroll'
+    if ARGV[1].nil? || ARGV[1] == '--help' || ARGV[1] == '-h'
+      puts "Usage: cli bridgeenroll BRIDGE_NAME APP_PUBLIC_KEY [SCOPE]"
+      puts ""
+      puts "Authorize an openc3-app control identity for a bridge (Iroh hub) and"
+      puts "print that bridge's current connection ticket. Used by openc3-app to"
+      puts "auto-enroll over the local Docker control plane: the bridge then only"
+      puts "accepts api/* control connections from the given app identity."
+      puts ""
+      puts "Arguments:"
+      puts "  BRIDGE_NAME       Name of the bridge (hub)"
+      puts "  APP_PUBLIC_KEY    openc3-app's Iroh public key (EndpointId, hex)"
+      puts "  SCOPE             Scope (optional, default: OPENC3_SCOPE or DEFAULT)"
+      puts ""
+      puts "On success the bridge ticket is printed alone on stdout."
+      exit 0
+    end
+    bridge_name = ARGV[1].to_s.upcase
+    app_public_key = ARGV[2]
+    abort("APP_PUBLIC_KEY is required (see --help)") if app_public_key.nil? || app_public_key.empty?
+    unless app_public_key.match?(/\A[0-9a-f]{64}\z/i)
+      abort("APP_PUBLIC_KEY must be exactly 64 hexadecimal characters")
+    end
+    app_public_key = app_public_key.downcase
+    scope = ARGV[3] || ENV['OPENC3_SCOPE'] || 'DEFAULT'
+    model = OpenC3::BridgeModel.get_model(name: bridge_name, scope: scope)
+    abort("Bridge '#{bridge_name}' not found in scope #{scope}. Is its bridge_microservice running?") unless model
+    if model.ticket.nil? || model.ticket.empty?
+      abort("Bridge '#{bridge_name}' has no ticket yet. Is its bridge_microservice running?")
+    end
+    old_app_public_key = model.app_public_key
+    model.app_public_key = app_public_key
+    model.update
+    # Print ONLY the ticket so openc3-app can capture it from stdout.
+    puts model.ticket
+
   when 'bridgegem'
     if ARGV[1].nil? || ARGV[1] == '--help' || ARGV[1] == '-h'
       puts "Usage: cli bridgegem GEM_NAME [PARAMS...]"
@@ -1492,6 +1530,106 @@ if not ARGV[0].nil? # argument(s) given
     # Always ensure the scriptrunner policy is in place since it is required for script execution
     client.ensure_scriptrunner_policy(ENV['OPENC3_CONFIG_BUCKET'], ENV['OPENC3_LOGS_BUCKET'])
 
+  when 'initsettings'
+    if ARGV[1] == '--help' || ARGV[1] == '-h'
+      puts "Usage: cli initsettings [--dry-run | --export]"
+      puts ""
+      puts "Seed COSMOS settings from the environment. A setting changed in the Admin"
+      puts "Console is left alone, so those edits survive a restart."
+      puts ""
+      puts "Environment:"
+      puts "  OPENC3_SETTING_<NAME>          One variable per setting, e.g."
+      puts "                                 OPENC3_SETTING_TIME_ZONE=UTC sets 'time_zone'"
+      puts "  OPENC3_SETTINGS_OVERWRITE      true to overwrite existing settings on every"
+      puts "                                 run. false/unset leaves them alone"
+      puts "  OPENC3_SETTINGS_ALLOW_UNKNOWN  true to allow setting names COSMOS doesn't"
+      puts "                                 recognize. Without it an unknown name is"
+      puts "                                 reported and skipped, so a typo can't"
+      puts "                                 silently do nothing"
+      puts "  OPENC3_SETTINGS_STRICT         true to exit non-zero when a setting is"
+      puts "                                 rejected. Off by default"
+      puts ""
+      puts "These three accept true/false (1/0 also work)."
+      puts ""
+      puts "A setting that already exists is left alone because an operator may have"
+      puts "edited it in the Admin Console. Settings written by a release before this"
+      puts "command existed carry no record of having been seeded, so they all count as"
+      puts "edited: on such an upgrade run one init with OPENC3_SETTINGS_OVERWRITE=true"
+      puts "to adopt the environment values, then turn it back off."
+      puts ""
+      puts "An unrecognized name, an invalid value, or a malformed one of the variables"
+      puts "above is reported on stdout and that one setting is skipped; init continues"
+      puts "and COSMOS uses the default. Nothing here fails init unless"
+      puts "OPENC3_SETTINGS_STRICT is set. Use --dry-run to check the same things before"
+      puts "starting COSMOS, where a non-zero exit is what you want."
+      puts ""
+      puts "Settings that can be seeded:"
+      OpenC3::SettingModel.describe_settings.each { |line| puts "  #{line}" }
+      puts ""
+      puts "Boolean settings accept true/false (1/0 also work) and are stored as real"
+      puts "booleans."
+      puts "Every other setting is stored as the text given, including the settings"
+      puts "whose text is JSON (astro, classification_banner, context_tag)."
+      puts ""
+      puts "JSON settings - shape of each blob:"
+      OpenC3::SettingModel.describe_json_settings.each do |name, example|
+        puts "  #{name}"
+        puts "    #{example}"
+      end
+      puts ""
+      puts "Rather than hand-writing one of those, configure it in Admin -> Settings"
+      puts "and run 'cli initsettings --export' to print the current values as lines"
+      puts "you can paste straight into compose.override.yaml."
+      puts ""
+      puts "Options:"
+      puts "      --dry-run     Report what would be seeded and exit without writing."
+      puts "                    Lists every problem rather than stopping at the first,"
+      puts "                    and works before Redis is up so it can be run ahead of"
+      puts "                    starting COSMOS. Exits non-zero if anything would fail,"
+      puts "                    regardless of OPENC3_SETTINGS_STRICT"
+      puts "      --export      Print the settings currently stored as compose"
+      puts "                    'environment:' lines, quoted so the JSON ones parse."
+      puts "                    Configure in Admin -> Settings, then export and paste."
+      puts "                    Reads Redis, so COSMOS must be running - unlike"
+      puts "                    --dry-run, which works while it is down"
+      puts "  -h, --help        Show this help message"
+      exit 0
+    end
+    dry_run = ARGV[1] == '--dry-run'
+    export = ARGV[1] == '--export'
+    if ARGV[1] and !dry_run and !export
+      abort "Unknown option #{ARGV[1]}. See 'cli initsettings --help'"
+    end
+    if export
+      # --export reads the stored values, so it needs a reachable Redis. Say so
+      # plainly - the raw connection error is something like
+      # "Bad file descriptor (redis://openc3-redis:6379)", which doesn't hint
+      # that the answer is to start COSMOS.
+      unless OpenC3::SettingModel.redis_available?
+        abort "Cannot reach Redis at #{ENV['OPENC3_REDIS_HOSTNAME']}:#{ENV['OPENC3_REDIS_PORT']}.\n" \
+              "--export reads the settings currently stored, so COSMOS has to be running.\n" \
+              "Start it with './openc3.sh run', or use --dry-run, which works while COSMOS is down."
+      end
+      begin
+        lines = OpenC3::SettingModel.export_lines
+      rescue => e
+        abort "Error reading settings: #{e.message}"
+      end
+      if lines.empty?
+        puts "# No settings are stored yet - configure them in Admin -> Settings first"
+      else
+        puts "# Paste under the openc3-cosmos-init service's \"environment:\" key in"
+        puts "# compose.override.yaml, keeping this indentation."
+        lines.each { |line| puts "      #{line}" }
+      end
+    else
+      begin
+        OpenC3::SettingModel.apply_defaults(dry_run: dry_run)
+      rescue => e
+        abort "Error applying default settings: #{e.message}"
+      end
+    end
+
   when 'runmigrations'
     if ARGV[1] == '--help' || ARGV[1] == '-h'
       puts "Usage: cli runmigrations"

data/bin/uvinstall

@@ -75,8 +75,12 @@ if [ -f "${GEM_PATH}/uv.lock" ] && [ -f "${GEM_PATH}/pyproject.toml" ]; then
     cd "${VENV_BASE}"
     uv venv "${VENV_DIR}" --allow-existing
 
-    # Offline sync first, online only on a cache miss (bounded by UV_HTTP_*)
-    uv_offline_then_online sync --frozen --no-dev --no-install-project ${UV_ARGS}
+    # Offline sync first, online only on a cache miss (bounded by UV_HTTP_*).
+    # --inexact keeps sync additive: without it sync makes the venv match the
+    # lock exactly and uninstalls anything else, including packages an admin
+    # uploaded into this plugin venv via PythonPackageModel.install (which uses
+    # the additive `pipinstall`).
+    uv_offline_then_online sync --frozen --inexact --no-dev --no-install-project ${UV_ARGS}
     RESULT=$?
 
     if [ $RESULT -eq 0 ]; then
@@ -99,7 +103,10 @@ if [ -f "${GEM_PATH}/requirements.txt" ]; then
     RESULT=$?
 elif [ -f "${GEM_PATH}/pyproject.toml" ]; then
     echo "Installing from pyproject.toml via uv pip install"
-    uv_offline_then_online pip install --python "${VENV_DIR}" ${UV_ARGS} "${GEM_PATH}"
+    # --python: The Python interpreter into which packages should be installed.
+    # --project: Discover a project (i.e. pyproject.toml) in the given directory.
+    # -r: Install the packages listed in the given files.
+    uv_offline_then_online pip install --python "${VENV_DIR}" --project "${GEM_PATH}" ${UV_ARGS} -r "${GEM_PATH}/pyproject.toml"
     RESULT=$?
 
     # `uv pip install <path>` builds the plugin as a package before installing

data/data/config/command_modifiers.yaml

@@ -284,6 +284,8 @@ TEMPLATE_FILE:
     - name: Template File Path
       required: true
       description: The relative path to the template file. Filename should generally start with an underscore.
+        Absolute paths and paths containing '..' are not allowed. The file must be inside the directory
+        containing the definition file.
       values: .+
   since: 5.0.10
 RESPONSE:

data/data/config/interface_modifiers.yaml

@@ -168,7 +168,7 @@ SECRET:
   summary: Define a secret needed by this interface
   description:
     Defines a secret for this interface and optionally assigns its value to an option.
-    For more information see [Admin Secrets](/docs/tools/admin#secrets).
+    For more information see the [Secrets guide](/docs/guides/secrets) and [Admin Secrets](/docs/tools/admin#secrets).
   since: 5.3.0
   parameters:
     - name: Type
@@ -186,6 +186,8 @@ SECRET:
     - name: Environment Variable or File Path
       required: true
       description: Environment variable name or file path to store secret.
+        FILE paths must be under /tmp (or the directory set by the
+        OPENC3_SECRET_FILE_DIR environment variable); paths outside of it are rejected.
         Note that if you use the Option Name to set an option to the secret value,
         this value doesn't really matter as long as it is unique.
       values: .*
@@ -284,3 +286,103 @@ SHARD:
       values: \d+
   example: |
     SHARD 0
+BRIDGE:
+  summary: Name of the bridge to run this interface on
+  description: Run this interface on a bridge host rather than within COSMOS. Note only python is supported.
+  since: 7.4.0
+  parameters:
+    - name: Bridge Name
+      required: true
+      description: Bridge Name - Typically DEFAULT
+      values: .+
+  example: |
+    BRIDGE DEFAULT
+BRIDGE_PROTOCOL:
+  summary: Bridge Protocols modify the bridge interface by processing the data
+  description:
+    Protocols can be either READ, WRITE, or READ_WRITE. READ protocols act on the data
+    received by the interface while write acts on the data before it is sent out. READ_WRITE applies
+    the protocol to both reading and writing.<br/><br/>
+    For information on creating your own custom protocol please see [Protocols](../configuration/protocols.md)
+  since: 7.4.0
+  parameters:
+    - name: Type
+      required: true
+      description: Whether to apply the protocol on incoming data, outgoing data, or both
+      values: ["READ", "WRITE", "READ_WRITE"]
+    - name: Protocol Filename or Classname
+      required: true
+      description: Ruby or Python filename or class name which implements the protocol
+      values: .*
+    - name: Protocol specific parameters
+      required: false
+      description: Additional parameters used by the protocol
+  python_example: |
+    INTERFACE DATA_INT openc3/interfaces/tcpip_client_interface.py host.docker.internal 8080 8081 10.0 nil BURST
+      MAP_TARGET DATA
+      BRIDGE_PROTOCOL READ openc3/interfaces/protocols/ignore_packet_protocol.py INST IMAGE # Drop all INST IMAGE packets
+BRIDGE_OPTION:
+  summary: Set a parameter on a bridged interface
+  description:
+    When a bridge option is set the bridge interface class calls the set_option method.
+    Custom interfaces can override set_option to handle any additional options they want.
+  since: 7.4.0
+  parameters:
+    - name: Name
+      required: true
+      description:
+        The option to set. OpenC3 defines several options on the core provided
+        interfaces. The SerialInterface defines FLOW_CONTROL which can be NONE (default) or RTSCTS
+        and DATA_BITS which changes the data bits of the serial interface.
+        The TcpipServerInterface and HttpServerInterface define LISTEN_ADDRESS which is the IP address to accept
+        connections on (default 0.0.0.0).
+      values: .*
+    - name: Parameters
+      required: false
+      description: Parameters to pass to the option
+      values: .*
+  example: |
+    INTERFACE SERIAL_INT serial_interface.rb COM1 COM1 115200 NONE 1 10.0 nil
+      BRIDGE DEFAULT
+      BRIDGE_OPTION FLOW_CONTROL RTSCTS
+      BRIDGE_OPTION DATA_BITS 8
+BRIDGE_SECRET:
+  summary: Define a bridge secret needed by this bridge interface
+  description:
+    Defines a bridge secret for this bridge interface and optionally assigns its value to an option.
+    For more information see [Admin Secrets](/docs/tools/admin#secrets).
+  since: 7.4.0
+  parameters:
+    - name: Type
+      required: true
+      description:
+        ENV or FILE.  ENV will mount the secret into an environment variable.
+        FILE mounts the secret into a file.
+      values: .*
+    - name: Secret Name
+      required: true
+      description:
+        The name of the secret to retrieve from the Admin / Secrets tab.
+        For more information see [Admin Secrets](/docs/tools/admin#secrets).
+      values: .*
+    - name: Environment Variable or File Path
+      required: true
+      description: Environment variable name or file path to store secret.
+        FILE paths must be under /tmp (or the directory set by the
+        OPENC3_SECRET_FILE_DIR environment variable); paths outside of it are rejected.
+        Note that if you use the Option Name to set an option to the secret value,
+        this value doesn't really matter as long as it is unique.
+      values: .*
+    - name: Option Name
+      required: false
+      description: Interface option to pass the secret value. This is the primary way to pass secrets to interfaces.
+      values: .*
+    - name: Secret Store Name
+      required: false
+      description: Name of the secret store for stores with multipart keys
+      values: .*
+  example: |
+    INTERFACE SERIAL_INT serial_interface.rb COM1 COM1 115200 NONE 1 10.0 nil
+      BRIDGE DEFAULT
+      BRIDGE_SECRET ENV USERNAME ENV_USERNAME USERNAME
+      BRIDGE_SECRET FILE KEY "/tmp/DATA/cert" KEY

data/data/config/microservice.yaml

@@ -118,7 +118,8 @@ MICROSERVICE:
     SECRET:
       summary: Define a secret needed by this microservice
       description:
-        Defines a secret for this microservice. For more information see [Admin Secrets](/docs/tools/admin#secrets).
+        Defines a secret for this microservice. For more information see the [Secrets guide](/docs/guides/secrets)
+        and [Admin Secrets](/docs/tools/admin#secrets).
         Note that unlike the INTERFACE SECRET, the microservice SECRET does not take an Option Name parameter,
         because the secret value is injected directly into the microservice process as an environment variable
         (Type ENV) or written to a file (Type FILE).
@@ -138,7 +139,9 @@ MICROSERVICE:
           values: .*
         - name: Environment Variable or File Path
           required: true
-          description: Environment variable name or file path to store secret
+          description: Environment variable name or file path to store secret.
+            FILE paths must be under /tmp (or the directory set by the
+            OPENC3_SECRET_FILE_DIR environment variable); paths outside of it are rejected.
           values: .*
         - name: Secret Store Name
           required: false

data/data/config/telemetry_modifiers.yaml

@@ -274,6 +274,8 @@ TEMPLATE_FILE:
     - name: Template File Path
       required: true
       description: The relative path to the template file. Filename should generally start with an underscore.
+        Absolute paths and paths containing '..' are not allowed. The file must be inside the directory
+        containing the definition file.
       values: .+
   since: 5.0.10
 IGNORE_OVERLAP:

data/data/config/widgets.yaml

@@ -206,6 +206,9 @@ Decoration Widgets:
         END
     FILEDISPLAY:
       summary: Displays the contents of a target file with syntax highlighting
+      description: Files are read from the COSMOS bucket, either the target's installed files or the modified
+        copy under targets_modified. In local mode a file created only on the local filesystem
+        (plugins/SCOPE/targets_modified) is not in the bucket and cannot be read.
       since: 6.10.3
       parameters:
         - name: File path
@@ -224,6 +227,9 @@ Decoration Widgets:
         FILEDISPLAY "INST/data/sample.json" 400 200
     FILECHECKSUM:
       summary: Displays SHA-256 checksum of one or more files, with comparison if multiple
+      description: Files are read from the COSMOS bucket, either the target's installed files or the modified
+        copy under targets_modified. In local mode a file created only on the local filesystem
+        (plugins/SCOPE/targets_modified) is not in the bucket and cannot be read.
       since: 6.10.3
       parameters:
         - name: File path

data/ext/openc3/ext/burst_protocol/burst_protocol.c

@@ -23,6 +23,7 @@ static ID id_method_reduce_to_single_packet = 0;
 static ID id_method_replace = 0;
 static ID id_method_clone = 0;
 static ID id_method_log_discard = 0;
+static ID id_method_check_buffer_size = 0;
 
 static ID id_ivar_data = 0;
 static ID id_ivar_extra = 0;
@@ -77,6 +78,10 @@ static VALUE burst_protocol_read_data(int argc, VALUE *argv, VALUE self)
 
   rb_str_concat(rb_ivar_get(self, id_ivar_data), data);
 
+  /* Bound the memory a peer can make us buffer. Raises if @data has grown
+   * past @max_buffer_size, which makes Interface#read disconnect the peer. */
+  rb_funcall(self, id_method_check_buffer_size, 0);
+
   /* Maintain extra from last read read_data */
   if (!((RSTRING_LEN(data) == 0) && (!(RTEST(extra))))) {
     rb_ivar_set(self, id_ivar_extra, extra);
@@ -301,6 +306,7 @@ void Init_burst_protocol(void)
   id_method_replace = rb_intern("replace");
   id_method_clone = rb_intern("clone");
   id_method_log_discard = rb_intern("log_discard");
+  id_method_check_buffer_size = rb_intern("check_buffer_size");
 
   id_ivar_data = rb_intern("@data");
   id_ivar_extra = rb_intern("@extra");

data/ext/openc3/ext/platform/platform.c

@@ -35,10 +35,13 @@ VALUE cSegFault = Qnil;
 #include <string.h>
 #include <sys/stat.h>
 
+/* Must be a macro rather than a const int so filename below is a fixed size
+ * array rather than a variable length array */
+#define FILENAME_LEN 256
+
 /* Mark that this function does not return (it exits) to remove compiler warning */
 __attribute__((noreturn)) static void catch_sigsegv(int sig_num)
 {
-  const int FILENAME_LEN = 256;
   char *openc3_log_dir = NULL;
   time_t rawtime;
   struct tm timeinfo;