Documenting capability levels for broker implementations

[rajp152k]

formalizing capability levels for a broker's functionality will help explicitly document the granularity across implementations down the line : this in turn helps structure the testing infrastructure more comprehensibly (ref : #202 for instance)

[rajp152k]

post an initial discussion with @ashutoshgngwr ,
trying out an intermediate doc generation phase that picks up what all parts of the broker have been implemented (would proceed with an exec'able alias in deps.edn) -> this would contribute towards a capability matrix of sorts

with reference to #202 , a custom test runner, that has access to these broker specific implementation flags as well as info as to what class of integration tests require what functionality, would help out with more convenient dispatch of the tests.

(fyi @neenaoffline)

[rajp152k]

unimplemented functionality of a broker yields an abstract method error : would be using this to find out capabilities of a broker implementation

(defprotocol BrokerTest
  (fna [this foo])
  (fnb [this bar]))

(defrecord BrokerTestRecord [baz]
  BrokerTest
  (fna [this foo] foo))

(fnb 
 (BrokerTestRecord. "baz") :foo)

yields :

  Show: Project-Only All 
  Hide: Clojure Java REPL Tooling Duplicates  (6 frames hidden)

1. Unhandled java.lang.AbstractMethodError
   Method
   goose/broker/BrokerTestRecord.fnb(Ljava/lang/Object;)Ljava/lang/Object; is
   abstract
                      REPL:   -1  goose.broker.BrokerTestRecord/fnb
                      REPL:   78  goose.broker/eval22744
                      REPL:   78  goose.broker/eval22744
             Compiler.java: 7194  clojure.lang.Compiler/eval
    interruptible_eval.clj:  106  nrepl.middleware.interruptible-eval/evaluator/run/fn
    interruptible_eval.clj:  101  nrepl.middleware.interruptible-eval/evaluator/run
               session.clj:  230  nrepl.middleware.session/session-exec/session-loop
        SessionThread.java:   21  nrepl.SessionThread/run

[rajp152k]

see this : #214

[rajp152k]

naked capability levels (granular methods of the broker protocol implemented) (#214) are being used for selectively dispatching integration tests when they apply.

UX/DX (developer experience) shouldn't expose this granularity in docs/api (in alignment with discussions with @neenaoffline , @ashutoshgngwr) , need to consider a hierarchical strat (segregation comments in the broker protocol could seed the effort : https://github.com/nilenso/goose/blob/main/src/goose/broker.clj