diff options
| -rw-r--r-- | cnp-specification.cnm | 304 |
1 files changed, 152 insertions, 152 deletions
diff --git a/cnp-specification.cnm b/cnp-specification.cnm index 139abfc..67c4368 100644 --- a/cnp-specification.cnm +++ b/cnp-specification.cnm @@ -49,256 +49,256 @@ content \ -> \\ - section Request - text - A CNP request is sent by a client that wants to request a resource from a server (or send some data to it). + section EBNF + raw ebnf + raw_character = ? any byte except "\0", "\n", " ", "=", "\\" ? ; + escaped_character = "\\" ( "0" | "n" | "_" | "-" | "\\" ) ; + ident_character = raw_character | escaped_character ; + identifier = ident_character, { ident_character } ; + number = "0" | ( "1" … "9" ), { "0" … "9" } ; + version = "cnp/", number, ".", number ; + intent = identifier ; + parameter = [ identifier ], "=", [ identifier ] ; - section Intent - text fmt - In a request, the intent part of the header contains the hostname of the server concatenated with the path of the requested resource. + header = version, " ", intent, { " ", parameter }, "\n" ; + body = { ? any byte ? } ; - The hostname may be a domain name or an IP address, optionally with a port number, and it may not contain any slash (``0x2f``) bytes. In general, it should be the address that the client sends the request to. The format of the hostname is the same as in URLs. + message = header, body ; - The path is a Unix-style absolute filepath with an optional trailing slash. It may (and probably should) be cleaned up by CNP implementations before being processed by collapsing multiple consecutive slashes into single ones, removing path entries that consist of a single dot and resolving double-dot parent directories, while leaving a trailing slash if one was present (for example, the path ``"/../../.\/\/\/foo/bar/.."`` becomes ``"/foo"`` and ``"\/\/foo/bar/../"`` becomes ``"/foo/"``). If possible, implementations should avoid sending filepaths that need to be cleaned. The minimal path is ``"/"``; blank path is an error. - The hostname is case-insensitive, while the path is case-sensitive. Hostname may be normalized by clients and servers, but a specific path (after cleanup) represents one specific resource. + section Request + text + A CNP request is sent by a client that wants to request a resource from a server (or send some data to it). - To separate the hostname from the filepath, split the intent before the first slash. + section Intent + text fmt + In a request, the intent part of the header contains the hostname of the server concatenated with the path of the requested resource. - section Parameters - text - The following request parameters are defined (default value is assumed if the parameter value is blank; any absent parameter must be treated as if it had the default value): + The hostname may be a domain name or an IP address, optionally with a port number, and it may not contain any slash (``0x2f``) bytes. In general, it should be the address that the client sends the request to. The format of the hostname is the same as in URLs. + The path is a Unix-style absolute filepath with an optional trailing slash. It may (and probably should) be cleaned up by CNP implementations before being processed by collapsing multiple consecutive slashes into single ones, removing path entries that consist of a single dot and resolving double-dot parent directories, while leaving a trailing slash if one was present (for example, the path ``"/../../.\/\/\/foo/bar/.."`` becomes ``"/foo"`` and ``"\/\/foo/bar/../"`` becomes ``"/foo/"``). If possible, implementations should avoid sending filepaths that need to be cleaned. The minimal path is ``"/"``; blank path is an error. - section length - raw - length={number} + The hostname is case-insensitive, while the path is case-sensitive. Hostname may be normalized by clients and servers, but a specific path (after cleanup) represents one specific resource. - text fmt - The length of the request body data in bytes. + To separate the hostname from the filepath, split the intent before the first slash. - This field is required if any data will be sent to the server. - Default value: ``"0"`` (empty body) + section Parameters + text + The following request parameters are defined (default value is assumed if the parameter value is blank; any absent parameter must be treated as if it had the default value): - section name - raw - name={identifier} + section length + raw + length={number} - text fmt - The name of the content being sent in the request body. Must not contain slashes (``0x2f``) or NUL bytes (``0x00``), including escaped NUL bytes (``\0``). + text fmt + The length of the request body data in bytes. - Can be used to provide filename metadata. If the original filename was a Unicode filename instead of a bytestring, UTF-8 should be used to encode it. + This field is required if any data will be sent to the server. - Default value: ``""`` (no name provided) + Default value: ``"0"`` (empty body) - section type - raw - type={identifier}/{identifier} + section name + raw + name={identifier} - text fmt - MIME type of the content being sent in the request body. + text fmt + The name of the content being sent in the request body. Must not contain slashes (``0x2f``) or NUL bytes (``0x00``), including escaped NUL bytes (``\0``). - Default value: ``"application/octet-stream"`` + Can be used to provide filename metadata. If the original filename was a Unicode filename instead of a bytestring, UTF-8 should be used to encode it. + Default value: ``""`` (no name provided) - section if_modified: - raw - if_modified={timestamp} - text fmt - Only send the resource in the response if it has been modified since the RFC 3339 UTC timestamp provided, according to the server's time. Otherwise, reply with a ``"not_modified"`` response and no body data. + section type + raw + type={identifier}/{identifier} - The RFC 3339 timestamp format should be the following, as a strftime format string format: ``%Y-%m-%dT%H:%M:%SZ``, for example: ``1970-12-31T23:59:30Z``. + text fmt + MIME type of the content being sent in the request body. - The timestamp should usually be either the server's ``"modified"`` parameter value from the time the cached resource was requested or the ``"time"`` parameter value from that request if the former was not provided. If neither was present in the previous response for the current request's intent, the client should not use an ``if_modified`` parameter. + Default value: ``"application/octet-stream"`` - Default value: ``""`` (do not perform this check, just send the resource) + section if_modified + raw + if_modified={timestamp} - section Response - text - CNP requests are answered by a CNP response by the server. Most of the time, the response will probably contain the requested resource. + text fmt + Only send the resource in the response if it has been modified since the RFC 3339 UTC timestamp provided, according to the server's time. Otherwise, reply with a ``"not_modified"`` response and no body data. + The RFC 3339 timestamp format should be the following, as a strftime format string format: ``%Y-%m-%dT%H:%M:%SZ``, for example: ``1970-12-31T23:59:30Z``. - section Intent - text - The intent part of the response header is one of the defined response types. It signifies whether the response contains the resource requested, a redirect, report of an error or other results. + The timestamp should usually be either the server's ``"modified"`` parameter value from the time the cached resource was requested or the ``"time"`` parameter value from that request if the former was not provided. If neither was present in the previous response for the current request's intent, the client should not use an ``if_modified`` parameter. + Default value: ``""`` (do not perform this check, just send the resource) - section ok - text - The request was successfully resolved and the response body contains the requested resource. + section Response + text + CNP requests are answered by a CNP response by the server. Most of the time, the response will probably contain the requested resource. - section not_modified - text fmt - The resource has not been modified since the time in the request's ``"if_modified"`` parameter. The response body is blank and the client should use the cached resource. + section Intent + text + The intent part of the response header is one of the defined response types. It signifies whether the response contains the resource requested, a redirect, report of an error or other results. - section redirect - text fmt - The client should make a new request to the location provided in the ``"location"`` parameter. The response body may contain a page as if it was an ``"ok"`` response. - The new request should be blank (contain no body data, as if that path was just entered anew by the user). + section ok + text + The request was successfully resolved and the response body contains the requested resource. - Clients are not required to follow the redirect. Servers should not assume that a client will always follow the redirect immediately or at all. Interactive user agents may prompt the user for confirmation before opening the new page. Otherwise, following redirects up to a certain count is generally the expected behavior. - User agents do not have to display the provided page and may directly perform the redirect. If the redirect is not performed and a page was provided, it should be displayed instead. + section not_modified + text fmt + The resource has not been modified since the time in the request's ``"if_modified"`` parameter. The response body is blank and the client should use the cached resource. - section error - text fmt - There was an error answering the request. The server must also provide the ``"reason"`` response parameter. The body data may contain a page as if it was an ``"ok"`` response. + section redirect + text fmt + The client should make a new request to the location provided in the ``"location"`` parameter. The response body may contain a page as if it was an ``"ok"`` response. - User agents do not have to display the provided page and may just inform the user of the error reason. If a page is provided, it should be used to inform the user of the details of the error. + The new request should be blank (contain no body data, as if that path was just entered anew by the user). + Clients are not required to follow the redirect. Servers should not assume that a client will always follow the redirect immediately or at all. Interactive user agents may prompt the user for confirmation before opening the new page. Otherwise, following redirects up to a certain count is generally the expected behavior. - section Parameters - text - The following response parameters are defined (default value is assumed if the parameter value is blank; any absent parameter must be treated as if it had the default value): + User agents do not have to display the provided page and may directly perform the redirect. If the redirect is not performed and a page was provided, it should be displayed instead. - section length - raw - length={number} + section error + text fmt + There was an error answering the request. The server must also provide the ``"reason"`` response parameter. The body data may contain a page as if it was an ``"ok"`` response. - text fmt - The length of the response body data in bytes. + User agents do not have to display the provided page and may just inform the user of the error reason. If a page is provided, it should be used to inform the user of the details of the error. - If this parameter is not provided or is blank, the client should read all data until the connection is closed, end of file is reached or equivalent. Despite that, the length parameter should be sent whenever possible. - Valid in all response types. + section Parameters + text + The following response parameters are defined (default value is assumed if the parameter value is blank; any absent parameter must be treated as if it had the default value): - Default value: ``""`` (read until EOF) + section length + raw + length={number} - section name - raw - name={identifier} + text fmt + The length of the response body data in bytes. - text fmt - The name of the content being sent in the response body. Must not contain slashes (``0x2f``) or NUL bytes (``0x00``), including escaped NUL bytes (``\0``). + If this parameter is not provided or is blank, the client should read all data until the connection is closed, end of file is reached or equivalent. Despite that, the length parameter should be sent whenever possible. - Can be used to provide filename metadata. If the original filename was a Unicode filename instead of a bytestring, UTF-8 should be used to encode it. + Valid in all response types. - Valid in response types where the body data can be file (``ok``, ``redirect``, ``error``). + Default value: ``""`` (read until EOF) - Default value: ``""`` (no name provided) + section name + raw + name={identifier} - section type - raw - type={identifier}/{identifier} + text fmt + The name of the content being sent in the response body. Must not contain slashes (``0x2f``) or NUL bytes (``0x00``), including escaped NUL bytes (``\0``). - text fmt - MIME type of the content being sent in the response body. + Can be used to provide filename metadata. If the original filename was a Unicode filename instead of a bytestring, UTF-8 should be used to encode it. - Valid in response types where the body data can be file (``ok``, ``redirect``, ``error``). + Valid in response types where the body data can be file (``ok``, ``redirect``, ``error``). - Default value: ``"application/octet-stream"`` + Default value: ``""`` (no name provided) - section time - raw - time={timestamp} + section type + raw + type={identifier}/{identifier} - text fmt - The current time on the server as an RFC 3339 UTC timestamp. + text fmt + MIME type of the content being sent in the response body. - May be sent with any response type, but most useful in the ``"ok"`` response, where it may be used by the client in an ``"if_modified"`` request parameter later. + Valid in response types where the body data can be file (``ok``, ``redirect``, ``error``). - Default value: ``""`` (no timestamp provided) + Default value: ``"application/octet-stream"`` - section modified - raw - modified={timestamp} + section time + raw + time={timestamp} - text fmt - RFC3339 UTC timestamp representing the time the requested file was last modified. + text fmt + The current time on the server as an RFC 3339 UTC timestamp. - Valid in ``"ok"`` and ``"not_modified"`` responses, where it may be used by the client in an ``"if_modified"`` request parameter later. + May be sent with any response type, but most useful in the ``"ok"`` response, where it may be used by the client in an ``"if_modified"`` request parameter later. - Default value: ``""`` (no timestamp provided) + Default value: ``""`` (no timestamp provided) - section location - raw - location={identifier}/{identifier} + section modified + raw + modified={timestamp} - text fmt - The location to redirect to in the format of a CNP request intent. + text fmt + RFC 3339 UTC timestamp representing the time the requested file was last modified. - If the host part of the intent in the value is empty, the current host should be reused. If the host is ``"."``, the current host should be reused and the path should be appended to the current path, excluding the last filename after the final slash in the current path (if any). Otherwise, the new request should be sent to the provided host, which has to be resolved to a server address (instead of just sending a request with the new host to the current server). + Valid in ``"ok"`` and ``"not_modified"`` responses, where it may be used by the client in an ``"if_modified"`` request parameter later. - For example, if the request was sent to ``"example.com/foo/bar"`` and the redirect location was ``"/baz"``, the new request's intent is ``"example.com/baz"``, but if the location parameter was ``"./baz"``, the new intent is ``"example.com/foo/baz"``. + Default value: ``""`` (no timestamp provided) - Valid in ``"redirect"`` response type. - Default value: ``""`` (not providing this parameter in a redirect response is an error, no redirect happens) + section location + raw + location={identifier}/{identifier} + text fmt + The location to redirect to in the format of a CNP request intent. - section reason - raw - reason={identifier} + If the host part of the intent in the value is empty, the current host should be reused. If the host is ``"."``, the current host should be reused and the path should be appended to the current path, excluding the last filename after the final slash in the current path (if any). Otherwise, the new request should be sent to the provided host, which has to be resolved to a server address (instead of just sending a request with the new host to the current server). - text - Describes the reason for the error. + For example, if the request was sent to ``"example.com/foo/bar"`` and the redirect location was ``"/baz"``, the new request's intent is ``"example.com/baz"``, but if the location parameter was ``"./baz"``, the new intent is ``"example.com/foo/baz"``. - Defined values: + Valid in ``"redirect"`` response type. - list - text fmt - ``syntax``: the request was not a valid CNP message + Default value: ``""`` (not providing this parameter in a redirect response is an error, no redirect happens) - text fmt - ``version``: the request CNP version is not supported by the server - text fmt - ``invalid``: the received CNP message is not a valid CNP request (invalid intent format, invalid value of a defined parameter) + section reason + raw + reason={identifier} - text fmt - ``not_supported``: a requested feature is not supported by the server, so the request cannot be answered + text + Describes the reason for the error. - text fmt - ``too_large``: the server does not want to accept so much data (either header or body) + Defined values: - text fmt - ``not_found``: the requested path was not found on the server + list + text fmt + ``syntax``: the request was not a valid CNP message - text fmt - ``denied``: server does not allow access to this content (might require authentication first) + text fmt + ``version``: the request CNP version is not supported by the server - text fmt - ``rejected``: the request did not match the server's requirements for that path, but was a valid CNP request (e.g. missing parameters the application requires or an API call provided incorrect type of data) + text fmt + ``invalid``: the received CNP message is not a valid CNP request (invalid intent format, invalid value of a defined parameter) - text fmt - ``server_error``: internal server error + text fmt + ``not_supported``: a requested feature is not supported by the server, so the request cannot be answered text fmt - Valid in ``"error"`` response type. + ``too_large``: the server does not want to accept so much data (either header or body) - Default value: ``"server_error"`` (servers should provide this parameter in the ``"reason"`` response if possible) + text fmt + ``not_found``: the requested path was not found on the server + text fmt + ``denied``: server does not allow access to this content (might require authentication first) - section EBNF - raw ebnf - raw_character = ? any byte except "\0", "\n", " ", "=", "\\" ? ; - escaped_character = "\\" ( "0" | "n" | "_" | "-" | "\\" ) ; - ident_character = raw_character | escaped_character ; - identifier = ident_character, { ident_character } ; - number = "0" | ( "1" … "9" ), { "0" … "9" } ; + text fmt + ``rejected``: the request did not match the server's requirements for that path, but was a valid CNP request (e.g. missing parameters the application requires or an API call provided incorrect type of data) - version = "cnp/", number, ".", number ; - intent = identifier ; - parameter = [ identifier ], "=", [ identifier ] ; + text fmt + ``server_error``: internal server error - header = version, " ", intent, { " ", parameter }, "\n" ; - body = { ? any byte ? } ; + text fmt + Valid in ``"error"`` response type. - message = header, body ; + Default value: ``"server_error"`` (servers should provide this parameter in the ``"reason"`` response if possible) |