Package 'safeinsights.fusion'

Decode a fusion table into a data frame

Description

Decode a fusion table into a data frame

Usage

fusion_as_data_frame(x)

Arguments

x	A fusion_response (from fusion_request()) whose body is a fusion table, or the decoded table body itself.

Value

A data frame with typed columns: string to character, integer to integer (double when a value exceeds the 32-bit range), integer64 to character, number to double, boolean to logical, date to Date, datetime to UTC POSIXct. null becomes NA. The column types travel as attr(, "fusion_types").

---

Last budget hint seen on a peer

Description

Last budget hint seen on a peer

Usage

fusion_budget(peer)

Arguments

peer	A fusion_peer.

Value

A fusion_budget (rounds and bytes used vs. max) or NULL before the first response.

---

Finish the analysis: send CLOSE to every leg

Description

Every leg is attempted. Legs that already ended report their terminal code.

Usage

fusion_complete(fusion)

Arguments

fusion

A fusion object.

Value

A named character vector of per-leg outcomes: "OK", a terminal code, or "ERROR". If any leg failed with a non-terminal error, that error is raised after all legs were tried.

---

Connect to the study's tunnel(s) as the destination

Description

Reads the environment contract (FUSION_ROLE, FUSION_TUNNEL_ENDPOINT(S), FUSION_TUNNEL_TOKEN(S)), waits for every leg to reach CHANNEL_UP, and returns a handle whose peers are keyed by the peer organization slug reported by each tunnel.

Usage

fusion_connect(
  env = Sys.getenv(),
  settings = NULL,
  ready_timeout = NULL,
  transports = NULL
)

Arguments

env	Environment variables; defaults to Sys.getenv().
settings	A fusion_settings() object; defaults to reading the ⁠FUSION_*⁠ knobs from env.
ready_timeout	Seconds to wait for CHANNEL_UP on all legs (default FUSION_READY_TIMEOUT_S).
transports	Advanced: a named list of transports to use instead of the environment (the simulator and tests).

Value

An object of class fusion.

---

Check the environment contract and each tunnel's ⁠/v1/info⁠

Description

Content-free: prints labels, hosts, leg ids, peer slugs, roles, states and API versions; never a token. Used by the Docker smoke and by researchers debugging a container.

Usage

fusion_doctor(env = Sys.getenv(), wait = FALSE, json = FALSE)

Arguments

env	Environment variables; defaults to Sys.getenv().
wait	If TRUE, wait for CHANNEL_UP up to FUSION_READY_TIMEOUT_S.
json	If TRUE, print a JSON report instead of text.

Value

TRUE when every tunnel is reachable, has the expected role and a compatible API (and is CHANNEL_UP when wait = TRUE); FALSE otherwise. Invisible.

---

Is this condition terminal for its peer?

Description

Is this condition terminal for its peer?

Usage

fusion_is_terminal(e)

Arguments

e	A condition object.

Value

TRUE for fusion_config_error, fusion_not_ready_error, fusion_limit_exceeded_error and fusion_session_error; FALSE otherwise.

---

Redirect SDK log lines

Description

By default the SDK writes one message() per event to stderr. Tests and embedding applications can capture the lines instead.

Usage

fusion_log_sink(sink = NULL)

Arguments

sink	A function of one character argument, or NULL to restore message().

Value

The previous sink, invisibly.

---

Declare an operation handler

Description

Declare an operation handler

Usage

fusion_operation(
  handler,
  person_id_param = NULL,
  cardinality = "aggregate",
  count_column = NULL,
  sanitize = FALSE
)

Arguments

handler	A function ⁠function(params, ctx)⁠ returning a JSON-able value, a data frame, or a fusion_table(). params is the query's named list; ctx has correlation_id, message_id, peer, operation, budget.
person_id_param	Name of the parameter whose distinct values maxDistinctPersonIds bounds. Its value must be absent, one scalar, or a flat array of scalars; other shapes are refused with GUARD_REFUSED before the handler runs.
cardinality	One of "aggregate", "per-group", "per-record" (the manifest's class).
count_column	For per-group operations, the result column holding group sizes. Required: minGroupSize is checked on that column only and the SDK never infers it from column types.
sanitize	If TRUE, a handler error crosses to the destination as class and one-line message only, instead of the full traceback (ADR 0005).

Value

An object of class fusion_operation.

---

Build the operation registry

Description

Build the operation registry

Usage

fusion_operations(...)

Arguments

...	Named fusion_operation() objects (bare functions are wrapped as aggregate operations).

Value

An object of class fusion_operations.

---

Get a peer handle

Description

Get a peer handle

Usage

fusion_peer(fusion, name = NULL)

Arguments

fusion	A fusion object from fusion_connect().
name	The peer organization slug. With one leg it may be omitted.

Value

A fusion_peer handle for fusion_request().

---

List peers

Description

List peers

Usage

fusion_peers(fusion)

Arguments

fusion

A fusion object.

Value

A data frame with columns peer, legId, direction, state.

---

Run one round: request an operation from a peer

Description

Blocks until the source's response arrives, a typed error is raised, or the round timeout (with the SDK's same-correlationId re-issues) is exhausted. Researcher code never sees a correlationId or a retransmission.

