sg.flybot.pullable.remote — sg.flybot/lasagna-remote 0.1.0

Pull-based remote protocol over HTTP.

Server Quick Start

(require '[sg.flybot.pullable.remote :as remote])

;; Define API as a function: request → {:data ... :schema ...}
(defn my-api [ring-request]
  {:data {:user {:name "Alice" :age 30}}
   :schema {:user {:name :string :age :number}}})

;; Create Ring handler
(def handler (remote/make-handler my-api))

Client Quick Start (JVM only)

(require '[sg.flybot.pullable.remote.client :as client])

(def api (client/connect "http://localhost:8080/api"))
(api '{:user {:name ?n}})
;; => {'n "Alice"}

(client/schema api)  ; introspect

Endpoints

• POST /api - Execute pull pattern
• GET /api/_schema - Schema introspection (session-aware)

Wire Format

Content negotiation via Accept/Content-Type headers:

• application/transit+json (default)
• application/transit+msgpack
• application/edn

Request/Response

Request: {:pattern '{:user {:name ?n}}} Success: {'n "Alice"} Failure: {:errors [{:code :schema-violation :reason "..."}]}

decode clj/s

Decode bytes to Clojure data.

encode clj/s

Encode Clojure data to bytes. Format: :transit-json, :transit-msgpack, :edn.

execute clj/s

Execute a pull pattern directly (no HTTP). Used by in-process callers like browser sandboxes that share the same execution engine as the server.

api-fn: (fn [context] {:data ... :schema ... :errors ...}) pattern: Clojure data structure (EDN) opts: {:params {...} ; $-param substitution :resolve fn ; symbol resolver (default: safe whitelist) :eval-fn fn ; form evaluator (default: blocked) :context map} ; passed to api-fn

Returns vars map on success, {:errors [...]} on failure.

(def api-fn
  (fn [_ctx] {:data {:posts posts-coll}}))

(execute api-fn '{:posts ?all})
;; => {'all [...]}

make-handler clj/s

Create a Ring handler for pull-based API.

Arguments:

• api-fn: Function (ring-request) → {:data lazy-map, :schema schema-map, :errors errors-config}

The api-fn returns :errors config for error handling:

• :detect - keyword or fn to detect errors in mutation results
• :codes - Map of error-type to HTTP status

Collections return errors as data: {:error {:type :forbidden :message "..."}}

Options:

• :path - Base path for API (default "/api")

Example:

(def handler
  (make-handler
    (fn [req]
      {:data (build-api (:session req))
       :schema my-schema
       :errors {:detect :error
                :codes {:forbidden 403}}})))

parse-mutation clj/s

Detect if pattern is a mutation. Returns {:path :query :value} or nil.

Mutations use nil (create) or map (update/delete) as query keys. Read patterns (keyword query keys or ?-variable values) return nil.

wrap-api clj/s

(wrap-api handler api-fn)

(wrap-api next-handler api-fn {:keys [path] :or {path "/api"} :as opts})

Ring middleware that adds pull API at specified path.

Delegates non-API requests to the wrapped handler.

Options:

• :path - Base path for API (default "/api")

(def app
  (-> my-handler
      (wrap-api my-api {:path "/api/v1"})))