ActionCore

English | 繁體中文 | 简体中文

je_action_core is the keyword-driven action executor shared by APITestka, LoadDensity, MailThunder and FileAutomation. Each of them carried its own copy of the same executor, package manager, callback executor, action-file reader and socket server. This package replaces those copies: a project configures it with its own command prefix, document key, exceptions and messages.

It has no dependencies and supports Python 3.10 to 3.14.

Contents

• Installation
• Actions
• Quick start
• The pieces
• Package gate
• Socket server protocol
• Who uses it
• Development
• License

Installation

pip install je_action_core

A framework that is built on it installs it as a dependency.

Actions

An action list is a JSON list of actions, or a document that keeps the list under one key ({"api_testka": [...]}). Each action takes one of three forms:

Running a list returns one record per action: the command's return value, or repr(error) when it raised. One failing action does not stop the rest.

Quick start

from je_action_core import (
    ActionExecutor, ActionListRules, CommandPolicy, CommandRegistry, ExecutorSettings, LoggingReporter,
)
import logging

registry = CommandRegistry({"MY_add": lambda a, b: a + b}, policy=CommandPolicy.FUNCTIONS_ONLY)
executor = ActionExecutor(
    ExecutorSettings(rules=ActionListRules("my_tool"), reporter=LoggingReporter(logging.getLogger("my_tool"))),
    registry,
)

executor.execute_action({"my_tool": [["MY_add", [1, 2]], ["MY_add", {"a": 3, "b": 4}]]})
# {"execute: ['MY_add', [1, 2]]": 3, "execute: ['MY_add', {'a': 3, 'b': 4}]": 7}

The pieces

__all__ in je_action_core/__init__.py is the supported import surface.

Package gate

PackageManager.add_package_to_executor imports a package and registers its members as commands. An action list that can name os or subprocess could therefore run anything. The host program decides what may load:

package_manager.allow_packages("my_helpers")          # these, and their submodules
package_manager.set_allow_arbitrary_packages(False)   # refuse everything else before importing it

Neither switch should ever be exposed as an action command, so an action list cannot open its own gate. A refused package raises the project's refused exception, which the executor records as that action's result. Until the host calls either switch, any package still loads but raises a DeprecationWarning. A project can turn the gate off (PackageGate.OFF) while it moves to it.

Socket server protocol

start_action_socket_server(host, port, settings, handler_class=ActionRequestHandler) serves on a daemon thread. A client sends one JSON action document per connection. The server replies with one line per record, then Return_Data_Over_JE. A failure replies with the error text and the same marker. quit_server stops the server and sets close_flag and close_event. What can be configured:

• Framing: Framing.RAW reads one 8 KiB recv, and OversizePolicy says what happens to a full buffer. Framing.LENGTH_PREFIX reads a 4-byte big-endian length, then the body (at most 1 MiB), and sends every reply line as its own frame.
• TLS: tls_context=server_tls_context(certfile, keyfile) wraps each connection (TLS 1.2 or later).
• Replies: ReplyMessages holds the templates for a record line, each failure stage (JSON, refused by validate, execution), an undecodable request, the quit reply, the authentication refusals and the log line.
• Authentication: the base handler has none. SecretHeaderRequestHandler requires a first line <auth_prefix><secret>. EnvelopeTokenRequestHandler accepts {"token": ..., "command": ...} and {"token": ..., "op": "quit"}. Both compare secrets in constant time.

Without authentication, bind the server only to a trusted interface.

Who uses it

APITestka (AT_, port 9939), LoadDensity (LD_), MailThunder (MT_, port 9942) and FileAutomation (FA_) are the projects this package is for. architecture.md §6 lists which of them have moved to it and which pieces and settings each one uses. All four run their TCP servers on socket_server: LoadDensity with the JSON-envelope token, framing and TLS, FileAutomation with the AUTH header and its ACL.

n and an ACL.

Development

pip install -e .
pip install pytest
python -m pytest test/

architecture.md describes the layers and the contracts with the four projects. Outstanding work is in progress.md, and finished work is recorded in docs/updates/.

License

MIT, see LICENSE.