脚本开发

JS API 手册 REST API 手册 (仅专业版支持) RingoJS
RingoJS 1.2.1

模块 ringo/utils/http

提供实用功能来处理HTTP请求和响应。 大多数方法仅适用于低级操作。 要开发一个功能齐全的Web应用程序，建议使用专门的Web框架（如 stick）。

Functions

Class Headers

Instance Methods

Class ResponseFilter

Instance Methods

BufferFactory (data, encoding)

将文件上载存储在内存缓冲区中的stream factory。这个函数不是直接调用，而是作为 streamFactory 参数传递给 parseFileUpload()。

缓冲区存储在参数数据对象的value属性中。

Parameters

Object data
String encoding

Headers (headers)

返回一个用作 HTTP 请求header集合的对象。返回的对象提供了以不区分大小写和保留大小写的方式设置，获取和删除其属性的方法。具有相同字段名称的多个header将被合并到一个逗号分隔的字符串中。因此，此函数不支持 Set-Cookie header。

该函数可以用作现有 JavaScript 对象的混合或作为构造函数。

Parameters

Object headers

an existing JS object. If undefined, a new object is created

Headers.prototype. add (name, value)

用给定的名称和值添加header。

Parameters

String name

the header name
String value

the header value

Headers.prototype. contains (name)

查询是否设置了具有给定名称的header

Parameters

String name

the header name

Returns

Boolean

true if a header with this name is set

Headers.prototype. get (name)

使用给定名称获取header的值

Parameters

String name

the header name

Returns

String

the header value

Headers.prototype. set (name, value)

将给定名称的header设置为给定值。

Parameters

String name

the header name
String value

the header value

Headers.prototype. toString ()

以 MIME 格式返回header的字符串表示形式。

Returns

String

a string representation of the headers

Headers.prototype. unset (name)

使用指定名称取消所有 Cookie

Parameters

String name

the header name

ResponseFilter (body, filter)

用于实现 JSGI 响应过滤器的实用程序类。响应的每个部分首先传递给过滤器函数。如果过滤器函数返回一个值，那么该值将传递给 JSGI 响应流。

Parameters

Object body

a JSGI response body
Function filter

a filter function

ResponseFilter.prototype. forEach (fn)

forEach 函数由 JSGI 连接器调用。

Parameters

Function fn

the response handler callback function

TempFileFactory (data, encoding)

存储临时文件中的文件上传的stream factory。这个函数不是直接调用，而是作为 streamFactory 参数传递给 parseFileUpload()。

临时文件的名称存储在参数数据对象的tempfile属性中。

Parameters

Object data
String encoding

canonicalRanges (ranges)

创建范围数组的规范形式。还检查所有范围是否有效，否则引发异常。

Example

// returns [[0,100], [150, 200]]
canonicalRanges([[0,100], [150, 200]]);

// returns [[0,200]]
canonicalRanges([[0,100], [50, 200]]);

// returns [[0, 300]]
canonicalRanges([[0,200], [50, 200], [200, 250], [245, 300]]);

Parameters

Array ranges

array in the form [[startOffset, endOffset], ...]; offsets start at zero

Returns

Array

the input array in the canonical form without overlapping ranges

getMimeParameter (headerValue, paramName)

从 MIME header值中获取参数。例如，使用“Content-Type：text / plain; charset = UTF-8”和“charset”调用此函数将返回“UTF-8”。

Parameters

String headerValue

a header value
String paramName

a MIME parameter name

isFileUpload (contentType)

了解内容类型是否表示此模块可以解析的格式。

Parameters

String contentType

a HTTP request Content-Type header

Returns

Boolean

true if the content type can be parsed as form data by this module

isUrlEncoded (contentType)

了解内容类型是否表示此模块可以解析的格式。

Parameters

String contentType

a HTTP request Content-Type header

Returns

Boolean

true if the content type can be parsed as form data by this module

mergeParameter (params, name, value)

使用方括号属性语法向参数对象添加值。例如，参数 foo [bar] [] [baz] = hello 将产生对象结构 {foo: {bar: [{baz : "hello"}]}}.

Parameters

Object params

the top level parameter object
String name

the parameter name
String value

the parameter value

