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 shows 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.
Http request is an information about action that client is performing using http protocol.
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 may be an information about a resource, a resource itself or a result of a performed action that 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. Controllers fulfill requests by returning the state of a resource, changing the state of a resource or creating new resource.
More about registering a controller is available here.
Middleware are functions or classes that have access to the request object before controllers. Middleware are great way of extending and/or changing other middleware or application behaviour.
More about middleware and its usage is available here.
