Relintai/pandemonium_engine
1
0
Fork 0
mirror of https://github.com/Relintai/pandemonium_engine.git synced 2024-12-19 02:16:51 +01:00
Code Issues Packages Projects Releases Wiki Activity
b7d732b782
pandemonium_engine/modules/web/doc_classes/WebServerRequest.xml

385 lines
20 KiB
XML
Raw Blame History

<?xml version="1.0" encoding="UTF-8" ?>
<class name="WebServerRequest" inherits="Reference" version="3.8">
<brief_description>
The [WebServerRequest] class represents one incoming HTTP request. It also contains the proper helper methods for sending a response.
</brief_description>
<description>
The [WebServerRequest] class represents one incoming HTTP request. It also contains the proper helper methods for sending a response.
Since HTML documents has a relatively fixed structure, this class contains head, body, footer properties, the response HTML can be added to these, and then these can be compiled and sent using [code]compile_body()[/code] or the [code]compile_and_send_body()[/code] helpers into the [code]compiled_body[/code] property. This adds an html5 type declaration then the opening [code]html[/code] tag, then the contents of the head variable to the [code]head[/code] section of the response, and then the contents of the body then footer variable into the [code]body[/code] section of the response, then it closes the main [code]html[/code] tag. It also contains helper methods for sending files, handling cookies, storing sessions, storing custom data etc.
CSRF tokens are also supported. These are generated string tokens that are stored in HTTPSessions, but since they are universally needed, helper methods were added directly into [WebServerRequest]. They can be used to validate that a form was actually submitted by the user from a page rendered by the application's server itself, in order to mitigate attacks that use the technique called [C]ross [S]ite [R]equest [F]orgery.
This framework uses a stack like url routing model, where the http path is split along forward slashes, and then these get handled going deeper into the given [WebServer]'s [WebNode] hierarchy, effectively using the node structure as a pseudo filesystem. Of course [WebNode]s can decide on handling the request's parameters themselves instead of letting the default hierarchy based routing to take place. For example [BrowsableFolderServeWebPage] uses this to implement a web based file browser. The currently handled segment can be queried using the [code]get_current_path_segment()[/code]. The [code]pop_path()[/code] and [code]push_path()[/code] helper methods can be used to switch segments.
</description>
<tutorials>
</tutorials>
<methods>
<method name="can_create" qualifiers="const">
<return type="bool" />
<description>
Returns true if the active [WebPermission] has create permission for this session. It you don't have a [WebPermission] set, all perissions are enabled for every user.
</description>
</method>
<method name="can_delete" qualifiers="const">
<return type="bool" />
<description>
Returns true if the active [WebPermission] has delete permission for this session. It you don't have a [WebPermission] set, all perissions are enabled for every user.
</description>
</method>
<method name="can_edit" qualifiers="const">
<return type="bool" />
<description>
Returns true if the active [WebPermission] has edit permission for this session. It you don't have a [WebPermission] set, all perissions are enabled for every user.
</description>
</method>
<method name="can_view" qualifiers="const">
<return type="bool" />
<description>
Returns true if the active [WebPermission] has view permission for this session. It you don't have a [WebPermission] set, all perissions are enabled for every user.
</description>
</method>
<method name="compile_and_send_body">
<return type="void" />
<description>
Calls [code]compile_body()[/code], and then [code]send()[/code].
</description>
</method>
<method name="compile_body">
<return type="void" />
<description>
Takes the head, body and footer properties, and merges them into the [code]compiled_body[/code] property. It adds an html5 type declaration, then the opening [code]html[/code] tag, then the contents of the [code]head[/code] property to the [code]head[/code] section of the response, and then the contents of the [code]body[/code] then footer property into the [code]body[/code] section of the response, then it closes the main [code]html[/code] tag.
</description>
</method>
<method name="get_cookie">
<return type="String" />
<argument index="0" name="key" type="String" />
<description>
Returns the value of the cookie [code]key[/code].
</description>
</method>
<method name="get_csrf_token">
<return type="String" />
<description>
A helper method that tries to get the value of the [code]csrf_token[/code] key from the [HTTPSession] set into the [code]session[/code] property.
</description>
</method>
<method name="get_current_path_segment" qualifiers="const">
<return type="String" />
<description>
Returns the currently active path segment. For example if you have [code]http://127.0.0.1/a/b/c[/code], and the current path segment is [code]b[/code], then this will return [code]b[/code].
If you reach the end, it will return an empty String! For example if you have [code]http://127.0.0.1/a/b/c[/code], and the current path segment reached beyond [code]c[/code] (we are at the [WebNode] that has it's [code]uri_segment[/code] set to [code]c[/code]), then this will return empty String. Actually this is how [WebNode]s check whether they need to handle a request themselves or not ([code]if request.get_current_path_segment() == "/": handle_request(request)[/code]).
</description>
</method>
<method name="get_current_segment_index" qualifiers="const">
<return type="int" />
<description>
Returns the index of the currently active path segment. For example if you have [code]http://127.0.0.1/a/b/c[/code], and the current path segment is [code]b[/code], then this will return 1.
</description>
</method>
<method name="get_file_count" qualifiers="const">
<return type="int" />
<description>
Returns how many files were in the http request. Note that only multipart forms can contain files.
</description>
</method>
<method name="get_file_data" qualifiers="const">
<return type="PoolByteArray" />
<argument index="0" name="index" type="int" />
<description>
Returns the file as a PoolByteArray.
</description>
</method>
<method name="get_file_data_str" qualifiers="const">
<return type="String" />
<argument index="0" name="index" type="int" />
<description>
Returns the file as a String.
</description>
</method>
<method name="get_file_file_name" qualifiers="const">
<return type="String" />
<argument index="0" name="index" type="int" />
<description>
Return the file's name that was present in the form itself.
</description>
</method>
<method name="get_file_key" qualifiers="const">
<return type="String" />
<argument index="0" name="index" type="int" />
<description>
Same as get_file_file_name at the moment.
</description>
</method>
<method name="get_file_length" qualifiers="const">
<return type="int" />
<argument index="0" name="index" type="int" />
<description>
Returns the file's length.
</description>
</method>
<method name="get_host" qualifiers="const">
<return type="String" />
<description>
Returns the host which was present in the request header.
</description>
</method>
<method name="get_method" qualifiers="const">
<return type="int" enum="HTTPServerEnums.HTTPMethod" />
<description>
Returns the request's method.
</description>
</method>
<method name="get_next_path_segment" qualifiers="const">
<return type="String" />
<description>
Returns the next path segment. For example if you have [code]http://127.0.0.1/a/b/c[/code], and the current path segment is [code]b[/code], then this will return [code]c[/code].
</description>
</method>
<method name="get_or_create_session">
<return type="HTTPSession" />
<description>
Returns the value of the session property if it's not null, else it will try to create one using the active [HTTPSessionManager].
</description>
</method>
<method name="get_parameter" qualifiers="const">
<return type="String" />
<argument index="0" name="key" type="String" />
<description>
Returns the value that was set in the request header for the given key, or an empty String.
</description>
</method>
<method name="get_path" qualifiers="const">
<return type="String" />
<argument index="0" name="beginning_slash" type="bool" default="false" />
<argument index="1" name="end_slash " type="bool" default="true" />
<description>
Reutrns the path of the request, from the current path segment to the end. For example if you have [code]http://127.0.0.1/a/b/c[/code], and the current segment is [code]b[/code], this will return "b/c/" using the it's default arguments.
</description>
</method>
<method name="get_path_full" qualifiers="const">
<return type="String" />
<description>
Returns the full path of the request. For example if you have [code]http://127.0.0.1/a/b/c[/code], this will return [code]a/b/c[/code].
</description>
</method>
<method name="get_path_segment" qualifiers="const">
<return type="String" />
<argument index="0" name="i" type="int" />
<description>
Reutrns the i-th path segment.
</description>
</method>
<method name="get_path_segment_count" qualifiers="const">
<return type="int" />
<description>
Reutrns how many path segments a request has.
</description>
</method>
<method name="get_remaining_segment_count" qualifiers="const">
<return type="int" />
<description>
Reutrns how manny segments are remaining.
</description>
</method>
<method name="get_server">
<return type="WebServer" />
<description>
Returns the owner [WebServer].
</description>
</method>
<method name="get_url_root" qualifiers="const">
<return type="String" />
<description>
Returns the url up to the current segment prefixed with [code]/[/code]. For example if you have [code]http://127.0.0.1/a/b/c[/code], and the current segment is [code]b[/code], this will return [code]/a/[/code].
</description>
</method>
<method name="get_url_root_add" qualifiers="const">
<return type="String" />
<argument index="0" name="add" type="String" />
<description>
Equivalent to [code]get_url_root() + add[/code];
</description>
</method>
<method name="get_url_root_current" qualifiers="const">
<return type="String" />
<description>
Returns the url up to, including the current segment prefixed with [code]/[/code]. For example if you have [code]http://127.0.0.1/a/b/c[/code], and the current segment is [code]b[/code], this will return [code]/a/b/[/code].
</description>
</method>
<method name="get_url_root_parent" qualifiers="const">
<return type="String" />
<argument index="0" name="parent" type="int" default="1" />
<description>
Returns the url up to, including the current segment - parent, prefixed and postfixed with [code]/[/code]. For example if you have [code]http://127.0.0.1/a/b/c[/code], and the current segment is [code]b[/code], this will return [code]/a/[/code] using it's default arguments.
</description>
</method>
<method name="get_url_root_parent_add" qualifiers="const">
<return type="String" />
<argument index="0" name="add" type="String" />
<description>
Equivalent to [code]get_url_root_parent() + add[/code];
</description>
</method>
<method name="get_url_site" qualifiers="const">
<return type="String" />
<description>
Returns the url up to, including the current segment prefixed with the host, with a [code]/[/code] at the end. For example if you have [code]http://127.0.0.1/a/b/c[/code], and the current segment is [code]b[/code], this will return [code]http://127.0.0.1/a/b/[/code].
</description>
</method>
<method name="get_url_site_add" qualifiers="const">
<return type="String" />
<argument index="0" name="add" type="String" />
<description>
Equivalent to [code]get_url_site() + add[/code];
</description>
</method>
<method name="get_web_root">
<return type="WebNode" />
<description>
Returns the [WebServer]'s root [WebNode].
</description>
</method>
<method name="has_csrf_token">
<return type="bool" />
<description>
Returns whether the active session has a csrf token or not.
</description>
</method>
<method name="parse_files">
<return type="void" />
<description>
Some WebSerber implementations might need a call to this in order to process files in multipart forms. Don't call it manually, these implementations need to call it when needed.
</description>
</method>
<method name="parser_get_path">
<return type="String" />
<description>
Returns the full http path. Mostly intended for internal use. [code]setup_url_stack()[/code] uses this.
</description>
</method>
<method name="pop_path">
<return type="void" />
<description>
Moves the path stack pointer backward once. For example if you have [code]http://127.0.0.1/a/b/c[/code], and the current segment is [code]b[/code], the current segment will become [code]a[/code].
</description>
</method>
<method name="push_path">
<return type="void" />
<description>
Moves the path stack pointer forward once. For example if you have [code]http://127.0.0.1/a/b/c[/code], and the current segment is [code]b[/code], the current segment will become [code]c[/code]. Note that if you have [code]http://127.0.0.1/a/b/c[/code], and the current segment is [code]c[/code], the current segment will become empty String.
</description>
</method>
<method name="response_add_cookie">
<return type="void" />
<argument index="0" name="cookie" type="WebServerCookie" />
<description>
When you eventually send the response, the [WebServerCookie] added here will be added to the message header. If you want to get the receiver to delete a particular cookie, create a [WebServerCookie], add it, and use it's helper deletion related methods, which will end up adding commands to the header when the request is sent that that should (normally) cause the client to delete cookies.
</description>
</method>
<method name="response_get_cookie">
<return type="WebServerCookie" />
<argument index="0" name="index" type="int" />
<description>
Returns a previously added [WebServerCookie]. If you want to access cookie strings that you previously sent to the client, use [code]get_cookie()[/code], this method is so that you can edit cookies before being sent further.
</description>
</method>
<method name="response_get_cookie_count">
<return type="int" />
<description>
Returns the [WebServerCookie] count.
</description>
</method>
<method name="response_remove_cookie">
<return type="void" />
<argument index="0" name="index" type="int" />
<description>
Removes a previously added [WebServerCookie]. If you want to remove a cookie from the client, see [code]response_add_cookie()[/code] and/or [code]response_remove_cookie_simple()[/code].
</description>
</method>
<method name="response_remove_cookie_simple">
<return type="void" />
<argument index="0" name="key" type="String" />
<description>
Helper method that adds a [WebServerCookie], which will ask client to delete the cookie denoted by [code]key[/code] after being sent.
</description>
</method>
<method name="send">
<return type="void" />
<description>
Sends the contents of the compiled_body property as a response.
</description>
</method>
<method name="send_error">
<return type="void" />
<argument index="0" name="error_code" type="int" />
<description>
Sends an error. The default implementation calls the [WebServer]'s root [WebNode]'s [code]handle_error_send_request()[/code] method.
</description>
</method>
<method name="send_file">
<return type="void" />
<argument index="0" name="file_path" type="String" />
<description>
Sends the file at the given path.
</description>
</method>
<method name="send_redirect">
<return type="void" />
<argument index="0" name="location" type="String" />
<argument index="1" name="status_code" type="int" enum="HTTPServerEnums.HTTPStatusCode" default="302" />
<description>
Sends a redirect http header.
</description>
</method>
<method name="set_csrf_token">
<return type="void" />
<argument index="0" name="value" type="String" />
<description>
Sets the pased csrf token to the active session, if there is one.
</description>
</method>
<method name="setup_url_stack">
<return type="void" />
<description>
The [WebServer] needs to call this when it finished parsing a http request header and setting up a [WebServerRequest]. It parses and sets up inbternals for the easy handling of http paths.
</description>
</method>
<method name="validate_csrf_token">
<return type="bool" />
<description>
A helper that validates the csrf token for you.
</description>
</method>
</methods>
<members>
<member name="active_permission" type="WebPermission" setter="set_active_permission" getter="get_active_permission">
Returns the currently active [WebPermission] or null.
</member>
<member name="body" type="String" setter="set_body" getter="get_body" default="&quot;&quot;">
When you call [code]compile_body()[/code] or [code]compile_and_send_body()[/code], the contents of this property will end up in the [code]body[/code] portion of the resulting HTML.
</member>
<member name="compiled_body" type="String" setter="set_compiled_body" getter="get_compiled_body" default="&quot;&quot;">
The contents of this property will be sent as response when you call send(). Normally you should use the [code]head[/code], [code]body[/code], and [code]footer[/code] properties along with [code]compile_body()[/code] or [code]compile_and_send_body()[/code], however you can use this directly when needed.
</member>
<member name="connection_closed" type="bool" setter="set_connection_closed" getter="get_connection_closed" default="false">
The server might set this to true if the connection got closed while handling the request. It's not yet used.
</member>
<member name="footer" type="String" setter="set_footer" getter="get_footer" default="&quot;&quot;">
When you call [code]compile_body()[/code] or [code]compile_and_send_body()[/code], the contents of this property will end up in the bottom of the [code]body[/code] portion of the resulting HTML.
</member>
<member name="head" type="String" setter="set_head" getter="get_head" default="&quot;&quot;">
When you call [code]compile_body()[/code] or [code]compile_and_send_body()[/code], the contents of this property will end up in the [code]head[/code] portion of the resulting HTML.
</member>
<member name="permissions" type="int" setter="set_permissions" getter="get_permissions" default="15">
The currently active permissions. This is updated every time a new WebPermission is activated while routing.
</member>
<member name="session" type="HTTPSession" setter="set_session" getter="get_session">
Use this to access the active session for this [WebServerRequest].
If you want the session property to have a value, it has to be set manually somewhere along the line. Adding a [HTTPSessionManager] as a direct child of your [WebServer] and adding [SessionSetupWebServerMiddleware] to your [WebRoot] can do this for you automatically.
</member>
<member name="status_code" type="int" setter="set_status_code" getter="get_status_code" enum="HTTPServerEnums.HTTPStatusCode" default="200">
The status code that the server will set in the response.
</member>
</members>
<constants>
</constants>
</class>
Reference in New Issue View Git Blame Copy Permalink