bridge

Overview ¶

Command bridge is the cgo c-shared boundary that exposes dotvault's public client API (github.com/goodtune/dotvault/client) to non-Go runtimes — today, the Python package under python/. It is built with

go build -buildmode=c-shared -o _dotvault.<ext> ./python/bridge

and loaded via ctypes. It imports ONLY the public client package, never any internal/* package, so the same single-source-of-truth boundary the Go facade enforces holds for the Python surface too: token precedence, the OS-user identity convention, and the kv/users/<user>/... layout all come from the one Go implementation rather than being re-derived in Python.

Scope is the read-only + cached-auth subset of the facade plus the peer-action surface: AuthenticateCached (never prompts), IdentityName, Token, ReadKVField, ReadUserSecret, and the socket-forwarded Browse/Notify/Clipboard. Interactive Login/Authenticate (browser/terminal) are out — driving an OIDC browser pop or an LDAP password prompt across an FFI boundary from inside a Python process is awkward and is not what a library caller wants; such callers should rely on a token already provisioned by the daemon or `dotvault login`. Browse/Notify/Clipboard need no local token — they post over the peer socket — so they are in scope: a headless Python program hands a URL, a notification, or a clipboard value (a token to paste into an opened page) back to the workstation over the same forwarded socket it borrows tokens from.

ABI conventions ¶

• A *client.Client lives entirely on the Go side. The C ABI never sees a Go pointer (cgo forbids passing Go pointers that themselves contain Go pointers to C); instead clients are kept in a handle table and addressed by an opaque int64 handle. 0 is never a valid handle and signals failure.
• Strings cross out via *C.char allocated with C.CString (malloc). The caller OWNS every non-nil out string and MUST release it with dotvault_free. Strings cross in as NUL-terminated *C.char and are copied immediately; the bridge never retains them.
• Fallible calls return an int category code (see the cat* constants, which the Python layer mirrors) and, on a non-OK code, set *errOut to an owned message string. catOK leaves *errOut nil.
• Network calls take a timeoutMillis; <= 0 means no deadline (context.Background), matching the facade's own background-context calls.