(this issue is for creating the very first public version of the manua – it doesn't need to be comprehensive)

Ratpack needs a basic user manual covering:

1. Introduction
2. Quick start
3. Basic mechanics
4. Scripts vs apps
5. Sync vs async
6. Extensions (modules)

I'm thinking of an equivalent of Vert.x's sendFile(): an efficient way to write a file direct to the response. Very useful for static resources. I'm not aware of whether Netty has built-in support for this, but if not, there's always the [NIO API](http://docs.oracle.com/javase/1.5.0/docs/api/java/nio/channels/FileChannel.html#transferFrom(java.nio.channels.ReadableByteChannel,%20long,%20long).

This is similar to the grails.serverURL setting in Grails. Not sure yet what form this will take in Ratpack, or what effect it will have.

How to build the docs etc.

At the moment, Groovy is not touched until the first request is handled. This makes Ratpack feel sluggish as it has to bootstrap Groovy at this time.

We could improve this by bootstrapping Groovy in the background as soon as the app starts.

Are values decoded properly?

@robfletcher feel like tackling this?

That is, add setter methods that return this…

RatpackServerBuilder port(int port)

The HTTP spec requires that the Location header on redirects is an absolute URL. For application developers, that's a complete pain in the backside. So, Response.redirect() should do the following:

1. if given an absolute URL, redirect() should put that URL straight into the Location header
2. if given a URL starting with a slash, '/', redirect() should prepend the public-facing domain and port if provided, otherwise the base URL of the request.
3. if given a relative URL (with no leading '/'), redirect() should prepend the public-facing domain and port if provided plus the parent path of the request URL, otherwise the full parent path (including domain and port).

Given a public-facing URL of http://www.ratpack-framework.org and a request to http://localhost:5050/posts/list :

"index" --> http://www.ratpack-framework.org/posts/index
"/index.html" --> http://www.ratpack-framework.org/index.html

If there is no public-facing URL configured:

"index" --> http://localhost:5050/posts/index
"/index.html" --> http://localhost:5050/index.html

I tried a simple Ratpack app that threw an exception when handling a request. The browser then just stuck at "waiting for response". Missing exception handler? Here's the exception stacktrace:

May 02, 2013 8:53:24 AM org.ratpackframework.bootstrap.internal.NettyRatpackServer startUp
INFO: Ratpack started for http://0:0:0:0:0:0:0:0:5050
May 02, 2013 8:53:40 AM org.ratpackframework.handler.NettyRoutingAdapter messageReceived
INFO: received /
May 02, 2013 8:53:40 AM org.jboss.netty.channel.SimpleChannelUpstreamHandler
WARNING: EXCEPTION, please implement org.ratpackframework.handler.NettyRoutingAdapter.exceptionCaught() for proper handling.
java.lang.AssertionError: Bintray user name must be specified in $BINTRAY_USER.    Expression: bintrayUser. Values: bintrayUser = null

This issue on the ratpack-site project got me thinking about the roles and responsibilities of a 'standard' Ratpack renderer. My current thoughts:

1. A renderer should be able to generate content based on source from any location, be that the filesystem, a database, or a JAR.
2. A renderer should generate content to any output stream/writer
3. A renderer should add appropriate content-type and encoding headers to a response, but the app developer must be able to override these.

I'm not sure whether a renderer should do anything with cache headers. I'd be interest in feedback from others.

If anyone wants to pick this up, I have some Geb based code that does 90% of what we need for this.

The only thing it doesn't do is detect links that resolve to valid pages, but whose fragment portion is pointing to something that doesn't exist.

The Javadoc will be the main reference documentation (linked to throughout the manual) so should look good.

I don't have any real ideas on what it should look like. Just a bit nicer than the default Java 7 skin.

At the moment if you have a compile time error anywhere in the script, or a runtime error not in the routing {} block you'll just get a 500 back from the server and no diagnostics.

To solve this we need to bind the error handler before the script compile handler.

Perhaps a simple Ratpack app for the site.

As per the GitHub support for contributing guidelines. I also suggest having a manifesto-style document that includes a vision + values, such as the tenets for the Pyramid project.

At the moment, there is a concept of a global renderer.

See: https://github.com/ratpack/ratpack/blob/master/ratpack-core/src/main/java/org/ratpackframework/bootstrap/internal/RootModule.java#L86

Extension modules simply bind a different impl of https://github.com/ratpack/ratpack/blob/master/ratpack-core/src/main/java/org/ratpackframework/templating/TemplateRenderer.java to override the template renderer.

The benefit of doing this is integration with this method: https://github.com/ratpack/ratpack/blob/master/ratpack-core/src/main/java/org/ratpackframework/app/Response.java#L65

This is convenient for users in that they just call a render method in their handler. However, the cost is that the user can only provide the rendering engine two things for a rendering operation; a template id and a model map.

I propose that we drop template rendering as concern of the core. If you want to use a template solution, you define whatever types you like as the interface and simply inject them into your endpoints…

class MyEndpoint implements Endpoint {

  final MarkdownRenderer renderer

  @Inject
  MyEndpoint(MarkdownRenderer renderer) {
    this.renderer = renderer
  }

  void respond(Request request, Response response) {
      renderer.render("foo", response)
  }

}

The groovy module could still support the Response.render() method as an extension. This wouldn't prevent using other renderers with the Groovy module.

These should run before the heroku deployment.

Currently, the config API is statically defined and not extensible. It needs to be extensible.

At the moment, the only SPI is the ability to inject Guice modules. Guice doesn't define any lifecycle. It simply creates an "application context" which you can retrieve beans from. We will likely need to implement our own lifecycle and make it fundamental to the way Ratpack bootstraps.

This is my proposed plan:

There are two distinct phases of bootstrapping; config then application. This creates a separation between config extension modules and application extension modules. Config types have no access to runtime types, but app types can depend on config types (in order to configure themselves).

We introduce RatpackAppBuilder, which looks like this:

interface RatpackAppBuilder {

    // Mutable list of modules defining config time beans
    List<Module> getConfigModules()

    // Callback called by Ratpack after initializing all config modules
    // Allows access to mutate the config beans before the runtime is bootstrapped
    void onConfig(Handler<Config>)

    // Mutable list of modules defining runtime beans
    List<Module> getRuntimeModules()

}

Config.groovy looks something like this:

interface Config {
    <T> T get(T configObjectType)
    <T> T config(T configObjectType, Handler<T> configurer)
}

(you can infer the closure overrides for the Groovy module)

In the Groovy script mode, this type backs the config.groovy script…

configModules << new MyConfigExtensionModule()

onConfig {
    config(MyCustomConfigObject) {
        someSetting = foo
    }
}

runtimeModules << new MyRuntimeModuleThatDependsOnMyCustomConfigObject()

It does mean that there is no static list of config options, but there can't be if it is to be extensible.

See: https://github.com/ratpack/ratpack/blob/master/ratpack-core/src/main/java/org/ratpackframework/http/Request.java#L38

Both of this are available as Map<String, List>, which while technically correct is not optimised for the common case when there is usually only one value for a param.

Print a valid url on server startup. Currently this prints the information below on start-up when no host has been provided.

Ratpack started for http://0:0:0:0:0:0:0:0:5050

would be better to have

Ratpack started for http://0.0.0.0:5050
or
Ratpack started for http://localhost:5050
or
Ratpack started for http://127.0.0.1:5050

In terms of support I intend…

• IE9+ should be 100%. Currently there are only a couple of glitches.
• IE8 doesn't support media queries or pseudo-elements so the layout, logo and chapter dividers are broken. Some simple CSS rules should be able to make them acceptable at least.
• IE<=7 I'm inclined to just turn the stylesheet off using a conditional comment and load a different one with a few very very basic tweaks so that the content is readable.

Possibly we can use a git sub-module to house the SASS source which can be shared between the two projects.

I envisage having distinct top-level stylesheets each of which pulls in a bunch of common components.

In order to deploy on Heroku, a buildpack is required to release your application.

The official Gradle buildpack is stuck on Gradle 1.0-milestone-5 and jdk6. Besides that, it is very brittle and quite broken. I decided to set up a brand new buildpack that runs Gradle 1.5 with jdk1.7. You can find the preliminary version under heroku-buildpack-gradle-jdk7.

I've managed to get the groovy-console example app up on Heroku, although it runs out of memory on invocation of gradle run. Seems like the quota is 512M on Heroku, so will look into tweaking the heap size on command invocation.

Another problem that needs to be resolved: Heroku seeks to set the port dynamically on bootstrapping of the app. It expects the app to pick up environment variable PORT and dynamically configure itself to use it at runtime. Heroku then routes all requests to the application through the port that it provided earlier.

I was looking at #5 and noticed some mentions of AddressConfig. We would probably need to inject the result of PORT into the port field of this object on startup of the app as part of the application lifecycle. Since this still seems to be under discussion at the moment, I will wait until it's better defined.

Don't really know what this will look like yet.

Might just be getting the internal testing fixtures into a cleaner state and publishing them.

It should use this internally, and expose a subset of the API.

There are a lot of methods on this type, and most aren't useful in our context.

It would be more user friendly if this wasn't a generic type.

Not quite sure how this is going to work yet, considering the Groovy subclass.

I'm sure it's possible to relocate public with configuration (though I don't know how.) But, I'd recommend placing it higher by default (e.g. putting it in the root of the project.) I like the way Grails does it, though you may not want to use the name web-app since that is a Servlets convention.

I think that front-end developers will like the framework better if the docroot is not so deeply nested. Remember not everyone wants to use an IDE.

Consider this script fragment:

ratpack {
    module {
        ...
    }

    routes {
        gets {
            response.send "Hello World!"
        }
    }
}

The module(), routes() and gets() methods are all invalid, but all the user sees is a massive stack trace. It would be better to report them as invalid parts of the DSL with a simple, clear message.

It might make sense to have a system property or two to manage stacktrace reporting.

Following Tim's recent Ratpack presentation at 33rd Degree

https://github.com/tlberglund/33rd-degree-ratpack

At one point the application had a GET route defined as

get('/lookup') {
    render('artist.html')
}

The template artists.html had a form with POST as the method. Clicking on the button produced an empty page. There was no error on the console. I believe this case should cause and error as there is no exact route defined for POST('/lookup') and apparently GET('/lookup') did not handle the request either.