HTTP:payload(t)

Manipulates or inspects the buffered HTTP request or response body. This function is a unified interface for performing various operations on the payload data, such as retrieving its size or content, searching, modifying, replacing, or removing parts of it.

Syntax

HTTP:payload(t)

Arguments

Name	Description
t	A table that specifies the operation and its parameters. The table must contain an operation field. Other fields are required or optional depending on the operation.

Events

Applicable in the following events:

• HTTP_DATA_REQUEST

• HTTP_DATA_RESPONSE

Operations

The following sections detail all possible structures for the argument table t.

1. size — Returns the total size (in bytes) of the buffered payload.

2. content — Returns all or part of the buffered payload content as a string.

3. set — Overwrites or inserts data into the buffered payload at a specified location.

4. find — Searches for a string or regular expression within the buffered payload.

5. remove — Removes a string or regular expression from the buffered payload.

6. replace — Replaces all occurrences of a string or regular expression with a new string.

size

Returns the total size (in bytes) of the buffered payload.

Field	Type	Required	Description
operation	String	Yes	Must be set to "size".

Example

when HTTP_DATA_RESPONSE {
t1={}
t1["operation"]="size"
sz=HTTP:payload(t1)
debug("----response data size: %d-----\n", sz)}

content

Returns all or part of the buffered payload content as a string.

Field	Type	Required	Description
operation	String	Yes	Must be set to "content".
offset	Integer	No	The byte offset to start reading from. Default is 0.
size	Integer	No	The number of bytes to read. If missing, returns all data from the offset to the end.

Example

when HTTP_DATA_REQUEST {
t={};
t[“operation”]=”content”;   --return the buffered content
t[“offset”]=12;
t[“size”]=20;
ct = HTTP:payload(t);   --return value is a string containing the buffered content
}

Note: The “offset” and “size” fields are optional. If the “offset” field is missing, zero is assumed. If the “size” field is missing, it will operate on the whole buffered data.

set

Overwrites or inserts data into the buffered payload at a specified location.

Field	Type	Required	Description
operation	String	Yes	Must be set to "set".
offset	Integer	No	The byte offset where the data will be inserted/replaced. Default is 0.
size	Integer	No	The number of existing bytes to be overwritten starting from the offset. If missing, the operation will overwrite from the offset to the end of the buffer with the new data.
data	String	Yes	The new data string to insert.

Example

when HTTP_DATA_REQUEST {
t={};
t[“operation”]=”set” --replace the buffered content by new data
t[“offset”]=12;
t[“size”]=20;
t[“data”]= ”new data to insert”;
ret = HTTP:payload(t); --return value is boolean: false if fail, true if succeed
}

Note: The “offset” and “size” fields are optional. If the “offset” field is missing, zero is assumed. If the “size” field is missing, it will operate on the whole buffered data.

find

Searches for a string or regular expression within the buffered payload.

Field	Type	Required	Description
operation	String	Yes	Must be set to "find".
data	String	Yes	The string or regular expression pattern to search for (e.g., "text" or "t[ex]t").
offset	Integer	No	The byte offset to start searching from. Default is 0.
size	Integer	No	The number of bytes to search within. If missing, searches until the end of the buffer.
scope	String	No	Can be "first" (finds the first occurrence) or "all" (finds all occurrences). Default is "first".

Example

when HTTP_DATA_REQUEST {
t={};
t[“operation”]=”find”
t[“data”]=”sth”; -- can be a regular expression, like (s.h)
t[“offset”]=12;
t[“size”]=20;
t[“scope”]=”first” -- the scope field can be either “first” or “all”
ct = HTTP:payload(t);  --return value is a boolean false if operation fail or the number of occurrences found;
}

Note: The “offset” and “size” fields are optional. If the “offset” field is missing, zero is assumed. If the “size” field is missing, it will operate on the whole buffered data. The “scope” field can be either be “first” or “all”.

remove

Removes a string or regular expression from the buffered payload.

Field	Type	Required	Description
operation	String	Yes	Must be set to "remove".
data	String	Yes	The string or regular expression pattern to remove.
offset	Integer	No	The byte offset to start the operation from. Default is 0.
size	Integer	No	The number of bytes to operate within. If missing, operates on the entire buffer from the offset.
scope	String	No	Can be "first" (remove the first match) or "all" (remove all matches). Default is "first".

Example

when HTTP_DATA_REQUEST {
t={};
t[“operation”]=”remove”
t[“data”]=”sth”; -- can be a regular expression, like (s.h)
t[“offset”]=12;
t[“size”]=20;
t[“scope”]=”first” --"first" or “all”
ct = HTTP:payload(t);  --return value is a boolean false if operation fail or the number of occurrences removed
}

replace

Replaces all occurrences of a string or regular expression with a new string.

Field	Type	Required	Description
operation	String	Yes	Must be set to "replace".
data	String	Yes	The string or regular expression pattern to find.
new_data	String	Yes	The string to replace each match with.
offset	Integer	No	The byte offset to start the operation from. Default is 0.
size	Integer	No	The number of bytes to operate within. If missing, operates on the entire buffer from the offset.
scope	String	No	Can be "first" (remove the first match) or "all" (remove all matches). Default is "first".

Example

when HTTP_DATA_REQUEST {
t={};
t[“operation”]=”replace”
t[“data”]=”sth”; -- can be a regular expression, like (s.h)
t[“new_data”]=”sth new”; --“new_data” field is needed for the “replace” operation.
t[“offset”]=12;
t[“size”]=20;
t[“scope”]=”first” -- or “all”
ct = HTTP:payload(t);  --return value is a boolean false if operation fail or the number of occurrences replaced
}