|
| 1 | +package python.multiplatform.env |
| 2 | + |
| 3 | +import python.multiplatform.ffi.Python3 |
| 4 | +import python.native.ffi.PyImport_ExecCodeModule |
| 5 | +import python.native.ffi.Py_CompileString |
| 6 | +import python.native.ffi.Py_DecRef |
| 7 | +import python.multiplatform.ffi.pyErrorOrGeneric |
| 8 | + |
| 9 | +/** |
| 10 | + * The dev agent (SPEC L-12, #233): a debug-only channel from a notebook or a hot reload into this |
| 11 | + * interpreter, designed in toolchain's `docs/design/live-connection.md` (option B). |
| 12 | + * |
| 13 | + * [Python3.initialize] calls [startIfRequested]. It does nothing unless the launcher set |
| 14 | + * [ENVIRONMENT_VARIABLE] (`port=<n>;token=<t>[;overlay=<dir>]`) **and** the app was built for it: one of |
| 15 | + * its installed payload roots ([PythonPayload.installed]) holds [ENABLE_MARKER]. Then the agent's Python |
| 16 | + * ([DEV_AGENT_SOURCE], embedded from `src/commonMain/python/python_multiplatform_devagent.py`) is loaded as |
| 17 | + * the module [MODULE] and listens on 127.0.0.1 with that token, which must be at least 32 random bytes |
| 18 | + * (`secrets.token_urlsafe(32)`). A refused or malformed request is reported on stderr and does not stop the app. |
| 19 | + * |
| 20 | + * The marker is the build-time switch. This library is one artifact for an app's debug and release builds |
| 21 | + * alike, so a constant in it cannot tell them apart; the app's build can, and toolchain stages the marker |
| 22 | + * into a debug variant's payload only. Without it, a release build opens no port even if something starts |
| 23 | + * its process with the variable set: "a release launch never sets it" is the launcher's promise, which this |
| 24 | + * runtime does not rely on. |
| 25 | + */ |
| 26 | +internal object PythonDevAgent { |
| 27 | + const val ENVIRONMENT_VARIABLE = "PYTHON_MULTIPLATFORM_DEV_AGENT" |
| 28 | + const val MODULE = "python_multiplatform_devagent" |
| 29 | + const val ENABLE_MARKER = "python_multiplatform_devagent.enable" |
| 30 | + |
| 31 | + private const val PY_FILE_INPUT: Int = 257 |
| 32 | + private var loaded = false |
| 33 | + private var requested = false |
| 34 | + |
| 35 | + fun startIfRequested() { |
| 36 | + if (requested || readEnvVar(ENVIRONMENT_VARIABLE).isNullOrBlank()) return |
| 37 | + requested = true |
| 38 | + if (enabledRoot() == null) { |
| 39 | + println( |
| 40 | + "WARNING: python-multiplatform dev agent not started: $ENVIRONMENT_VARIABLE is set, but no " + |
| 41 | + "payload root holds $ENABLE_MARKER, so this is not a build made for it (a release build).", |
| 42 | + ) |
| 43 | + return |
| 44 | + } |
| 45 | + try { |
| 46 | + load() |
| 47 | + Python3.exec("__import__(\"$MODULE\").start_from_env()") |
| 48 | + } catch (e: Exception) { |
| 49 | + println("WARNING: python-multiplatform dev agent not started: ${e.message}") |
| 50 | + } |
| 51 | + } |
| 52 | + |
| 53 | + /** The installed payload root that holds [ENABLE_MARKER], if any. */ |
| 54 | + private fun enabledRoot(): String? = |
| 55 | + PythonPayload.installed.firstOrNull { pathIsAccessible("$it/$ENABLE_MARKER") } |
| 56 | + |
| 57 | + /** Loads [DEV_AGENT_SOURCE] as the module [MODULE] (once). */ |
| 58 | + fun load() { |
| 59 | + if (loaded) return |
| 60 | + Python3.withPython { |
| 61 | + val code = Py_CompileString(DEV_AGENT_SOURCE, "<python-multiplatform:devagent>", PY_FILE_INPUT) |
| 62 | + ?: throw pyErrorOrGeneric("Failed to compile the dev agent") |
| 63 | + try { |
| 64 | + val module = PyImport_ExecCodeModule(MODULE, code) |
| 65 | + ?: throw pyErrorOrGeneric("Failed to load the dev agent") |
| 66 | + Py_DecRef(module) |
| 67 | + } finally { |
| 68 | + Py_DecRef(code) |
| 69 | + } |
| 70 | + } |
| 71 | + loaded = true |
| 72 | + } |
| 73 | +} |
0 commit comments