aboutsummaryrefslogtreecommitdiffstats
path: root/doc/src/manual
diff options
context:
space:
mode:
authorLoïc Hoguin <[email protected]>2017-09-04 14:33:44 +0200
committerLoïc Hoguin <[email protected]>2017-09-04 14:33:44 +0200
commit58e9e76814a8291894ba01ac8a4551e4f8d480b3 (patch)
tree58145af48e5c9dbcec51ffec14bb9faea25c6b24 /doc/src/manual
parent47aa0097ed3f63bf0de1b540a6a8d4086e3d2ea6 (diff)
downloadcowboy-58e9e76814a8291894ba01ac8a4551e4f8d480b3.tar.gz
cowboy-58e9e76814a8291894ba01ac8a4551e4f8d480b3.tar.bz2
cowboy-58e9e76814a8291894ba01ac8a4551e4f8d480b3.zip
Fix more documentation todos
I have decided not to include a manual page for cowboy_stream_h at this point because it clashes with the cowboy_stream manual page. This decision will be revisited in the future.
Diffstat (limited to 'doc/src/manual')
-rw-r--r--doc/src/manual/cowboy.start_clear.asciidoc10
-rw-r--r--doc/src/manual/cowboy.start_tls.asciidoc10
-rw-r--r--doc/src/manual/cowboy_app.asciidoc6
-rw-r--r--doc/src/manual/cowboy_constraints.asciidoc60
-rw-r--r--doc/src/manual/cowboy_constraints.int.asciidoc63
-rw-r--r--doc/src/manual/cowboy_constraints.nonempty.asciidoc62
-rw-r--r--doc/src/manual/cowboy_handler.terminate.asciidoc18
-rw-r--r--doc/src/manual/cowboy_websocket.asciidoc8
8 files changed, 205 insertions, 32 deletions
diff --git a/doc/src/manual/cowboy.start_clear.asciidoc b/doc/src/manual/cowboy.start_clear.asciidoc
index 7a12a58..3d09935 100644
--- a/doc/src/manual/cowboy.start_clear.asciidoc
+++ b/doc/src/manual/cowboy.start_clear.asciidoc
@@ -47,16 +47,12 @@ ProtocolOpts::
The protocol options are in a map containing all the options for
the different protocols that may be involved when connecting
-to the listener, including HTTP/1.1 and HTTP/2 but also
-subprotocols like Websocket.
-// @todo For Websocket this might change in the future.
+to the listener, including HTTP/1.1 and HTTP/2.
+
The HTTP/1.1 options are documented in the
link:man:cowboy_http(3)[cowboy_http(3)] manual;
-the HTTP/2 options in
-link:man:cowboy_http2(3)[cowboy_http2(3)];
-and the Websocket options in
-link:man:cowboy_websocket(3)[cowboy_websocket(3)].
+and the HTTP/2 options in
+link:man:cowboy_http2(3)[cowboy_http2(3)].
== Return value
diff --git a/doc/src/manual/cowboy.start_tls.asciidoc b/doc/src/manual/cowboy.start_tls.asciidoc
index 1cf87c9..8d2131a 100644
--- a/doc/src/manual/cowboy.start_tls.asciidoc
+++ b/doc/src/manual/cowboy.start_tls.asciidoc
@@ -47,16 +47,12 @@ ProtocolOpts::
The protocol options are in a map containing all the options for
the different protocols that may be involved when connecting
-to the listener, including HTTP/1.1 and HTTP/2 but also
-subprotocols like Websocket.
-// @todo For Websocket this might change in the future.
+to the listener, including HTTP/1.1 and HTTP/2.
+
The HTTP/1.1 options are documented in the
link:man:cowboy_http(3)[cowboy_http(3)] manual;
-the HTTP/2 options in
-link:man:cowboy_http2(3)[cowboy_http2(3)];
-and the Websocket options in
-link:man:cowboy_websocket(3)[cowboy_websocket(3)].
+and the HTTP/2 options in
+link:man:cowboy_http2(3)[cowboy_http2(3)].
== Return value
diff --git a/doc/src/manual/cowboy_app.asciidoc b/doc/src/manual/cowboy_app.asciidoc
index bc67959..5825cf9 100644
--- a/doc/src/manual/cowboy_app.asciidoc
+++ b/doc/src/manual/cowboy_app.asciidoc
@@ -20,8 +20,7 @@ Functions:
* link:man:cowboy(3)[cowboy(3)] - Listener management
* link:man:cowboy_req(3)[cowboy_req(3)] - Request and response
* link:man:cowboy_router(3)[cowboy_router(3)] - Router
-
-// @todo What about cowboy_constraints?
+* link:man:cowboy_constraints(3)[cowboy_constraints(3)] - Constraints
Protocols:
@@ -33,9 +32,6 @@ Handlers:
* link:man:cowboy_static(3)[cowboy_static(3)] - Static file handler
-// @todo What about cowboy_stream_h?
-// @todo cowboy_compress_h
-
Behaviors:
* link:man:cowboy_handler(3)[cowboy_handler(3)] - Plain HTTP handlers
diff --git a/doc/src/manual/cowboy_constraints.asciidoc b/doc/src/manual/cowboy_constraints.asciidoc
new file mode 100644
index 0000000..52ee664
--- /dev/null
+++ b/doc/src/manual/cowboy_constraints.asciidoc
@@ -0,0 +1,60 @@
+= cowboy_constraints(3)
+
+== Name
+
+cowboy_constraints - Constraints
+
+== Description
+
+The module `cowboy_constraints` defines the built-in
+constraints in Cowboy and provides an interface for
+manipulating these constraints.
+
+Constraints are functions that define what type of
+input is allowed. They are used throughout Cowboy,
+from the router to query strings to cookies.
+
+== Exports
+
+Built-in constraints:
+
+* link:man:cowboy_constraints:int(3)[cowboy_constraints:int(3)] - Integer constraint
+* link:man:cowboy_constraints:nonempty(3)[cowboy_constraints:nonempty(3)] - Non-empty constraint
+
+== Types
+
+=== constraint()
+
+[source,erlang]
+----
+constraint() :: int | nonempty | fun()
+----
+
+A constraint function.
+
+The atom constraints are built-in, see the corresponding
+function in the exports list above.
+
+=== reason()
+
+[source,erlang]
+----
+reason() :: {constraint(), Reason, Value}
+
+Reason :: any()
+Value :: any()
+----
+
+Reason for the constraint failure.
+
+It includes the constraint function in question,
+a machine-readable error reason and the value that
+made the constraint fail.
+
+== See also
+
+link:man:cowboy(7)[cowboy(7)],
+link:man:cowboy(3)[cowboy(3)],
+link:man:cowboy_router(3)[cowboy_router(3)],
+link:man:cowboy_req:match_cookies(3)[cowboy_req:match_cookies(3)],
+link:man:cowboy_req:match_qs(3)[cowboy_req:match_qs(3)]
diff --git a/doc/src/manual/cowboy_constraints.int.asciidoc b/doc/src/manual/cowboy_constraints.int.asciidoc
new file mode 100644
index 0000000..28855a4
--- /dev/null
+++ b/doc/src/manual/cowboy_constraints.int.asciidoc
@@ -0,0 +1,63 @@
+= cowboy_constraints:int(3)
+
+== Name
+
+cowboy_constraints:int - Integer constraint
+
+== Description
+
+Constraint functions implement a number of different operations.
+
+[source,erlang]
+----
+int(forward, Bin) -> {ok, Int} | {error, not_an_integer}
+
+Bin :: binary()
+Int :: integer()
+----
+
+Validate and convert the text representation of an integer.
+
+[source,erlang]
+----
+int(reverse, Int) -> {ok, Bin} | {error, not_an_integer}
+----
+
+Convert an integer back to its text representation.
+
+[source,erlang]
+----
+int(format_error, Error) -> HumanReadable
+
+Error :: {not_an_integer, Bin | Int}
+HumanReadable :: iolist()
+----
+
+Generate a human-readable error message.
+
+== Arguments
+
+Arguments vary depending on the operation. Constraint
+functions always take the operation type as first argument,
+and the value as second argument.
+
+== Return value
+
+The return value varies depending on the operation.
+
+== Changelog
+
+* *2.0*: Interface modified to allow for a variety of operations.
+* *1.0*: Constraint introduced.
+
+== Examples
+
+This function is not meant to be called directly.
+
+== See also
+
+link:man:cowboy_constraints(3)[cowboy_constraints(3)],
+link:man:cowboy_constraints:nonempty(3)[cowboy_constraints:nonempty(3)],
+link:man:cowboy_router(3)[cowboy_router(3)],
+link:man:cowboy_req:match_cookies(3)[cowboy_req:match_cookies(3)],
+link:man:cowboy_req:match_qs(3)[cowboy_req:match_qs(3)]
diff --git a/doc/src/manual/cowboy_constraints.nonempty.asciidoc b/doc/src/manual/cowboy_constraints.nonempty.asciidoc
new file mode 100644
index 0000000..0c25b4b
--- /dev/null
+++ b/doc/src/manual/cowboy_constraints.nonempty.asciidoc
@@ -0,0 +1,62 @@
+= cowboy_constraints:nonempty(3)
+
+== Name
+
+cowboy_constraints:nonempty - Non-empty constraint
+
+== Description
+
+Constraint functions implement a number of different operations.
+
+[source,erlang]
+----
+nonempty(forward | reverse, <<>>) -> {error, empty}
+----
+
+Reject empty values.
+
+[source,erlang]
+----
+nonempty(forward | reverse, Bin) -> {ok, Bin}
+
+Bin :: binary()
+----
+
+Accept any other binary values.
+
+[source,erlang]
+----
+nonempty(format_error, Error) -> HumanReadable
+
+Error :: {empty, Bin}
+HumanReadable :: iolist()
+----
+
+Generate a human-readable error message.
+
+== Arguments
+
+Arguments vary depending on the operation. Constraint
+functions always take the operation type as first argument,
+and the value as second argument.
+
+== Return value
+
+The return value varies depending on the operation.
+
+== Changelog
+
+* *2.0*: Interface modified to allow for a variety of operations.
+* *1.0*: Constraint introduced.
+
+== Examples
+
+This function is not meant to be called directly.
+
+== See also
+
+link:man:cowboy_constraints(3)[cowboy_constraints(3)],
+link:man:cowboy_constraints:int(3)[cowboy_constraints:int(3)],
+link:man:cowboy_router(3)[cowboy_router(3)],
+link:man:cowboy_req:match_cookies(3)[cowboy_req:match_cookies(3)],
+link:man:cowboy_req:match_qs(3)[cowboy_req:match_qs(3)]
diff --git a/doc/src/manual/cowboy_handler.terminate.asciidoc b/doc/src/manual/cowboy_handler.terminate.asciidoc
index f10d945..c995ba3 100644
--- a/doc/src/manual/cowboy_handler.terminate.asciidoc
+++ b/doc/src/manual/cowboy_handler.terminate.asciidoc
@@ -8,12 +8,12 @@ cowboy_handler:terminate - Terminate the handler
[source,erlang]
----
-terminate(Reason, Req | undefined, State, Handler) -> ok
+terminate(Reason, PartialReq, State, Handler) -> ok
-Reason :: any()
-Req :: cowboy_req:req()
-State :: any()
-Handler :: module()
+Reason :: any()
+PartialReq :: map()
+State :: any()
+Handler :: module()
----
Call the optional terminate callback if it is defined.
@@ -27,13 +27,13 @@ Reason::
Reason for termination.
-Req::
+PartialReq::
The Req object.
+
-It is possible to pass `undefined` if the handler has no concept
-of requests/responses and discarded the Req object before calling
-this function.
+It is possible to remove fields from the Req object to save memory
+when the handler has no concept of requests/responses. The only
+requirement is that a map is provided.
State::
diff --git a/doc/src/manual/cowboy_websocket.asciidoc b/doc/src/manual/cowboy_websocket.asciidoc
index 7979b97..2421ae8 100644
--- a/doc/src/manual/cowboy_websocket.asciidoc
+++ b/doc/src/manual/cowboy_websocket.asciidoc
@@ -25,9 +25,10 @@ websocket_init(State) -> CallResult %% optional
websocket_handle(InFrame, State) -> CallResult
websocket_info(Info, State) -> CallResult
-terminate(Reason, undefined, State) -> ok %% optional
+terminate(Reason, PartialReq, State) -> ok %% optional
Req :: cowboy_req:req()
+PartialReq :: map()
State :: any()
Opts :: cowboy_websocket:opts()
InFrame :: {text | binary | ping | pong, binary()}
@@ -74,9 +75,8 @@ tuple).
The optional `terminate/3` callback will ultimately be called
with the reason for the termination of the connection. This
-callback is common to all handlers. Note that Websocket has
-no concept of requests so it sets the second argument to
-undefined.
+callback is common to all handlers. Note that Websocket will
+not provide the full Req object by default, to save memory.
Cowboy will terminate the process right after closing the
Websocket connection. This means that there is no need to