fieldtest.client — io.github.luke1298/fieldtest 0.1.0

Running the arm the server chose, and reporting how it did.

A client is a map:

{:decisions {"asset-host" {:experiment "asset-host" :revision 3
                            :arm :cdn :exposure-id "6f1c..."}}
 :reporter  (in-process-reporter server)   ; or fieldtest.http/reporter
 :on-error  (fn [e] ...)}                  ; optional

Get :decisions once per scope with decide, then reuse them for every branch in that scope. An experiment is described by the same data the decide request lists:

(def asset-host {:experiment "asset-host" :revision 3 :arms [:default :cdn]})

branch clj/s

(branch client experiment arms & args)

Calls one of the functions in arms, a map of arm keyword to function, with args, and returns {:result r :exposure-id id}.

If the client has a decision for this experiment and revision, the decided arm runs. If it doesn't, :default runs and :exposure-id is nil. If the decision names an arm that isn't in arms, :default runs, the exposure id is kept, and unsupported-arm feedback is reported.

When the arm returns a promise, :result is that same promise. If the arm throws or its promise rejects, the caller gets the original error, and fieldtest doesn't try a different arm.

Throws ex-info, before calling anything, if arms has no :default.

decide clj/s

(decide decider experiments)

(decide decider
        experiments
        {:keys [sticky-key context timeout-ms] :or {timeout-ms 1000} :as opts})

Asks decider for decisions on experiments and returns a promise of a map of experiment name to decision.

The promise doesn't reject. If the decider fails or takes longer than :timeout-ms (default 1,000), it resolves to {}, and every branch then runs :default without reporting anything.

Options: :sticky-key, :context, :timeout-ms and :on-error.

decision clj/s

(decision {:keys [decisions]} {:keys [experiment revision]})

The client's decision for experiment, or nil when it has none for that experiment and revision.

decisions->json clj/s

(decisions->json decisions)

Serializes decisions so another runtime can branch on them without asking the server again.

decisions-by-experiment clj/s

(decisions-by-experiment response)

Turns a decide response into a map of experiment name to decision.

in-process-decider clj/s

(in-process-decider server)

A decider that calls server in this process. A decider takes a decide request and returns a promise of {:decisions [...]}.

in-process-reporter clj/s

(in-process-reporter server)

A reporter that hands feedback to server in this process. A reporter takes a batch (a vector) of feedback records and returns a promise.

json->decisions clj/s

(json->decisions s)

Reads decisions written by decisions->json. Unknown fields are ignored.

report! clj/s

(report! {:keys [reporter] :as client}
         {:keys [exposure-id exposure-ids] :as feedback})

Sends one piece of feedback through the client's reporter without waiting for it, and returns nil.

feedback takes :exposure-id (or :exposure-ids), :metric, :value, :value-unit, :outcome and optional :attrs; see fieldtest.records/feedback. If there is no exposure id, nothing is sent. Invalid feedback and reporter errors are passed to :on-error instead of being thrown.

timed clj/s

(timed client {:keys [exposure-id metric attrs timeout-ms]} f & args)

Calls (apply f args) and reports how long it took, in ms, as feedback. Returns whatever f returns, including the same promise if it returns one, and rethrows anything f throws.

The outcome is ok if f succeeds and error if it throws or rejects. If :timeout-ms is given and f hasn't finished by then, timeout is reported instead; f keeps running. opts takes :exposure-id (without one, nothing is reported), :metric, and optionally :attrs and :timeout-ms.