Usage

fusion_request(peer, operation, params = list(), timeout = NULL)

Arguments

peer	A fusion_peer from fusion_peer() (or a fusion object with a single peer).
operation	The Data-Partner-approved operation name.
params	A named list of parameters. Use I() or list() to force a length-1 vector to travel as a JSON array (for example person_ids = I("p-1")).
timeout	Per-attempt round timeout in seconds (default FUSION_ROUND_TIMEOUT_S).

Value

A fusion_response with ⁠$body⁠ (raw JSON as nested lists), ⁠$budget⁠, ⁠$operation⁠, ⁠$peer⁠, ⁠$correlation_id⁠, ⁠$message_id⁠, ⁠$bytes⁠, ⁠$duration_s⁠. Decode a table body with fusion_as_data_frame().

---

Serve registered operations until the study completes

Description

Blocks. Returns invisibly on STUDY_COMPLETE; signals fusion_limit_exceeded_error / fusion_session_error on a terminal error and fusion_config_error on a misconfigured environment or registry. A source serves exactly one tunnel. Source scripts should do nothing but fusion_serve() after setup: the long-poll loop blocks the R process by design.

Usage

fusion_serve(
  operations,
  env = Sys.getenv(),
  settings = NULL,
  ready_timeout = NULL,
  transport = NULL
)

Arguments

operations	A fusion_operations() registry.
env	Environment variables; defaults to Sys.getenv().
settings	A fusion_settings() object.
ready_timeout	Seconds to wait for CHANNEL_UP.
transport	Advanced: a transport to use instead of the environment (simulator, tests).

Value

NULL, invisibly.

---

Tuning settings

Description

Reads the ⁠FUSION_*⁠ knobs from an environment (default: the process environment). Every default is provisional until load-tested with the real tunnel.

Usage

fusion_settings(env = Sys.getenv())

Arguments

env	A named character vector of environment variables; defaults to Sys.getenv().

Value

A list of class fusion_settings.

---

Fault injection for fusion_simulate()

Description

Rounds are numbered from 1 per peer, as in the fake tunnel scenarios.

Usage

fusion_sim_faults(
  drop_response_rounds = integer(0),
  error_after_round = NULL,
  max_rounds = NULL,
  max_response_bytes_per_round = NULL
)

Arguments

drop_response_rounds	Rounds whose response is withheld until the SDK re-issues the same correlationId (exercises round-timeout handling with a short timeout).
error_after_round	The leg becomes SESSION_ERRORED after this round completes.
max_rounds	Cap on rounds enforced by the simulated source tunnel (LIMIT_EXCEEDED).
max_response_bytes_per_round	Cap on response bytes per round (LIMIT_EXCEEDED with cap = "maxResponsePlaintextBytesPerRound").

Value

An object of class fusion_sim_faults.

---

Run a fusion analysis in this process, with no tunnel

Description

Wires a source handler set and a destination analysis function together through an in-process transport, so researchers can develop and test fusion code against sample data in the IDE. The same guards, memo, error envelopes and typed errors apply as in a real study.

Usage

fusion_simulate(
  operations,
  analysis,
  guards = NULL,
  caps = NULL,
  approved_operations = NULL,
  faults = NULL,
  settings = NULL
)

Arguments

operations	A fusion_operations() registry (two-party; the peer is named "dp-sim") or a named list of registries, one per peer (hub).
analysis	A function of one argument, the connected fusion object, exactly as in a study.
guards	Optional list like list(maxDistinctPersonIds = 5000, minGroupSize = 11).
caps	Optional caps object as ⁠/v1/info⁠ would carry (informational).
approved_operations	Optional approved operation list for the registry pre-flight.
faults	A fusion_sim_faults() object, or a named list of them per peer.
settings	A fusion_settings() object; defaults to fast simulator settings.

Value

Whatever analysis returns. Every leg is closed on a clean return.

---

Build a fusion table from a data frame

Description

Column types are inferred from the R classes (character/factor to string, integer to integer, double to number, logical to boolean, Date to date, POSIXct to datetime, bit64::integer64 to integer64) unless overridden with types. NA, NaN and infinities encode as null.

Usage

fusion_table(df, types = NULL)

Arguments

df	A data frame (or tibble).
types	Optional named character vector of column types, e.g. c(n = "integer") for a double column that holds whole numbers.

Value

An object of class fusion_table, accepted as a handler return value or a body.

---