magmalake flare_mlake

flare_mlake · API · utils

flare.utils.dylib

Canonical FFI dylib path resolver shared across :mod:flare.

Consolidates the per-package FFI-lib finders: every package that owned a C-side helper carried its own _find_flare_*_lib helper -- 7 callers, 4 lookalike implementations of the same CONDA_PREFIX / bare-checkout fallback search. Different return values for "library not present" ("build/libflare_X.so" vs "libflare_X.so"); identical search order otherwise.

This module is the single canonical home. Each call site that opens a flare-bundled shared object goes through :func:find_flare_lib; the bundled shim's name (the X in libflare_X.so) is the only argument.

Library naming convention

flare bundles four FFI shims under $CONDA_PREFIX/lib/:

  • libflare_tls.so -- OpenSSL hooks (TLS handshake, AEAD, hkdf, hmac, sha1) plus the flare_read / flare_write thin wrappers used by the io_uring reactor's hot path.
  • libflare_zlib.so -- zlib + gzip + raw-deflate thin wrappers consumed by :mod:flare.http.encoding (HTTP Content-Encoding) and :mod:flare.ws.permessage_deflate (WebSocket permessage-deflate).
  • libflare_brotli.so -- libbrotlienc + libbrotlidec consumed by :mod:flare.http.encoding for Content-Encoding: br.
  • libflare_fs.so -- access(2) + open(2) + read(2) + close(2) thin wrappers consumed by :mod:flare.http.fs (FileServer static-file path).

Search order (used by every call site):

  1. $FLARE_LIB_DIR/libflare_<name>.so -- when FLARE_LIB_DIR is an absolute path; for running outside pixi.
  2. $CONDA_PREFIX/lib/libflare_<name>.so -- the canonical install location, populated by flare/<sub>/ffi/build.sh on pixi activation.
  3. <exe dir>/libflare_<name>.so and <exe dir>/../lib/..., the running executable's directory (symlinks resolved) -- for a binary shipped next to its libraries.
  4. The bare libflare_<name>.so, which dlopen resolves on the binary's rpath (mojo build records the lib directory of the environment it built in) and then the system library path. Never the working directory.

Steps 2-4 are :func:flare.utils._dlopen.find_library, the search every magmalake tin that loads a library shares; each of 2 and 3 is taken only when the file is there. The path is built via String("") += prefix += literal rather than the prefix + literal concat operator. See the :mod:flare.tls.config module docstring for the full rationale (Mojo's concat can return a String whose buffer aliases another getenv + literal result, so two sequential CONDA_PREFIX + ... calls can clobber each other's bytes).

Public API

find_flare_lib(name: String) -> String Resolves libflare_<name>.so in the order above. name is the bare suffix ("tls", "zlib", "brotli", "fs").

dl_sym[FT](lib: OwnedDLHandle, name: String) raises -> FT Resolve a C-ABI function symbol. OwnedDLHandle.get_function returns an origin-bound _DLCallable that cannot be called or stored the way plain function pointers used to be; get_symbol + address reinterpret is the replacement every FFI call site across :mod:flare now shares.

Functions

dl_sym

def dl_sym[FT: TrivialRegisterPassable](lib: OwnedDLHandle, name: String) -> FT

Look up a C-ABI function symbol as a plain callable value.

Replaces the lib.get_function[FT](name) idiom, whose return type (an origin-bound _DLCallable) can no longer be invoked directly or stored across scopes.

find_flare_lib

def find_flare_lib(name: String) -> String

Return the path to libflare_<name>.so.

Search order:

  1. $FLARE_LIB_DIR/libflare_<name>.so, when FLARE_LIB_DIR is an absolute path. For running outside pixi, e.g. a bare checkout with FLARE_LIB_DIR=$PWD/build.
  2. $CONDA_PREFIX/lib/libflare_<name>.so, when CONDA_PREFIX is absolute and the file is there: the install that flare/<sub>/ffi/build.sh populates on pixi activation.
  3. <exe dir>/libflare_<name>.so, then <exe dir>/../lib/libflare_<name>.so, when there.
  4. The bare file name, which dlopen looks up on the binary's rpath (the environment mojo build ran in, so a binary built under pixi runs from a plain shell), LD_LIBRARY_PATH / DYLD_LIBRARY_PATH and the system directories. It never looks in the working directory.

The last step used to be build/libflare_<name>.so, relative to the working directory. A flare program started with no CONDA_PREFIX from a directory someone else could write to (a shared /tmp, a checked-out repository) loaded whatever build/libflare_tls.so it found there, and ran that code with the program's privileges.

Args
name: The bare suffix, e.g. "tls" for libflare_tls.so.

pinned_flare_lib

def pinned_flare_lib[name: StringSpan[ImmStaticOrigin]]() -> Pointer[OwnedDLHandle, MutUntrackedOrigin]

The process-wide handle to libflare_<name>.so, opened once.

A per-call OwnedDLHandle costs a dlopen, symbol lookups and a dlclose under the loader lock every worker shares, and unmaps the library between calls when nothing else holds it. This one is opened on first use and never closed.

Raises Error: If the library cannot be loaded.