Confused about compositional relationships & protocols about yada HOT 2 CLOSED

Hi Kovas,

Let me first respond to your general point, which is that I agree with you.
The initial version of yada had a single protocol with lots of coercion,
the remnants of which have evolved to the current yada.service/Service.
Over time, I began to experiment more with the idea of resources-as-data,
in particular that types that we use everyday (e.g. Strings, Files,
core.async channels) already contained much of the information you might
need to expose them as web resources. This has been a transition which
culminated in the current design. Although the design has reached an
overall design I'm broadly happy with, there is a degree of clutter from
the transition that needs cleaning up. Also, there are some things that
didn't survive the transition (like security) which needs to be rethought
and redone.

I've tried heard to document from day one, and develop in the open. But the
obvious trade-off with this approach is that the design can quickly
overtake documentation leading to staleness. Again, this should be
temporary.

Let me try to explain the specifics here, because like you say, there's no
place where I documented this info.

bidi is independent of yada and modular.

bidi/bidi deals with the general case of matching URIs to things, and
things to URIs. Those things can be keywords, vars, functions, whatever.

bidi/bidi declares 2 protocols that are involved with routing: Pattern and
Matched. This allows bidi routes to be made up of Clojure core types, and
additional user types can be plugged in that might want to get involved in
the matching or URI formation process

Since Ring handlers are common 'things' to want to route to, there's
support for this in bidi/ring, with bidi's make-handler function. The
make-handler function is useful, and it would be a shame if you couldn't
use it with records, so that's the reason there's a Ring protocol. The only
reason to use the Ring protocol, rather than provide a Ring-compatible
function, is if your Ring handler wanted to make use of extra details
accumulated in the routing process (perhaps created by custom types
satisfying Pattern or Matched).

There are some custom types in bidi/ring too, called Resources,
ResourcesMaybe, and Files. These will eventually be deprecated because yada
can provide better implementations of the current functionality (e.g.
including content negotiation and conditional requests, even perhaps
WebDav). Still, they linger on in this state of overall incompleteness.

Finally, bidi/bidi declares RouteProvider. It used to be part of modular
but got promoted. Perhaps that added to the confusion. It's really a way to
declare that you have a record that is able to provide a route, or a
subtree of routes, into a larger routing tree. It's for supporting
application composeability where you've got a big application with lots of
routes and want to break it up into sub-applications. Maybe it should be
broken out into a separate namespace. It's got nothing to do with Ring.

yada depends on bidi, although not tied to it, and much of its value can
still be exploited when used with other routing libraries, at least that's
the hope. It creates a Handler record for each yada instance. A Handler is
really only a record for the purposes of resources-as-data, the one
protocol it has to satisfy is clojure.lang.IFn so it can be used as a Ring
handler. It doesn't satisfy bidi's Ring protocol, because to do so would
establish unnecessary coupling with bidi, at the exclusion of other routing
libraries, current and future. Confusingly, it also satisfies yada's
Properties and Get protocols, but that's a 'meta' thing, so it's possible
to do (yada (yada ...)). yada's Swaggered record, does, however, satisfy
bidi's Ring protocol. The reason it does so is that the swagger support in
yada only works when you use bidi, because yada and bidi provide the yin
and yang of data (routes and resources) that a Swagger spec. exposes.

yada used to have many more protocols, reflecting various parts of the http
spec. Look at how many are now commented in yada.protocols. The main one
that remains is yada.protocols/Properties, which is how custom types adapt
to yada - they provide properties. Also, there's ResourceCoercion which
allows you to do things like (yada "Hello World!"). Plus each record must
satisfy a protocol for each method you want to support. That's the key
mechanism in yada for supporting custom http methods, which all good REST
libraries should do.

Dependency-wise. yada and bidi do not depend on modular. The example
applications built with them do, but not the core libraries. Modular is
targeted at the level of end-user application assembly.

Hope this throws a bit more light on things and helps to clarify. In due
course I'll factor these notes into yada's documentation. If you still have
questions, please let me know.

Regards,

Malcolm

Malcolm Sparks
Director

Email: [email protected]
Web: https://juxt.pro

JUXT LTD.
Software Consulting, Delivery, Training

On 6 November 2015 at 18:13, kovasb [email protected] wrote:

Very cool project!

This is a documentation issue. I've spent about a day reading all the
docs, source and example code. I'm still pretty confused about the
fundamentals.

The main issue is that there are a lot of protocols, and multiple layers
of abstraction. Bidi, Yada, and their Modular companions. There are several
things that seem to abstract Ring for example. There are multiple things
that get coerced into other things. Some docs explain what can go directly
into what would be helpful.

Simple example of confusion:

I see RouteProvider used a lot. I thought I could just drop something
implementing RouteProvider into a bidi route tree. Doesn't seem to work.

I'm also pretty confused about all the protocols implemented by Handler,
versus things like WebRequest and the various flavors of ring wrapping.

In general the execution model is unclear (when all these protocols would
be invoked during a) creating the master ring handler, and b) during
request processing.

—
Reply to this email directly or view it on GitHub
#31.

from yada.

This was very helpful. Thanks.

from yada.