Versioning

[borkdude]

Maybe it's a good idea to version the protocols:

HttpClient_v1

so we can add more protocols, HttpClient_v2, over time. Old libraries keep working if they encounter an implementation of v1, but can upgrade to the improved protocol v2, by using that.

Alternatively, one could add more methods to the protocol over time.

We can start with v0 which is the alpha and allow breakage on that one.

[mynomoto]

You could use the namespace for versioning the protocol. Maybe clj-easy.tools.http-client.v0?

[mynomoto]

Oh, that's interesting. I'm the end, libraries don't know their transitive dependencies because users are always able to override.
I would be concerned by codepaths that are less commonly used having those dependencies and it blows up in prod but people also like less dependencies.

[borkdude]

Yeah. So, a library could default to one implementation, but an app or other library could decide to pull in clj-easy/tools.json {:mvn/version "0.1.0-none"}. I wonder what happens if library B uses "0.1.0-cheshire" and library A uses "0.1.0-none" (since it's pretty sure nobody wants to use YAML) and an app uses library A (and/or B).

[mynomoto]

If the app has no top level dependency this will depend on tooling because tools.deps and maven have different ways to pick transitive dependencies. Iirc tools.deps tries to pick more recent versions and maven is dependent on the order of deps.

[jeroenvandijk]

Let's say some library depends on the clj-easy/tools.json interface, using the above method, they there are two options of including the library

1. declaring the dependency as provided "provided" or not declaring it at all. The end user has to include the dependency.
2. using a clj-easy/tools.json version "none" that throws on usage. The end user has to override this dependency with a version that works as desired

I see downsides with both approaches:

1. Will blow up at runtime leading to non-intuitive missing namespace errors (reminding me of ring)
2. Will not work perfectly with 3rd party extensions as 3rd parties will not be able to create an artifact on clojars with clj-easy/tools.json. This would only work for git repo's in combination with :git/url

Potential solution to problem 2:

Using a macro that resolves to the latest available function and has a default implementation that throws. WDYT? Code below

;; Example implementation
(ns clj-easy.tools.json.v3)

(defn read-str [& _]
  "v3 result here")

;; Main interface
(ns clj-easy.tools.json)

(defmacro def-fn [fqn-sym latest-version dep]
  (let [ns-name (symbol (namespace fqn-sym))
        fn-sym (symbol (name fqn-sym))
        f (some
           (fn [version]
             (when-let [n (find-ns (symbol (str ns-name ".v" version)))]
               (ns-resolve n fn-sym)))
           (reverse (range 0 (inc latest-version))))]
    `(def ~fn-sym
       (or ~f
           (fn [& args#]
             (throw
              (ex-info (str "No implementation for '" (quote ~ns-name) "/" (quote ~fn-sym) ". "
                            "Please add a " ~dep  " implementation "
                            "to the dependencies.") {})))))))

(def-fn clj-easy.tools.json/read-str 3 "clj-easy/tools.json")

(read-str "hi") ;=> "v3 result here"

(def-fn clj-easy.tools.json/read-str 2 "clj-easy/tools.json")

(read-str "hi") ;=> error

[borkdude]

Will not work perfectly with 3rd party extensions as 3rd parties will not be able to create an artifact on clojars with clj-easy/tools.json.

This might be a reason why we should then centralize implementations, like @mynomoto has suggested.
But you could also have a global exclusion on clj-easy.tools.json in your deps.edn and then pull in a 3rd party package.

[borkdude]

@mynomoto I made a branch, aptly named mynomoto-solution here.

I think I did what you suggested there.

When you run bb test:clj the test runner is invoked twice but with a different classpath, providing implementations for cheshire and data.json.

This is the cheshire implementation:

https://github.com/clj-easy/tools.misc/blob/mynomoto-solution/json/cheshire/clj_easy/tools/json/v0.clj

[mynomoto]

Yeah, that is what I was thinking. It looks great and it is way simpler than what I have on poly so far. I like your version better.
I would add a couple of tests reading a malformed json and writing some java object. Then I think we will start to see if this idea will be practical or not.

[borkdude]

I merged to master. PR for those tests welcome. Happy we reached some kind of consensus.

[borkdude]

A demo of the current approach on main, using cheshire as the json impl:

(require '[babashka.deps])
(babashka.deps/add-deps '{:deps {io.clj-easy.tools.json
                                 {:git/url "https://github.com/clj-easy/tools.misc"
                                  :deps/root "json/cheshire"
                                  :git/sha "aea9d3165650b82de4332c9ae53fb5f0f01a5ce0"}}})

(require '[clj-easy.tools.json.v0 :as json])
(prn (json/read-str (json/write-str {:a 1})))

[borkdude]

LOL, but also the data.json one works, because bb can execute that from source:

(require '[babashka.deps])
(babashka.deps/add-deps '{:deps {io.clj-easy.tools.json
                                 {:git/url "https://github.com/clj-easy/tools.misc"
                                  :deps/root "json/data-json"
                                  :git/sha "aea9d3165650b82de4332c9ae53fb5f0f01a5ce0"}}})

(require '[clj-easy.tools.json.v0 :as json])
(prn (json/read-str (json/write-str {:a 1})))