yada is designed to meet the following goals:

yada is not an experiment. It is designed for, and has been tested in, production environments.

yada is sufficiently quick-and-easy for quick prototype work but scales up when you need it to, to feature-rich secure services that can handle the most demanding workloads, while remaining faithful to the HTTP standards.

Some familiarity with HTTP will help you understand yada concepts quicker, but isn’t absolutely necessary. As you learn how to wield yada you will also discover and learn more about the HTTP standards as you go.

It’s quick to get started with yada without knowing how it works - it’s easy to get started even if you only have a basic knowledge of Clojure.

Let’s begin with a few examples. The obligatory Hello World! example is (yada/handler "Hello World!"), which responds with a message.

Perhaps you might want to serve a file? That’s (yada/handler (new java.io.File "index.html")).

Now you know how to serve a file, you know how to serve a directory. But perhaps you’ve got some resources on the classpath? (yada/handler (clojure.java.io/resource "talks/")).

What about (yada/handler nil)? Without knowing, can you guess what that might do? (That’s right, it produces a 404 Not Found response).

What about a quick dice generator? (yada/handler #(inc (rand-int 6))). Notice we use a function here, rather than a constant value, to vary numbers between rolls.

How about streaming those dice rolls as Server Sent Events? Put those dice rolls on a core.async channel, and return it with yada.

All these examples demonstrate the use of Clojure types that are converted on-the-fly into yada resources, and you can create your own types too.

Let’s delve a little deeper…

In yada, resources are defined by a plain-old Clojure map.

This has many benefits. While functions are opaque, data is open to inspection. Data structures are easy to generate, transform and query - chores that Clojure makes light work of.

Here’s an example of a resource:

There’s a lot of things you can do with a resource data model but perhaps the most obvious is to create a request handler from it to create responses from HTTP requests. That’s the role of a handler.

With yada, we transform a resource into a handler using the handler function.

A handler can be called as a function, with a single argument representing an HTTP request. It returns a value representing the corresponding HTTP response.

To use yada to create real responses to real HTTP requests, you need to add yada to a web-server. The web server takes care of the networking and messages of HTTP (RFC 7230), while yada focuses on the semantics and content ([RFC7231] and upwards).

To write real applications you also need a router that understands URIs, and yada has some features that are enabled when used with juxt/bidi, although there is nothing to stop you using yada with other routing libraries.

That’s yada in a nutshell, but the quickest way to to learn it is to set up an environment and play. That’s what we’ll do in the next chapter.

First let’s clone the project and change into its working directory.

Next we build and run it, in development mode.

This can take up to a couple of minutes to build and run from scratch so don’t worry if you have to wait a bit before you see anything.

At the dev⇒ prompt enter (go) to start a server listening by default on port 3000.

Fire up a browser and browse to http://localhost:3000/hello. You should see a simple Hello World message.

We’re going to start changing some of Edge’s source code soon, and when we do that we’ll type (reset) on our REPL. So let’s try that now.

Let’s send an HTTP request to the system to check it is working. We can use a browser to visit http://localhost:3000/hello or use curl if you have it installed on your system:

The result should be the same:

Fire up an editor and load up the file src/edge/hello.clj.

Locate the function called hello-routes. This returns a simple route structure that matches on the URI paths of incoming HTTP requests.

Make a change to string "Hello World!", for example, change it to "Hello Wonderful World!".

Now we’ve made a change to Edge’s source code, we must tell the system to reset. The system will then detect all the code changes and necessary dependencies to reload.

Let’s test the service again:

You should now see that the change has been made:

Congratulations. You’re all up and running with a project built with yada. This will make a great lab to try out your own yada experiments and see what is possible.

Browse to http://localhost:3000 and have fun!

Let’s send a request which gets routed to our handler, which creates the response. Let’s examine this response in more detail, via curl.

The response should be something like following (note that headers may appear in a different order):

The first three response headers are added by our webserver, Aleph.

Next we have another date and a string known as the entity tag:

The Last-Modified header shows when the string Hello World! was created, which happens to be the last time the system was started (or reset). Java strings are immutable, so yada is able to deduce that the string’s creation date is also the last time it could have been modified.

The entity tag is computed from the value of the Hello World! itself. Unlike the Last-Modified value, it can survive a reset.

Both Last-Modified and ETag are used to support HTTP conditional requests and conflict detection when uploading new versions of a resource.

Next we have a header telling us the media-type of the string’s representation.

yada is able to determine that the media-type is text, but without more information it must default to text/plain. It can also tell us the charset, which defaults to the default charset of the JVM (almost always utf-8)

Since the Java platform can encode a string to a number of charsets, yada adds a Vary header to signal to the user-agent (and proxy caches in between) that the body can change if a request contained a different Accept-Charset header. Java installations support many different charsets, so yada does too.

Next we are given the length of the body.

This value is in bytes, regardless of the charset. It includes the newline.

Finally we see our response body.

In HTTP, a conditional request is one where a user-agent (like a browser) can ask a server for the state of the resource but only if a particular condition holds.

A common condition is whether the resource has been modified since a particular date, usually because the user-agent already has a copy of the resource’s state which it can use if possible. If the resource hasn’t been modified since this date, the server can tell the user-agent that there is no new version of the state.

We can test this by setting the If-Modified-Since header in the request.

Here’s how we might do this using the curl command.

Of course, nobody will have modified the resource since the year 2525, so we should get a 304 response, telling us we can use our cached copy:

Notice we also get the same Vary and ETag headers. These help any proxies between the user-agent and the service properly cache content, and if they would have been produced in a 200 response, then they must also be produced in a 304. (This is the kind of thing that yada takes care of for you, unlike most libraries).

The responses we have received back from our service all contain this curious header called Vary set to accept-charset. The server is telling us (and any proxies between us) that the representation might vary depending on the charset negotiated. Let’s see if we can get our "Hello World!" message returned in other charsets.

Let’s try getting the string in UTF16 by telling the server that’s the only charset we’ll accept:

This returns the following:

The "Hello World!" message is prepended with 2 bytes called the Byte Order Mark (BOM). The length of the string (including the newline) is 13 characters. Since each character here is 2 bytes, that makes 26. The additional of the BOM makes it 28, which is what our Content-Length header reports.

A BOM indicates the order that the 2 bytes are transmitted in. In big endian form the most-significant byte is transmitted first. We can tell the service that we only want the big endian form with the following:

This will now produce the message without the BOM, because it is unnecessary. This means our Content-Length will be exactly 13 * 2 = 26.

If we were to use UTF-32, which defaults to big-endian, we’ll get a Content-Length of 13 * 4 = 52.

Note also that different representations generate different ETag values. The entity tag is a way of managing a cache of representations, not a cache of resources. Think of the ETag value as the key you could use in a key/value store that stored a cache of representations.

The negotiation of charsets may be considered by some to be unnecessary given the dominance of UTF-8. That is certainly true for today’s modern browsers. However, there are many other types of devices that are being connected to the internet (under the banner Internet of Things). Many of these devices have very tight constraints on processing and memory which prevent them from supporting UTF-8. If we are building a web service, we may want to connect these devices to it in the future.

Let’s try to overwrite the string by using a PUT.

The response is as follows:

The response status is 405 Method Not Allowed, telling us that our request was unacceptable. There is also an Allow header, telling us which methods are allowed. One of these methods is OPTIONS, which we could have used to check whether PUT was available without actually attempting it.

The response should be:

Both the PUT and the OPTIONS response contain an Allow header which tells us that PUT isn’t possible. This makes sense, because we can’t mutate a Java string.

We could, however, wrap the Java string in a Clojure atom which could reference different Java strings at different times.

To demonstrate this, try the following with the identifier http://localhost:3000/hello-atom.

Let’s try a normal GET.

We can now make another OPTIONS request to see whether PUT is available, before trying it.

It is! So let’s try it.

And now let’s see if we’ve managed to change the state of the resource.

As long as someone else hasn’t sneaked in a different state between your PUT and subsequent GET, you should see the new state of the resource is "Hello Wonderful World!". Great!

But what if someone did manage to PUT their change ahead of yours? Their version would now be overwritten. That might not be what you wanted. To ensure we don’t override someone’s change, we could have set the If-Match header using the ETag value.

Let’s test this now, using the ETag value we got before we sent our PUT request.

We get a 412, which means a pre-condition failed. The pre-condition in question relates to our If-Match header value not matching the current value of the atom. This is a very useful result, because it means we can ensure that we don’t overwrite someone else’s data.

There was one more method indicated by the Allow header of our OPTIONS request, which was HEAD. Let’s try this now.

The response does not have a body, but tells us the headers we would get if we were to try a GET request.

Often, a resource’s state or behavior will depend on parameters in the request. Let’s say we want to pass a parameter to the resource, via a query parameter.

To show this, we’ll write some real code:

This declares a resource with a GET method, which responds with a plain-text message formed from the query parameter.

Let’s see this in action, but without a parameter:

Here we get a 400 response. This means we’ve done something wrong (we’ve forgotten to add the query parameter).

Now let’s add the query parameter to the URI:

This should now get the 200 response we wanted:

Great!

As well as query parameters, yada supports path parameters, request headers, form data, cookies and request bodies. You can have optional parameters, in fact, anything that can be expressed in Plumatic Schema, and yada will even coerce parameters to a range of types. For more details, see the parameters chapter.

Now we have seen how to build a single web resource, let’s see how to build a Swagger description from a collection of web resources.

In your editor, switch to src/edge/web_server.clj. This file defines the overall route structure which includes our routes for "Hello World!". This has been included twice, both at the root and under the /api path.

This second version uses the Clojure threading macro -> which wraps the route structure with yada/swaggered and gives it a bidi tag (used for generating URIs, we’ll use this later).

The purpose of yada/swaggered is to augment the route structure given to it with a route to swagger.json, which responds with a Swagger description of the route structure in JSON. Since yada resources are data maps, this is a relatively simple data transformation of the route structure.

We can test the resource is available at its /api location with curl:

We can also query the Swagger description with curl:

This time we get a JSON body returned:

Notice we still get a Vary header telling us that multiple charsets are available. JSON bodies are available in UTF-16 and UTF-32. Compare this with Clojure’s EDN, which is specificed to be UTF-8 only. In fact, yada is happy to produce Swagger definitions in EDN too:

Note that this time we get no Vary header, since there are no charset alternatives.

It’s these little details that yada takes care of for you. There is no trickery involved, it’s simply the result of an almost obsessive focus on the relevant web standards. There is nothing special about strings, yada applies the same logic for anything else you ask it to handle. We’ll see more in the next chapter.

By the way, if you want to see the Swagger UI, browse to http://localhost:3000/swagger/?url=http://localhost:3000/api/swagger.json

This has been a long chapter, but we have only covered a simple "Hello World!" example.

You should now realise that implementing even a basic example that properly complies with the HTTP standard is a surprisingly tough undertaking. But this simple example demonstrated how a rich and functional HTTP resource can be created with a tiny amount of code, and none of the behaviour we have seen is hardcoded or contrived. We have only demonstrated a simple Java string, and yada includes similar support for many other basic types (atoms, Clojure collections, files, directories, Java resources…).

But the best thing is you can programmatically create your own resources and types to fit your particular requirements.

Without a library like yada we would need to read and understand hundreds of pages of the HTTP RFCs and spend a great deal of extra effort coding up its various aspects. Of course, nobody would bother doing that, but the consequence is that we miss out on the many architectural benefits of HTTP.

Rarely can client code make any assumptions that the HTTP API it is accessing complies with the text in the HTTP RFCs, and must therefore rely on detailed knowledge of how the API is written, either through documentation, Swagger definitions, close collaboration between development teams or some other means (trial-and-error). This is a problem because it causes rigidity between our systems.

By using yada, we are pushing the responsibility of implementing HTTP correctly away from the programmer and into a library.

The best way to learn is to experiment with yada, either on its own or by using it to build some service you have in mind. Either way you’ll want to set up a quick development environment.

The quickest and perhaps easiest way to get started is to clone the yada branch of JUXT’s edge repository. This is a continuously improving development environment representing our firm’s best advice for building Clojure projects.

edge is opinionated and combines a number of practices that we’ve found useful on many projects at JUXT.

If you’re new to Clojure, we recommend learning yada with edge. Not only is it packed full of examples for you to explore, the project can provide a solid foundation for your own projects with an architecture that is proven to scale as your project grows.

If you prefer to build your own development environment you’ll need a few pointers in order to integrate with yada.

The response-for function is great for testing the Ring response that would be returned from a yada type or handler.

We can describe a resource directly using a plain old Clojure map called a resource model.

Here’s an example:

Resource models are constrained by a schema, ensuring they are valid. The purpose of the yada.yada/resource function is to check the resource model is valid. The schema will attempt to coerce invalid resource models into their valid equivalents wherever possible. An error will be thrown only after these coercions have been attempted.

The following sections describe the anatomy of a resource model in more depth.

Now we have introduced all the entries that a resource model can contain, let’s use our knowledge to re-create a basic "Hello World!" resource:

Now we have a valid resource, we can now use it for a range of purposes — one obvious one is to handle HTTP requests. We can create a Ring request handler from a resource with the yada.yada/handler function:

We can now use this handler in a route.

For example, with Compojure:

Or with bidi:

A resource type is a Clojure type or record that can be automatically coerced into a resource model. These types must satisfy the yada.protocols.ResourceCoercion protocol, and any existing type or record may be extended to do so, using Clojure’s extend-protocol macro.

The as-resource function must return a resource (by calling yada.resource/resource, not just a map).

Occasionally, you may have multiple values associated with a given parameter. Query strings and HTML form data both allow for the same parameter to be specified multiple times.

To capture all values in a vector, declare your parameter type as a vector type:

Sometimes, request bodies are very large or even unlimited. To ensure you don’t run out of memory receiving this request data, you can specify more suitable containers, such as files, database blobs, Amazon S3 buckets or your own extensions.

All data produced and received from yada is handled efficiently and asynchronously, ensuring that even with very large data streams your service continues to work.

Each HTTP method has defined semantics. Often these semantics are defined in the HTTP standards, other RFCs or, in the case of custom methods, by you.

These semantics are important because they allow other web agents, such as browsers and proxies, to inter-operate with your site.

Below is an explanation of the semantics for every method yada currently supports and your responsibilities should you choose to provide the method for a resource.

Specify a function in :response that will be called during the GET method processing.

If the resource exists, the single-arity function will be called with the request context as its only argument.

It should return the response’s body, which should satisfy yada.body.MessageBody determining how exactly the response’s body will be returned.

(coming soon)

(coming soon)

(coming soon)

(coming soon)

(coming soon)

(coming soon)

(coming soon)

If you want to handle all request methods, or a complex set of them, you can specify the special keyword :* in the methods section of your resource model.

Custom methods can be added by defining new types that extend the yada.methods.Method protocol.

BREW is an example of a custom method you might want to create, especially if you are building a networked coffee maker compliant with RFC.

Content negotiation is an important feature of HTTP, allowing clients and servers to agree on how a resource can be represented to best meet the availability, compatibility and preferences of both parties. It is a key factor in the survival of services over time, since both new and legacy media-types can be supported concurrently. (It is also the mechanism by which new versions of media-types can be introduced, even media-types that define hypermedia interactions, more on this later.)

There are 2 types of content negotiation. The first is termed proactive negotiation where the server determines the type of representation from requirements sent in the request headers. These are the headers beginning with Accept.

For any resource, the available representations that can be produced by a resource, and those that it consumers, are declared in the resource model. Every resource that allows a GET method should declare at least one representation that it is able to produce.

Let’s start with a simple web-page example.

This is a short-hand for writing […​]

(missing text here)

clojure {:produces [{:media-type "text/plain" :language #{"en" "zh-ch"} :charset "UTF-8"} {:media-type "text/plain" :language "zh-ch" :charset "Shift_JIS;q=0.9"}]

( todo - languages )

The second type of negotiation is termed reactive negotiation where the agent chooses from a list of representations provided by the server.

(Currently, yada does not yet support reactive negotiation but it is definitely on the road-map.)

(coming soon)

Where necessary, and according to the semantics of the HTTP method, yada will coerce the result of a method into an entity body of the negotiated content type.

For example, consider the following resource-map.

clojure {:produces "application/json" :methods {:get {:response (fn [_] {:greeting "Hello"})}}}

On receiving a GET request, yada will automatically convert the map {:greeting "Hello"} into the JSON body {"greeting":"Hello"}.

However, the key phrase here is where necessary. If a string is returned from a method, and the content type is application/json, there is some ambiguity between whether the resource developer intends for yada to encode the string into JSON, or whether the string is already JSON encoded. In these ambiguous cases, yada assumes the string is JSON encoded already.

Therefore this code would produce an error when the user agent attempts to decode the JSON string.

If you are faced with this situation, you should choose one of the following options:

(coming soon)

When you need complete control over the response you should return the request-context's response, modified if necessary. In which case yada will see that you want to be explicit and get out of your way.

yada declares the responses that may normally be produced by a method. It adds these declarations to the resource-model when creating a resource prior to processing.

However, with explicit responses you may generate response codes that are unexpected by yada and which could be declared through the resource-model.

In these cases, you should declare the response codes in the :responses entry of the resource’s resource-model.

The keys in the :responses map can be integers, sets of integers, or the wildcard: *. Only sets are supported, so if you need to produce a range of status codes, create a set programmatically:

Individual status codes take precedence over sets of status codes, which take precedence over wildcards. After that, the order in which keys are checked is undefined. If you are using sets, avoid declaring the same status code in multiple keys.

Usually yada will return the responses produced by methods, and create ones for errors that occur along the way.

Often it is useful to be able to control the response body, or even the complete response, for responses with certain status codes.

We can specify these controlled responses by specifying a response entry in the value corresponding to the status code.

A common example is providing a custom 404 page when a resource cannot be found, which may provide the user with details of why the resource couldn’t be found and perhaps what to do next.

Let’s see how this is done:

Note that the response definition can include a declaration of the representations that the response can produce.

If the response is caused by an error, the actual error is available in the context under :error.

In yada, resources are self-contained and are individually protected from unauthorized access. We agree with the HTTP standards authors when we consider security to be integral to the definition of the resource itself, and not an extra to be bolted on afterwards. Nor should it be complected with routing. The process of identifying up a resource from its URI is independent of how that resource should behave, and shouldn’t be coupled to it.

Building security into each resource yields other benefits, such as making it easier to test the resource as a unit in isolation of other resources and the router.

As in all other areas, yada aims for 100% compliance with core HTTP standards when it comes to security, notably RFC 7235. Also, since HTTP APIs are nowadays used to facilitate transactional integration between systems via the user’s browser, it is critically important that yada fully supports systems that offer APIs to other applications, across origins, as standardised by CORS.

All security aspects for a resource are specified in its model’s :access-control entry.

Let’s look at authentication first. Authentication is the process of establishing and verifying the identity and credentials of the user, with reasonable confidence that the user is not an impostor.

In HTTP, resources can exist inside a protection space determined by one or more realms. Each resource declares the realm (or realms) it is protected by, as part of the :access-control entry of its resource-model.

Authorization is the process of allowing a user access to a resource. This may require knowledge about the user only (for example, in Role-based access control). Authorization may also depend on properties of the resource identified by the HTTP request’s URI (as part of an Attribute-based access control authorization scheme).

In either case, we assume that the user has already been authenticated, and we are confident that their credentials are genuine.

In yada, authorization happens after the resource’s properties have been loaded, because it may be necessary to check some aspect of the resource itself as part of the authorization process.

By default, yada will use a declarative role-based authorization scheme.

yada supports multiple realms. By default, there is a single realm in operation called "default". However, you can group authentication schemes and authorization models in separate realms. Each realm can contain multiple authentication schemes (it might be that a realm offers a choice of how to authenticate).

yada fully supports Cross-Origin Resource Sharing (CORS) allowing you to provide APIs that are accessible from other origins.

For example, you may be creating an API that you wish other websites to make use of, by allowing browsers visiting those websites access to your API.

CORS is specified in the :access-control section of the resource-model.

With the exception of :allow-credentials (which must be a boolean), any of the values can be declared as single-arity functions, which are called with the request-context as an argument to determine the value for the corresponding response header.

clojure {:strict-transport-security {:max-age 12000}}

Defaults to a maximum age of 31536000.

The HSTS header is only set if the scheme is HTTPS or the service is behind a proxy (determined by the presence of the X-Forwarded-For request header).

Defaults to default-src https: data: 'unsafe-inline' 'unsafe-eval'.

A browser’s iframe can be used for click-jacking. By default yada tells browsers not to allow this. The default value is SAMEORIGIN, unless you override it in the resource-model.

yada also sets the X-Xss-Protection response header to 1; mode=block. This can be overridden in the resource model.

By default, yada sets the X-Content-Type-Options response header to nosniff. This tells browsers not to try to attempt to determine the content-type of the response body.

Since yada sets the Content-Type header according to HTTP standards, there should never be a need for a browser to sniff the response body for this information, preventing an attack that might exploit some vulnerability in this process.

A bidi routing model is a hierarchical pattern-matching tree. The tree is made up of pairs, which tie a pattern to a (resource) handler (or a further group of pairs, recursively).

Both bidi’s route models and and yada's resource models are recursive data structures and can be composed together.

The end result might be a large and deeply nested tree, but one that can be manipulated, stored, serialized, distributed and otherwise processed as a single dataset.

A yada handler (created by yada’s yada function) and a yada resource (created by yada’s resource constructor function) that extends bidi’s Matched protocol are both able to participate in the pattern matching of an incoming request’s URI.

For a more thorough introduction to bidi, see https://github.com/juxt/bidi/blob/master/README.md.

Many web frameworks allow you to set a particular behavioral policy (such as security) across a set of resources by specifying it within the routing mechanism.

In our view, this is wrong, for many reasons. A URI is purely a identifier for a resource. A resource’s identifier might change, but such a change should not cause the resource to bahave differently.

In the phraseology offered by Rich Hickey in his famous Simple Made Easy talk, we should not complect a resource’s identification with its operation. Neither should we complect a protection space with a URI space. Doing so adds an unnecessary constraint to the already difficult problem of naming things (URIs) while adding an unnecessary constraint to the ring-facing of resources into protection spaces. For this reason, yada and bidi are kept apart as separate libraries.

Some web frameworks can be excused for offering a pragmatic way of reducing duplication in specification, but this really ought not to be necessary for Clojure programmers who have powerful alternatives.

What are these alternatives? How can we avoid typing the same declarations over and over in every resource?

One option is to create a function that can augment a set of base resource models with policies. That function can then be mapped over a number of resources.

A variation of this option is to use Clojure’s built-in tree-walking functions such as clojure.walk/postwalk. If you specify your entire API as a single bidi/yada tree, it is easy to specify each policy as a transformation from one version of the tree to another. What’s more, you will be able to check, debug and automate testing on the end result prior to handling actual requests.

Create a simple HTTP service to represent a phone book.

Acceptance criteria. - List all entries in the phone book. - Create a new entry to the phone book. - Remove an existing entry in the phone book. - Update an existing entry in the phone book. - Search for entries in the phone book by surname.

A phone book entry must contain the following details: - Surname - Firstname - Phone number - Address (optional)

Create a new namespace called phonebook.db.

We’ll create a database constructor, and some functions to access its contents.

This constructor creates a map with two entries, both refs. We could use an atom, but refs offer more flexibility.

Now let’s add some code to add an entry.

For this requirement, we are going to support the POST method.

Let’s add the following entry to the static properties of the IndexResource.

This declaration tells yada what parameters we are expecting in the POST method. In return, yada will do the following:

The easiest way of creating a Swagger spec is by following these steps:

Once you have published the Swagger specification you should use the Swagger UI to access it.

If you use the swaggered convenience function, a Swagger UI will automatically be hosted under the route. Use a single / to redirect to the UI for the Swagger specification of your routing tree. In the example above, navigating to /api/ will bring up the Swagger UI allowing you to browse and play with the API.

It is also possible to host your own Swagger UI and link it to your published Swagger specifications. Just pass the url query parameter to the Swagger UI to indiciate the location of the yada-produced Swagger specification you want to browse.

Advanced users: For an example of custom Swagger UI configuration see dev/resources/swagger/phonebook-swagger.html for an example.

Resources accept the following Swagger options. These options will also affect the Swagger UI.

These options can be provided at the resource’s top level and can be overriden per method.

In some sense Swagger definitions compete with REST as an architecture. Where REST encourages self-describing APIs, Swagger tends towards well-documented APIs. REST APIs are particularly well suited to fluid public APIs which can support gradual evolution and a diverse and potentially unknown set of clients. In contrast, Swagger APIs and suited to fixed private APIs inside a single organisation or between multiple collaborating parties.

Although the REST approach avoids publishing full API specifications up-front, preferring discovery over documentation, there are still many situations where it is useful to derive a data representation of an API.

One example is for API deployment to Amazon Web Services, where an API on the cloud can be created programmatically.

See IBM’s Watson Developer Cloud for a sophistated Swagger example.

A deferred value is simply a value that may not yet be known. Examples include Clojure’s futures, delays and promises. Deferred values are built into yada — for further details, see Zach Tellman’s manifold library.

In almost all cases, it is possible to return a deferred value from any of the functions that make up our resource record or handler options.

For example, suppose our resource retrieves its state from another internal web API. This would be a common pattern with µ-services. Let’s assume you are using an HTTP client library that is asynchronous, and requires you provide a callback function that will be called when the HTTP response is ready.

On sending the request, we could create a promise which is given to the callback function and returned to yada as the return value of our function.

Some time later the callback function will be called, and its implementation will deliver the promise with the response value. That will cause the continuation of processing of the original request. Note that at no time is any thread blocked by I/O.

Actually, if we use Aleph or http-kit as our HTTP client the code is even simpler, since both libraries return promises from their request functions.

In a real-world application, the ability to use an asynchronous model is very useful for techniques to improve scalability. For example, in a heavily loaded server, I/O operations can be queued and batched together. Performance may be slightly worse for each individual request, but the overall throughput of the web server can be significantly improved.

Normally, exploiting asynchronous operations in handling web requests is difficult and requires advanced knowledge of asynchronous programming techniques. In yada, however, it’s easy, thanks to manifold.

For a fuller explanation as to why asynchronous programming models are beneficial, see the Ratpack documentation. (Note that yada provides all the features of Ratpack and more).

Server Sent Events (SSE) is a part of the HTML5 generation of specifications that describes a capability for delivering events, asynchronously, from a server to a browser or other user-agent, over a long-lived connection.

SSE conceptually similar to web sockets. However, a key difference is that SSE is layered upon HTTP and thus inherits the protocol’s support for proxying, authorization, cookies and is integrated with Cross-Origin Resource Sharing (CORS).

In contrast, web sockets are raw TCP sockets that share nothing with HTTP except for the ability for a user agent to use the HTTP protocol to initiate a web socket connection. After that, everything is up to agreements between the client and server.

Since yada is designed to support HTTP, it does not provide anything extra to support web sockets beyond that which is provided by the web server.

To create Server Sent Event streams with yada, return a stream of data from a response.

For example, a stream of data could be a core.async channel. It is important that you set the representation to be text/event-stream, so that a client recognises this as a Server Sent Event stream and keeps the connection open.

It is, however, highly unusual to want to provide a channel of data to a single client. Typically, what is required is that each client gets a copy of every message in the channel. This can be achieved easily by multiplexing the channel with clojure.core.async/mult, which yada will recognise and tap on your behalf.

Of course, you can tap the mult yourself in your own logic and provide the tapping channel directly to yada, which will do the right thing depending on what you provide.

Rather than hardcode URLs, you can create the correctly URL with yada’s path-for function.

An example with a parameter:

(coming soon)

Say you want to modify the interceptor chain for a given resource.

You might want to put your interceptor(s) at the front.

Alternatively, you might want to replace some existing core interceptors:

Or you may want to insert some of your own before a given interceptor:

You can also append interceptors after a given interceptor:

Any resource can declare that it manages sub-resources by declaring a :sub-resource_ entry in its resource-model. The value of a sub-resource is a single-arity function, taking the request-context, that returns a new resource, from which a temporary handler is constructed to serve just the incoming request.

Sub-resources are recursive. A resource that is returned from a sub-resource function can itself declare that it provides its own sub-resources, ad-infinitum.

When routing, it is common for resources that provide sub-resources to match a set of URIs all starting with a common prefix, and extract the rest of the path from the request’s :path-info entry. This is achieved by declaring a :path-info? entry in the resource-model set to true.

(For a good example of sub-resources, readers are encouraged to examine the code for yada.resources.file-resource to see how yada serves the contents of directories.)

This is defined in yada.schema.

(coming soon)

(coming soon)

yada defines a number of protocols. Existing Clojure types and records can be extended with these protocols to adapt them to use with yada.

There are numerous types already built into yada, but you can also add your own. You can also add your own custom methods.

Asciidoctorj is used to generate HTML.

The main font is Noto Sans, licensed under the Open Font License.

Monospace font is Droid Sans Mono, licensed under the Apache License.

The yada font is based on Rochester licensed under the Apache License, Version 2.0.

Asciidoctor is used to generate DocBook 5 XML which is output to LaTeX using dblatex.