parseFileUpload (request, params, encoding, streamFactory)

分析多部分 MIME 输入流。

Parameters

Object request

the JSGI request object
Object params

the parameter object to parse into. If not defined a new object is created and returned.
String encoding

optional encoding to apply to non-file parameters. Defaults to "UTF-8".
Function streamFactory

factory function to create streams for mime parts

Returns

Object

an object containing arbitrary parameters as string or uploaded files as an object with the keys name, filename, contentType,value`.

parseParameters (input, params, encoding)

通过 URL 解析表示查询字符串的字符串或二进制对象，或使用指定的编码将数据发布到 JavaScript 对象结构中。它使用“＆”作为参数之间的分隔符，“=”作为分配。

Example

parseParameters("a=1&b=2&b=3&c");
// returns { a: "1", b: ["2","3"], c: ""}

parseParameters("a[]=1&a[]=2&a[]=3");
// returns { a: ["1", "2","3"]}

parseParameters("foo[bar][baz]=hello&foo[bar][boo]=world");
// returns {foo: {bar: {baz: "hello", boo: "world"}}}

Parameters

Binary|String input

a Binary object or string containing the URL-encoded parameters
Object params

optional parameter object to parse into. If undefined a new object is created and returned.
String encoding

a valid encoding name, defaults to UTF-8

Returns

Object

the parsed parameter object

parseRange (rangeStr, size)

解析 HTTP header并返回要提供的范围列表。如果请求了有效的字节范围，则返回范围数组的数组，否则返回 null。

Example

// returns [[0,499]]
parseRange("bytes=0-499", 10000);

// returns [[500,999], [0,499]]
parseRange("bytes=500-999,0-499", 10000);

// returns [[9500,9999]]
parseRange("bytes=-500", 10000);

Parameters

String rangeStr

value of the Range header field
Number size

optional length of the requested data in bytes; -1 indicates an unknown size

Returns

Array

parsed ranges as array in the form [[startOffset, endOffset], ...], offsets start at zero; or null for invalid header values.

setCookie (key, value, days, options)

为创建具有给定名称，值和属性的 cookie 创建 Set-Cookie header的值。

除键和值之外的所有参数都是可选的。 days 参数指定 cookie 到期之前的天数。要立即删除 cookie，请将 days 参数设置为0.如果days为 undefined 或 negative，则会为当前浏览器会话设置 cookie。

Example

setCookie("username", "michi");
setCookie("password", "strenggeheim", 10,
  {path: "/mypath", domain: ".mydomain.org"});

setCookie("foo", "bar", 10,
  { httpOnly: true, secure: true, sameSite: true });

setCookie("foo", "bar", 10,
  { httpOnly: true, secure: true, sameSite: "Lax" })

Parameters

String key

the cookie name
String value

the cookie value
Number|Date days

optional the number of days to keep the cookie, or a Date object with the exact expiry date. If this is undefined or -1, the cookie is set for the current session. If this is 0, the cookie will be deleted immediately.
Object options

optional options argument which may contain the following properties:

  • path - the path on which to set the cookie (defaults to /)
  • domain - the domain on which to set the cookie (defaults to current domain)
  • secure - to only use this cookie for secure connections
  • httpOnly - to make the cookie inaccessible to client side scripts
  • sameSite - first-party-only cookie; asserts browsers not to send cookies along with cross-site requests; default is strict enforcement, any other enforcement can be provided as string.

Returns

String

the Set-Cookie header value

urlEncode (object, separator, equals)

将对象的属性序列化为URL编码的查询字符串。如果某个属性包含一个数组作为值，则该数组将被序列化。

Example

// "foo=bar%20baz"
http.urlEncode({ foo: "bar baz" });

// "foo=bar%20baz&foo=2&foo=3"
http.urlEncode({ foo: ["bar baz", 2, 3] });

// "foo%5Bbar%5D%5B%5D%5Bbaz%5D=hello"
http.urlEncode({foo: {bar: [{baz: "hello"}]}});

Parameters

Object object

an object
String separator

optional string delimiting key-value pairs in the URL, defaults to &
String equals

optional string delimiting a key from its value, defaults to =

Returns

String

a string containing the URL encoded properties of the object