lib/nitcorn/README.md

   1 Lightweight framework for Web applications development
   2
   3 # Features
   4
   5 Dynamic content is served by subclassing `Action` and implementing `answer`.
   6 This method receives an `HttpRequest` and must return an `HttpResponse`.
   7 _nitcorn_ provides `FileServer`, a simple `Action` to serve static files.
   8
   9 `HttpRequest` contains the GET and POST arguments as well as session data it one exists.
  10 The produced `HttpResponse` should contain the HTTP status code, the body,
  11 session data to preserve or create a session, and optionally list files to append.
  12
  13 Each `Action` may be associated to many instances of `Route`.
  14 These routes can simply identify the root of a service,
  15 but also define parameters within the URI.
  16
  17 _nitcorn_ instances are configured dynamically in Nit code with the interfaces and routes created as needed.
  18
  19 _nitcorn_ plays well with other Nit services and tools such as `serialization`, `mongodb`, `sqlite` and `nitiwiki`.
  20 It also benefits from the full power of the Nit language:
  21 class refinement can be used to customize default services and merge many applications in a single server,
  22 and the FFI enables calling services in different languages.
  23
  24 # Examples
  25
  26 A minimal example follows with a custom `Action` and using `FileServer`.
  27
  28 More general examples are available at `lib/nitcorn/examples/`.
  29 For an example of a larger project merging many _nitcorn_ applications into one server,
  30 take a look at the configuration of `http://xymus.net/` at `../contrib/xymus_net/xymus_net.nit`.
  31
  32 Larger projects using _nitcorn_ can be found in the `contrib/` folder:
  33 * _opportunity_ is a meetup planner heavily based on _nitcorn_.
  34 * _tnitter_ is a micro-blogging platform with a simple Web and RESTful interface.
  35 * _benitlux_ uses a custom `Action` to subscribe people to a mailing list and define a RESTful interface.
  36
  37 ## Simple hello world server
  38
  39 ~~~
  40 import nitcorn
  41
  42 # Simple Action to display the Hello World page and the get arguments
  43 class HelloWorldAction
  44         super Action
  45
  46         redef fun answer(http_request, turi)
  47         do
  48                 var title = "Hello World!"
  49                 var args = http_request.get_args.join(",", ":")
  50
  51                 var response = new HttpResponse(200)
  52                 response.body = """
  53 <!DOCTYPE html>
  54 <html>
  55 <head>
  56         <meta charset="utf-8">
  57         <title>{{{title}}}</title>
  58 </head>
  59 <body>
  60         <h1>{{{title}}}</h1>
  61         <p>GET args: {{{args}}}</p>
  62 </body>
  63 </html>"""
  64                 return response
  65         end
  66 end
  67
  68 # Listen on `localhost:8080`
  69 var vh = new VirtualHost("localhost:8080")
  70
  71 # Serve `http://localhost:8080/hello.html` with our custom action
  72 vh.routes.add new Route("/hello.html", new HelloWorldAction)
  73
  74 # Serve everything else under `http://localhost:8080/` using a `FileServer` with a root at "/var/www/"
  75 vh.routes.add new Route(null, new FileServer("/var/www/"))
  76
  77 # Launch server
  78 var factory = new HttpFactory.and_libevent
  79 factory.config.virtual_hosts.add vh
  80 factory.run
  81 ~~~
  82
  83 # Credits
  84
  85 This nitcorn library is a fork from an independent project originally created in 2013 by
  86 Jean-Philippe Caissy, Guillaume Auger, Frederic Sevillano, Justin Michaud-Ouellette,
  87 Stephan Michaud and Maxime Bélanger.
  88
  89 It has been adapted to a library, and is currently maintained, by Alexis Laferrière.