Fundamental Concepts
Chocs works around some concepts that might be familiar for most developers. This chapter touches those concepts and explains application flow.
The following diagram show abstracted chocs's application flow. Presented flow works the same way across different environments (AWS, WSGI, etc).
Client performs a HTTP request to your application, this request is handled by the framework layer and gets transformed to chocs.HttpRequest instance. Transformed request is then passed to middleware layer which can amend application behaviour by for example modifying request contents and passing it to user defined controller. The controller must return chocs.HttpResponse instance as a processing output. Returned response is passed back to middleware layer. Middleware then passes (modified) response object back to framework layer and valid HTTP Response object is served to the client.
Application is a core part of chocs. It takes care of interpreting and transformig requests, passing requests' path to router and executing middleware and controllers. chocs.Application class also provides simple interface to register controllers and assign route patterns to them, so when request is made it can be routed to corresponding controller.
Request is an information for application which resource client is asking for and how the resource should be obtained.
There are two types of request from the framework perspective:
- native request this type of request varies depending on the environment in which application runs (aws, wsgi, etc..), and is hidden from usage
-
internal request which is an instance of
chocs.HttpRequestand provides abstraction for native http requests
Chocs task is to understand native request and transform it into an instance of chocs.HttpRequest, this transformation happens automatically.
More about request and its usage is available here.
Response is a reaction for the client's request. It should contain the resource which the client asked for.
There are two types of response from the framework perspective:
- native response this type of respose varies depending on the environment in which application runs (aws, wsgi, etc..), and is hidden from usage
-
internal response which is an instance of
chocs.HttpResponseand provides abstraction for native http response
More about response and its usage is available here.
Routing is chocs' component responsible for routing each incoming HTTP request to a handler. An application exposes routes for each resource it manages. A route is a pattern that matches the path of a request. When a request's path matches a route, the associated handler is invoked to handle the request. Routes are like paths but have additional syntax, like /users/{id}. The {id} is called route's parameter and matches any value in the given path segment.
More about routing and its usage is available here.
Controllers are callables that handle requests. A controller performs operations on a resource or resource collection, and always sends a response. Controllers fulfill requests by returning the state of a resource or by changing the state of a resource.
