From 744b673f20c6993038e10a480bd746db2c1dccb3 Mon Sep 17 00:00:00 2001 From: Ben Sima Date: Tue, 31 Mar 2020 20:48:56 -0700 Subject: Add tutorial and apidocs to website --- Run/Que/Website.hs | 64 ++++++++++++++++++++++++++--------------------------- Run/Que/apidocs.md | 3 +++ Run/Que/index.md | 11 +++++++-- Run/Que/tutorial.md | 55 +++++++++++++++++++++++++++++++++++++++++++++ 4 files changed, 98 insertions(+), 35 deletions(-) create mode 100644 Run/Que/apidocs.md create mode 100644 Run/Que/tutorial.md (limited to 'Run') diff --git a/Run/Que/Website.hs b/Run/Que/Website.hs index 8681678..910d97b 100644 --- a/Run/Que/Website.hs +++ b/Run/Que/Website.hs @@ -28,6 +28,8 @@ main = do , client = src "client.py" , quescripts = src "quescripts.md" , style = src "style.css" + , apidocs = src "apidocs.md" + , tutorial = src "tutorial.md" } data Sources = Sources @@ -35,42 +37,38 @@ data Sources = Sources , quescripts :: FilePath , client :: FilePath , style :: FilePath + , tutorial :: FilePath + , apidocs :: FilePath } loop :: Text -> Sources -> IO () -loop ns pages@Sources {..} = do - _ <- - Async.runConcurrently - $ (,,,) - <$> Async.Concurrently - (toHtml style index >>= serve (https "que.run" /: ns /: "index")) - <*> Async.Concurrently - ( BS.readFile client - >>= serve (https "que.run" /: ns /: "client") - ) - <*> Async.Concurrently - ( toHtml style quescripts - >>= serve (https "que.run" /: ns /: "quescripts") - ) - loop ns pages - - -toHtml :: FilePath -> FilePath -> IO ByteString -toHtml style md = - BS.pack - <$> Process.readProcess - "pandoc" - [ "--self-contained" - , "--css" - , style - , "-i" - , md - , "--from" - , "markdown" - , "--to" - , "html" - ] - [] +loop ns pages@Sources {..} = Async.runConcurrently actions >> loop ns pages + where + actions = traverse + Async.Concurrently + [ toHtml index >>= srv "index" + , toHtml quescripts >>= srv "quescripts" + , BS.readFile client >>= srv "client" + , toHtml tutorial >>= srv "tutorial" + , toHtml apidocs >>= srv "apidocs" + ] + srv p = serve $ https "que.run" /: ns /: p + toHtml :: FilePath -> IO ByteString + toHtml md = + BS.pack + <$> Process.readProcess + "pandoc" + [ "--self-contained" + , "--css" + , style + , "-i" + , md + , "--from" + , "markdown" + , "--to" + , "html" + ] + [] -- TODO: recover from 502 errors serve :: Url scheme -> ByteString -> IO () diff --git a/Run/Que/apidocs.md b/Run/Que/apidocs.md new file mode 100644 index 0000000..f400889 --- /dev/null +++ b/Run/Que/apidocs.md @@ -0,0 +1,3 @@ +% que.run Api Docs + +coming soon diff --git a/Run/Que/index.md b/Run/Que/index.md index ca5c7ef..c61dc5c 100644 --- a/Run/Que/index.md +++ b/Run/Que/index.md @@ -9,7 +9,7 @@ que is the concurrent, async runtime in the cloud plumbing - async programming as easy as running two terminal commands -HTTP routes on que.run are Golang-like channels with a namespace and a +HTTP routes on `que.run` are Golang-like channels with a namespace and a path. For example: `https://que.run/example/path/subpath`. ## Quickstart @@ -34,4 +34,11 @@ We are collecting a repository of scripts that make awesome use of que: - ephemeral, serverless chat rooms - collaborative jukebox -See the examples +See the scripts + + diff --git a/Run/Que/tutorial.md b/Run/Que/tutorial.md new file mode 100644 index 0000000..b5b258d --- /dev/null +++ b/Run/Que/tutorial.md @@ -0,0 +1,55 @@ +% que.run Tutorial + +## Ques + +A que is a multi-consumer, multi-producer channel available anywhere you +have a network connection. If you are familiar with Go channels, they +are pretty much the same thing. Put some values in one end, and take +them out the other end at a different time, or in a different process. + +Ques are created dynamically for every HTTP request you make. Here we +use the `que` client to create a new que at the path `example/new-que`: + + que example/new-que + +The `que` client is useful, but you can use anything to make the HTTP +request, for example here's the same thing with curl: + + curl https://que.run/example/new-que + +These requests will block until a value is placed on the other +end. Let's do that now. In a separate terminal: + + echo "hello world" | que example/new-que - + +This tells the `que` client to read the value from `stdin` and then send +it to `example/new-que`. Or with curl: + + curl https://que.run/example/new-que -d "hello world" + +This will succeed immediately and send the string "`hello world`" over +the channel, which will be received and printed by the listener in the +other terminal. + +You can have as many producers and consumers attached to a channel as +you want. + +## Namespaces + +Ques are organized into namespaces, identified by the first fragment of +the path. In the above commands we used `example` as the namespace, but +you can use whatever you want. + +Except, there is one special namespace `_` which is reserved for +internal use only. You can't write to the `_` namespace. + +Namespaces are normally public, and anyone can write and read to +them. The `Pro` version allows you to reserve namespaces and add +authentication. + +## Events + +Just reading and writing data isn't very exciting, so let's throw in +some events. We can very quickly put together a job processor. + + que example/new-que --then "./worker.sh '\msg'" -- cgit v1.2.3