-
-
Save kolektiv/3d28ae35657275ecc29c to your computer and use it in GitHub Desktop.
open System | |
open System.Text | |
open Freya.Core | |
open Freya.Machine | |
open Freya.Machine.Extensions.Http | |
open Freya.Machine.Router | |
open Freya.Router | |
open Freya.Types.Http | |
open Microsoft.Owin.Hosting | |
(* Representation/Negotiation | |
Freya doesn't impose any choice of serializer or encoding on you, | |
as it's usually best left to the developer to decide what their app | |
needs. We'll assume you've got some functions that will serialize | |
your resources to JSON and XML in this case. | |
We write a represent function which looks at the results of the | |
content negotiation, given as an instance of the Specification type. | |
We're only interested in the negotiation of MediaTypes in this case. | |
The results returned are lists of acceptable MediaTypes, ordered by | |
client preference. | |
Our function returns a Representation (actually a Freya<Representation> | |
as everything is a function in Freya!) which describes what this data is | |
and how it's represented. Here we only care that we've encoded the data | |
as UTF-8, and we've serialized it in a specific way. | |
This is the kind of code you only write once per app in general. *) | |
let json _ = | |
"""{ "Hello": "World" }""" | |
let xml _ = | |
"""<Hello>World</Hello>""" | |
let represent res spec = | |
let serialized, mediaType = | |
match spec.MediaTypes with | |
| Free -> json res, MediaType.Json | |
| Negotiated (m :: _) when m = MediaType.Json -> json res, MediaType.Json | |
| Negotiated (m :: _) when m = MediaType.Xml -> xml res, MediaType.Xml | |
| _ -> failwith "Representation Failure" | |
Freya.init | |
{ Data = Encoding.UTF8.GetBytes serialized | |
Description = | |
{ Charset = Some Charset.Utf8 | |
Encodings = None | |
MediaType = Some mediaType | |
Languages = None } } | |
(* Resources | |
We're creating a very simple resource here, all we're providing is a | |
handler, which will be called when the server wants to return a | |
200 OK response, and some configuration - in this case, which | |
MediaTypes are supported for this resource. Again - the MediaTypes are | |
actually given as a function - although they're static here, it is possible | |
to change things like this at runtime. | |
The simple fact of providing MediaTypes in this way means that the request | |
will now be negotiated when an Accept header is present (this is a | |
very declarative configuration model). | |
You probably wouldn't specify MediaTypes on every resource in a real | |
app - you'd define one or more resources containing common properties | |
like this, and then include them within resources. Resources with | |
Freya.Machine are completely nestable in this sense. | |
You would likely do the same with the "using http" statement here, which | |
tells the resource that it should use the HTTP processing state | |
machine. *) | |
let exampleMediaTypes = | |
Freya.init [ | |
MediaType.Json | |
MediaType.Xml ] | |
let exampleHandler = | |
represent "Hello World" | |
(* Allowed/Exists | |
Supporting extra logic is optional, but you can add in extra logical checks | |
(in fact overriding the default results of these checks) by adding new | |
elements to the resource. | |
In this case we've added two very simple decision | |
functions (Freya<bool>) which just look at an untyped query string for | |
their data. Of course normally you'd want to actualy be checking if the | |
resource existed, or there was some token in the request which matched a | |
requirement for being allowed to obtain a resource. | |
These could be written more succinctly, but this way is clearer. In many | |
cases you may also wish to only evaluate one of these functions once, | |
though it's used in multiple places (per request) and you can do that | |
by adding |> Freya.memo as we've done here with "exampleAllowed" - this | |
will now be evaluated at-most-once per request. *) | |
let exampleAllowed = | |
freya { | |
let! query = Freya.getLens Request.query | |
return query <> "forbidden" } |> Freya.memo | |
let exampleExists = | |
freya { | |
let! query = Freya.getLens Request.query | |
return query <> "missing" } | |
let exampleResource = | |
freyaMachine { | |
using http | |
allowed exampleAllowed | |
exists exampleExists | |
mediaTypesSupported exampleMediaTypes | |
handleOk exampleHandler } |> FreyaMachine.toPipeline | |
(* Routing | |
We need to hook our resource up to a path, so we use the Freya.Router | |
to do this. Just a simple root resource for this example. *) | |
let exampleRouter = | |
freyaRouter { | |
resource "/" exampleResource } |> FreyaRouter.toPipeline | |
(* App | |
We want to turn our router in to an OWIN AppFunc, so we can run it | |
using any OWIN compatible server. *) | |
let exampleApp = | |
exampleRouter |> OwinAppFunc.ofFreya | |
(* Katana | |
We'll use Katana to host our little example app. It'll need an app | |
type. *) | |
type ExampleApp () = | |
member __.Configuration () = | |
exampleApp | |
(* Entry | |
Finally, we'll spin up our server as a quick and dirty console | |
app on localhost for testing. *) | |
[<EntryPoint>] | |
let main _ = | |
let _ = WebApp.Start<ExampleApp> "http://localhost:8080" | |
let _ = Console.ReadLine () | |
0 |
One other thing - yes in the case I'm describing, you would lose some level of certainty that all of your error cases have been handled, as you can't rely on exhaustiveness of sum type handling. I'm not sure I can find an obvious answer to that with this model at this stage.
EDIT to add: I've found that encoding all possible outcomes of actions past a certain level of complexity as DUs becomes quite taxing and difficult to maintain in places. Not to say that it isn't desirable where practical though, in your example it seems a good approach.
Wow, thanks, it's beginning to click in place for me now - thank you for your patience with me!
So, when you define the resource using the freyaMachine
computation expression, you pass various Freya<bool>
values to allowed
, authorized
, exists
, etc. In what order of precedence are they evaluated? Is the order they are added in the freyaMachine
computation expression important?
Oh no problem - I don't mind at all. It's going to help me write docs, because knowing what's not obvious even to experienced smart people is quite hard when you're too close to the code! It's been fantastically helpful to me, so thanks for your time too, it really makes a difference.
The order is defined by the HTTP graph, which is one of the things that will be part of the documentation - and is also part of the debugging tools (though they're not quite prime time yet). However, being able to see that is pretty helpful, it's top pf my list.
The order in the computation expression isn't relevant - the computation expression is essentially building up a map of configuration and functions, which is then "compiled" to an actual graph instance which can be executed at runtime. So you don't have to worry about ordering, and you can set any combination of functions/configuration without worrying how they interact.
This is an out of date version of the reference [https://github.com/freya-fs/freya.documentation/blob/master/references/machine-custom-operations.md](before I made the graph system more powerful and extensible) which I'll be updating this week to reflect what's there now. With that and a diagram of the graph, it should be a lot clearer to visualise!
WebMachine have something like this as a diagram for their graph: https://raw.githubusercontent.com/wiki/basho/webmachine/images/http-headers-status-v3.png
Our graph isn't quite the same, and is also complicated by the fact that our graph actually works on an extension model. The absolute default graph in a resource is Start --> Finish
unless you say something like using http
which will modify that graph at runtime (in the "compilation" step). That's how we currently implement CORS - you would be using http
and using httpCors
, which will extend the graph with HTTP support and then CORS support where that's needed (and again, luckily, ordering in the computation expression doesn't matter here).
You can even write your own extensions to add processing steps to the graph if needed (for example, you could write an extension which would introduce WebDAV support). However, that is definitely not for the faint-hearted at this point, and it should never be needed if people just want to do simple and accurate HTTP work.
Yes I see where you're coming from. You're right in saying that handleOk, handle* etc. return a specific status code (well, you can override them, but it would be odd to do so). I think I'd probably describe it as an inversion of where the logic sits.
In your approach, you're attempting some action, and then interpreting the result of that to see what you should return. So if you succeeded, some kind of 2xx, failed because of the client, 4xx, etc.
The Freya machine model (and indeed general machine models, it's very similar in WebMachine, Liberator, or other similar approaches) is to model things differently. When defining a resource, I tend to start with the happy path. Define what
handleOk
means, in the case where everything is fine.Next, could it fail in some particular way? So, could this resource ever not exist? If there's ever any chance of that (if it's a collection it always exists perhaps, but if this resource represents some item it doesn't if the ID isn't found for example), then I'll implement the
exists
decision. Is it possible that the data coming in may not be in the correct form? If so, I'll implement theprocessable
decision, where I might validate that the JSON is syntactically correct for a POSTed representation (as an example).Could this fail because the user is not allowed to do something? Then I'll implement
allowed
, and so on.In cases where I'm actually modifying something, that'll be happening in an action - so for example, I may implement
doPost
, ordoPut
, which again form a branch in the decision graph - or may do.In essence, yes
handleOk
will always return200 OK
or equivalent - but it will only ever be invoked if everything is actually fine and that's a correct response. If something wasn't right, I would have branched off in the decision graph long before (hopefully!).In cases where you are working with legacy systems it's obviously trickier - sometimes you'd need to attempt the action quite early in the process if it's coarse-grained and non-modifiable, and refer back to it in your decisions. So i the case of your API as given, you might see something like this:
In this case we attempt an action and then implement our decisions based on the result (and due to the call to
Freya.memo
, we only attempt that action once). Of course, if you have control over your backend completely, you might optimise it so that you can actually make fine-grained calls in those decisions to your backend, but you don't have to if you can't for any reason. I've glossed over how to invokeimp
in that implementation, but it generally isn't awkward.