dohertj2/wwtools
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

mxaccesscli: document session-scoped userId semantics

Browse Source 
Replaces the "Reusing a userId" subsection with a clearer
"userId is session-scoped" note that captures the actual
GRAccess/MxAccess contract:

- AuthenticateUser returns an int that is bound to the LMX session
  hServer it was issued against, exactly like tag handles from
  AddItem. When the session unregisters (i.e. the MxSession is
  disposed, which happens when the process exits) the userId is
  no longer valid.
- Each mxa write invocation creates a fresh MxSession, so an
  authenticated write must include --username/--password (or a
  userId resolved within the current process).
- --user-id <N> is a hand-off for in-process callers, not a
  persistable credential.

This matches the user's observation that userIds behave like
tag/item handles in scope, and explains why batch flows benefit
from a future session-mode mxa daemon (modeled on graccesscli's
session) that holds one MxSession across many commands.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
This commit is contained in:
Joseph Doherty
2026-05-03 22:17:34 -04:00
parent 9de8660688
commit a842f67b54
1 changed files with 10 additions and 2 deletions
Download Patch File Download Diff File Expand all files Collapse all files
mxaccesscli/docs/usage.md
+10 -2
View File
@@ -151,9 +151,17 @@ This affects how System Platform records the action in the alarm/event subsystem
On a permissive galaxy (the development config used here), every action maps to `DefaultUser` regardless of advise variant — the mechanism is wired correctly but can't be differentiated until galaxy security is configured with real users. See [`Authentication`](#authentication) above.
### Reusing an already-resolved `userId`
### `userId` is session-scoped
`AuthenticateUser` may be expensive (involves SQL Server lookup + Windows cred check). For batch scripts that issue many writes, call `AuthenticateUser` once via a manual call, capture the `userId`, then pass it directly via `--user-id <N>` to subsequent `write` invocations. This skips the per-call auth round-trip.
The integer `userId` returned by `AuthenticateUser(hServer, ...)` is bound to the **LMX session** identified by `hServer` — the same way tag handles from `AddItem` are. Once the session unregisters (i.e. the `MxSession` is disposed, which happens when the process exits) the userId is no longer valid. There is no portable, long-lived "user id" you can persist across `mxa` invocations.
Practical implications for the CLI:
- **Each `mxa write` invocation** creates a fresh `MxSession`, so an authenticated write must include `--username` / `--password` (or pass a userId that was already resolved within the **current** process).
- **Within a single process** (e.g. a future `mxa session start` daemon, or a calling script that wraps multiple commands in one MxSession), `AuthenticateUser` is called once and the same `userId` can flow into many subsequent `Write` calls.
- **The `--user-id <N>` flag** is only useful when you're operating inside a session you already authenticated against — typically not from a one-shot `mxa write`. Treat it as a hand-off for in-process callers, not as a persistable credential.
`AuthenticateUser` itself is moderately expensive (SQL Server lookup + OS credential check). The CLI's per-invocation cost is dominated by the LMX bind / type-resolution stage, not by the auth round-trip — so re-authenticating on each `mxa write` is acceptable for interactive use. A future session-mode `mxa` would amortize it.
## `mxa subscribe <tag> [<tag>...]`