Topics to cover:

• Using an interceptor to attach a DB
• Using a consistent DB value in a request
• When to apply transactions
• After a transaction, what to do with the :db-after value
• Error handling

Topics to cover:

• Overriding or extending the default interceptors.
• Using your own data type for interceptor queue & stack. (See pedestal/pedestal#512)
• Move the guide on queue manipulation to here
• Move the guide on writing your own router to here

Used for functions in terminal position in a route. It lets Pedestal deduce the route name from the symbol for the function.

See the section here:
https://github.com/pedestal/docs/blob/master/documentation/service-interceptors.md#porting-ring-code

The Service Routing link is leading to 404.

I was recently bitten by lack of knowledge, writing an interceptor for a Vase app.

I needed to set the context's :response and then let it be processed by existing Vase code (e.g., converting the response to transit).

I initially did this in the :enter of my interceptor, and was surprised to discover that the remaining interceptors were not called. (The proximate reason is https://github.com/pedestal/pedestal/blob/master/service/src/io/pedestal/http/impl/servlet_interceptor.clj#L373, and I assume that the intention is deliberate).

It was easy to fix my code; I just needed to set the response in my :leave. But, this was not obvious at first, and would be helped by more documentation and examples of how to write interceptors. (Ideally, also with a link to this part of the Pedestal docs from the Vase docs).

The document pedestal-docs/content/guides/your-first-api.adoc refers to the tag <4> within tag::list_view[] of pedestal-docs/content/guides/todo-api/src/main.clj, but it is missing, <3> appears again is in its place.

See pedestal/pedestal#443 for verb-neutral routers.

See https://github.com/pedestal/pedestal/blob/master/service/test/io/pedestal/http/route_test.clj#L1239-L1270 for examples.

The "Deploying a WAR File" docs don't include steps for including the resources directory in the WAR:

http://pedestal.io/documentation/service-war-deployment/

This pull request adds resources/* to the copy command:
#19

#57 cleaned up some confusion about keywordizing in :params (not by default) and :form-params (yes by default, when possible).

Just discovered that http://pedestal.io/reference/parameters still has a confusing paragraph around this:

One catch to note has to do with form parameters from an HTTP POST request. Because form fields can be named just about anything, the keys in these maps aren’t automatically converted to keywords. If you want them to be keywordized, you should make sure to have the keyword-params interceptor on the applicable route.

This is confusing as 1) :form-params (and :query-params) are now by default converted to keywords, when possible and 2) adding keyword-params would also keywordize :params, which by default are not keywordized.

Maybe simply remove this paragraph to avoid further confusion?

In the final step of the guide, the route map still has echo interceptors, but that is not defined anywhere in the file.

And the detailed sections below the quick reference still need to be written.

The pedestal-service and pedestal-app lein templates set you up to use lein run-dev which lets you see changes without having to reload the repl. Nice feature! The docs don't mention it though.

Maybe there's a better way, but as a newcomer I was exiting the repl and starting it over every time I made a change.

Thanks to @stuartsierra for the report:

if you have any custom interceptors, you lose all the convenience of the default interceptors. It's not easy to figure out how to recover the capabilities provided by the default interceptors.

We should add a section in the reference about this.

The collection of predicates found here determine when Pedestal terminates. The default servlet chain provider adds a check for a response on the context.

I'm finding that this earlier, higher-level Pedestal documentation is a necessary companion to other Pedestal docs, such as app-tutorial. But some parts (text and diagrams) need updating, e.g. to cover the newer dataflow v2. Are there plans to update, and if yes, by when please? Thanks Relevance!

In http://pedestal.io/guides/hello-world-content-types#_the_whole_shebang see hello.clj defn greeting-for.

The line
(unmentionables nm) nm
should be
(unmentionables nm) nil

as shown in an earlier example of the guide (http://pedestal.io/guides/hello-world-query-parameters#_conditional_responses)

Topics to cover:

• Testing a single interceptor in isolation
• Testing a chain of interceptors in isolation (without HTTP handling)
• Using response-for to exercise HTTP + routing + interceptors

Steps to Reproduce

1. Go to http://pedestal.io
2. Enter "interceptor" in the search box.
3. Hit enter

Expected Results

Pages like http://pedestal.io/reference/interceptors and http://pedestal.io/guides/hello-world-content-types should appear.

Actual Results

A reference page from Clojure.org shows up in the results.

It might be good to point people to [pedestal/pedestal](https://github.com/pedestal/pedestal/tree/master/guides/documentation for documentation), as it looks like this repo isn't the source of documentation anymore?

Topics to cover:

• Single part uploads
• Multiple file uploads

This is an FAQ from the #pedestal slack channel.

When restarting the server from the boot repl I am getting a java.net.BindException: Address already in use exception on every restart. I end up having to exit boot and get back in.

I am using Ctrl + C to exit the Jetty web server.

Versions:

$ boot -V
#http://boot-clj.com
#Fri Dec 15 15:13:12 MST 2017
BOOT_CLOJURE_NAME=org.clojure/clojure
BOOT_CLOJURE_VERSION=1.8.0
BOOT_VERSION=2.7.2

list-view does its work in the :enter phase of the route handling, while list-item-view does it in the :leave phase. This difference entails that these two interceptors are placed in different orders relative to db-interceptor in the "list viewer" and "list-item viewer" routes.

Is there any particular reason for this difference? Is there anything preventing both interceptors from doing their work in, for example, the :leave phase and being uniformly placed before db-interceptor?

Topics to cover:

• Basic structure of :enter, :leave, and :error functions
• Creating an interceptor from a map
• Interceptors as values (i.e., def with a map)
• Interceptors constructed in functions (closing over state)
• The IntoInterceptor protocol (use a defrecord for an example)
• Async return from an interceptor
• Streaming response bodies
• Distinction between interceptors as a general technique vs. the HTTP handling interceptors in Pedestal

We've got a placeholder on the Guides page but it needs to be fleshed out.

@ohpauleez has gotten some great performance out of Pedestal apps. We need a guide that shows everyone how to do this.

The "fast-pedestal" sample app is there. Readers could benefit from a walkthrough doc that explains the differences from a default (i.e., template-generated) service.

Paul also has code in a private repo (https://github.com/cognitect-labs/FrameworkBenchmarks-internal/tree/master/frameworks/Clojure/pedestal/src/pedestal) that @mtnygard can use to write a guide.

I've found getting started working on Pedestal itself a little bit of a chore. Part of this I believe is due to my inexperience working on libraries, but then again, we want to keep the barrier of entry to contributions as low as possible. Someone who doesn't have a lot of experience but wants to contribute should find it easy to do so.

There are two aspects to this:

1. Working with unreleased versions of Pedestal in your own projects. Often you find a bug in your project. A fix might be committed but not released. How do you easily test the fix in your project? I use Leiningen in my own projects. Currently I use the Reloaded workflow and lein-test-refresh, both of which have issues when using lein checkouts for Pedestal due to dependencies that can't be loaded. To work around this I use lein install to put SNAPSHOT in my local maven repo. Due to how the Pedestal project is organized, I need to run lein install in each subdirectory. If I'm working with a bunch of different changes independently, this is tedious and error prone. Yes, I should script this. Should we provide a script that does this? Perhaps there's a script that does this already? Maybe some feature of Leiningen I don't know about? How are others handling this? What are some of the best practices?
2. What are the best practices for developing on Pedestal itself, independent of a particular project? What workflow do the maintainers use? Is there a way of testing the entire project (not just a single subproject)? Are there any automated tools that are useful? For my own projects I've found lein test-refresh useful. Should we consider adding that to the project files for testing?

It's not clear following the guide that when running the server in the repl that one should use something like this (def my-server (hello/start)) in order to start the server and then something like (io.pedestal.http/stop my-server) to stop the server. I was confused in the second part of the guide concerning query parameters when it was asked to restart the server (faultily assuming I could just run (hello/start) again) but on attempting this the error appeared java.net.BindException: Address already in use . I had to kill the REPL and restart in order to proceed. On Slack several helpful users (@mavbozo, and @ddeaguiar in the pedestal channel in clojurians pointed out some solutions)

1. Adding ::http/join? false to the http/create-server function
2. the (def my-server option)
3. (alter-var-root #'my-server io.pedestal.http/stop)

With this new helper we can try out a lot of requests from the REPL.
Don't forget to reload the main namespace in the REPL ((require main :reload))
and restart the server ((main/restart)) before you do.

Main needs to be quoted, (require 'main :reload). Also, seems like the double parens could be misinterpreted.

From @yokolet on pedestal#61:

I couldn't find any instruction about lein new pedestal-app <name> on http://pedestal.io/ .
Probably, we should add client side "Getting Started" like http://pedestal.io/documentation/hello-world-service/ .

The Developing at the REPL link on the guides page, under the interactive development section, is broken. It looks like it is supposed to point to #37, but that page isn't merged yet.

The "Quick Reference" says "The value of each key is either a handler function or a list of interceptors." That doesn't seem to work any more. The correct syntax is more like:

{:verb ^{:interceptors [interceptor-1 interceptor-2]} handler}

when only one verb uses the handler, or:

{:verb ^{:interceptors [interceptor-1 interceptor-2]} [:route-name handler]}

when the same handler is used by more than one verb.

http://pedestal.io/reference/request-map says that :params is a Map of keyword -> String.
Is this true if one doesn't add keyword-params to the default interceptors?
:params by default seem to use strings for form-params, even if they are keywords in :form-params.

In short, :params by default seems to be a map of keyword or String -> String.

lein new pedestal-service ps
;; verify project.clj is using pedestal.service 0.5.2
in service.clj add handler:
(defn post-test [request] (ring-resp/response request))
and route:
["/test" :post (conj common-interceptors `post-test)]

curl -X POST -d yo=lo localhost:8080/test?any=thing returns:
:params {:any "thing", "yo" "lo"}
:form-params {:yo "lo"}
:query-params {:any "thing"}

• 404 when response body is not found, or exists but is not a map, or exists is a map, but has no :status key

The Hello World document at pedestal-docs/content/guides/hello-world.adoc mentions that we will be using Leiningen but Boot is used in its place.

Some of the interesting protocols to discuss:

1. IntoInterceptor
2. Interceptor
3. RouterSpecification

I am going through the tutorials and am enjoying them. I am sure it will help new people get comfortable with Pedestal.

On
http://pedestal.io/guides/hello-world-query-parameters

Pedestal ginsus that up into a map of parameters for you

As much as that made me chuckle because I was regularly held captive to that commercial as a child, many readers are too young to get the reference or came from outside the US and will not find an entry for the verb "ginsu" at dictionary.com. I recommend adding a link https://www.youtube.com/watch?v=abLB7aTmnE4 to the original commercial or choosing another word. Yeah, 70s, Freedom Rock dude, turn it up!

It's a common question.

• How to get new handlers used without restarting the REPL?
• How to get routes reloaded?

Topics to cover

• Starting an SSE stream
• Sending messages
• Closing the stream
• Error handling
• Unexpected close by client

Hi..I'm not sure, but I'm following this documentation, first point: the project.clj is a bit different now, I've preferred dont do changes in this file and keep exactly as the generated by lein new pedestal-service

2. I run my repl but when I try
   (tools-help)

I get

CompilerException java.lang.RuntimeException: Unable to resolve symbol: tools-help in this context, compiling:(/tmp/form-init7413359724321465815.clj:1:1)

then I try
(use 'io.pedestal.service-tools.dev)

but again I get the same error

and checking the namespace
https://github.com/pedestal/pedestal/blob/master/service-tools/src/io/pedestal/service_tools/dev.clj

I notice than now it's a bit different...and I'm confused...

how is the correct way of start the server (and restart) using repl?

(start) (run-dev) (server/start runnable-service)

ehh..notice than I'm not a clojure expert, I'm a bit newbie so, probably it results obvious to clojure experts but for me is a bit confusing..thank so much

• Reference
• Guide

Especially the prefix-tree router, since it's the default. See pedestal/pedestal#330.

I've copied "the whole shebang" from the end of the Your First API guide and ran the code with leiningen using the dependencies specified at the beginning of the chapter. POSTing a new list with curl (curl -i -X POST localhost:8890/todo?name=mylist) results in a 201 response including a location header. However, trying to then query the new URI (curl -i localhost:8890/id) results in a 404 error.

I've tried to narrow down the source of the error and found that the key ":params" used in the function list-view is not populated with the list-id. The ":path-params" key, however, contains the required value.
Using this to get the list from the database, fails as well, though.
Accessing the database from the REPL (get @database "id") returns nil, although the keys in the database are the list-ids as strings. I've double checked that the keys in the database really are strings, but so far I had no success to get a value from that map.

Maybe I'm missing something obvious here, since I'm fairly new to Clojure. But from my understanding, at least the manual (get ...) to the database should work...

Thanks for your help!

Topics to cover:

• Serving content from the filesystem
• Serving content from the classpath

In this section of the guide: http://pedestal.io/guides/your-first-api#_create_list
the scroll window is not wide enough and cuts off the numbered "callout" bullet points #1 .. #5 (see image). Is there an asciidoctor param to make the window wider?

Alan

It implies that using expand-routes in a service's route definition is ok but this should not be done in all cases. It will lead to an error when default-interceptors is called because route expansion will be attempted again since maps implement the Expandable Routes protocol.

I suspect that most folks knowingly or unknowingly use default-interceptors.

During the refactor of the "Hello World, With Content Types", the usage of cond-> seems like a much more significant jump in understanding of Clojure than the rest of the content. I think it would make it much easier to understand if there was some sort of intermediate step to help smooth over what I expect will be a stumbling block for many, especially if they are new to Clojure.