mirrors/cosmopolitan
1
0
Fork 0
mirror of https://github.com/jart/cosmopolitan.git synced 2025-02-07 06:53:33 +00:00
Code Issues Projects Releases Packages Wiki Activity Actions

Update definitions.lua with latest progress (#852)

Browse source 
* Update definitions.lua with latest progress

* Remove duplicate definition
This commit is contained in:
Danny Robinson 2023-07-23 19:14:55 +01:00 committed by GitHub
parent 0ffc0dd461
commit ac92f25296
No known key found for this signature in database
GPG key ID: 4AEE18F83AFDEB23
1 changed files with 235 additions and 21 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

256
tool/net/definitions.lua
View file

@ -52,8 +52,6 @@ FLAGS
-b log message bodies
-a log resource usage
-g log handler latency
-e eval Lua code in arg
-F eval Lua code in file
-E show crash reports to public ips
-j enable ssl client verify
-k disable ssl fetch verify
@ -68,6 +66,8 @@ FLAGS
-v increase verbosity [repeatable]
-V increase ssl verbosity [repeatable]
-S increase pledge sandboxing [repeatable]
-e CODE eval Lua code in arg [repeatable]
-F PATH eval Lua code in file [repeatable]
-H K:V sets http header globally [repeatable]
-D DIR overlay assets in local directory [repeatable]
-r /X=/Y redirect X to Y [repeatable]
@ -644,6 +644,8 @@ function OnWorkerStop() end
---@alias uint32 integer Unsigned 32-bit integer
---@alias uint16 integer Unsigned 16-bit integer
---@alias uint8 integer Unsigned 8-bit integer
---@alias int8 integer Signed 8-bit integer
---@class EncoderOptions
---@field useoutput boolean? defaults to `false`. Encodes the result directly to the output buffer and returns `nil` value. This option is ignored if used outside of request handling code.
@ -733,6 +735,23 @@ function LaunchBrowser(path) end
---@nodiscard
function CategorizeIp(ip) end
--- Turns ISO-8859-1 string into UTF-8.
---@param iso_8859_1 string
---@return string UTF8
---@nodiscard
function DecodeLatin1(iso_8859_1) end
--- Turns binary into ASCII base-16 hexadecimal lowercase string.
---@param binary string
---@return string ascii
function EncodeHex(binary) end
--- Turns ASCII base-16 hexadecimal byte string into binary string,
--- case-insensitively. Non-hex characters may not appear in string.
---@param ascii string
---@return string binary
function DecodeHex(ascii) end
--- Decodes binary data encoded as base64.
---
--- This turns ASCII into binary, in a permissive way that ignores
@ -744,13 +763,6 @@ function CategorizeIp(ip) end
---@nodiscard
function DecodeBase64(ascii) end
--- Turns ISO-8859-1 string into UTF-8.
---
---@param iso_8859_1 string
---@return string UTF8
---@nodiscard
function DecodeLatin1(iso_8859_1) end
--- Turns binary into ASCII. This can be used to create HTML data:
--- URIs that do things like embed a PNG file in a web page. See
--- encodebase64.c.
@ -992,13 +1004,13 @@ function EncodeLatin1(utf8, flags) end
--- and everything else gets `%XX` encoded. Please note that `'&` can still break
--- HTML and that `'()` can still break CSS URLs. This function is charset agnostic
--- and will not canonicalize overlong encodings. It is assumed that a UTF-8 string
--- will be supplied. See `kescapefragment.c`.
--- will be supplied. See `kescapefragment.S`.
---@param str string
---@return string
---@nodiscard
function EscapeFragment(str) end
--- Escapes URL host. See `kescapeauthority.c`.
--- Escapes URL host. See `kescapeauthority.S`.
---@param str string
---@return string
---@nodiscard
@ -1022,13 +1034,13 @@ function EscapeLiteral(str) end
--- Escapes URL parameter name or value. The allowed characters are `-.*_0-9A-Za-z`
--- and everything else gets `%XX` encoded. This function is charset agnostic and
--- will not canonicalize overlong encodings. It is assumed that a UTF-8 string
--- will be supplied. See `kescapeparam.c`.
--- will be supplied. See `kescapeparam.S`.
---@param str string
---@return string
---@nodiscard
function EscapeParam(str) end
--- Escapes URL password. See `kescapeauthority.c`.
--- Escapes URL password. See `kescapeauthority.S`.
---@param str string
---@return string
---@nodiscard
@ -1039,7 +1051,7 @@ function EscapePass(str) end
--- gets `%XX` encoded. Please note that `'&` can still break HTML, so the output
--- may need EscapeHtml too. Also note that `'()` can still break CSS URLs. This
--- function is charset agnostic and will not canonicalize overlong encodings.
--- It is assumed that a UTF-8 string will be supplied. See `kescapepath.c`.
--- It is assumed that a UTF-8 string will be supplied. See `kescapepath.S`.
---@param str string
---@return string
---@nodiscard
@ -1050,13 +1062,13 @@ function EscapePath(str) end
--- else gets `%XX` encoded. Please note that `'&` can still break HTML, so the
--- output may need EscapeHtml too. Also note that `'()` can still break CSS URLs.
--- This function is charset agnostic and will not canonicalize overlong encodings.
--- It is assumed that a UTF-8 string will be supplied. See `kescapesegment.c`.
--- It is assumed that a UTF-8 string will be supplied. See `kescapesegment.S`.
---@param str string
---@return string
---@nodiscard
function EscapeSegment(str) end
--- Escapes URL username. See `kescapeauthority.c`.
--- Escapes URL username. See `kescapeauthority.S`.
---@param str string
---@return string
---@nodiscard
@ -1082,6 +1094,16 @@ function EvadeDragnetSurveillance(bool) end
--- - `maxredirects` (default: `5`): sets the number of allowed redirects to
--- minimize looping due to misconfigured servers. When the number is exceeded,
--- the result of the last redirect is returned.
--- - `keepalive` (default = `false`): configures each request to keep the
--- connection open (unless closed by the server) and reuse for the
--- next request to the same host. This option is disabled when SSL
--- connection is used.
--- The mapping of hosts and their sockets is stored in a table
--- assigned to the `keepalive` field itself, so it can be passed to
--- the next call.
--- If the table includes the `close` field set to a true value,
--- then the connection is closed after the request is made and the
--- host is removed from the mapping table.
---
--- When the redirect is being followed, the same method and body values are being
--- sent in all cases except when 303 status is returned. In that case the method
@ -1089,10 +1111,10 @@ function EvadeDragnetSurveillance(bool) end
--- that if these (method/body) values are provided as table fields, they will be
--- modified in place.
---@param url string
---@param body? string|{ headers: table<string,string>, value: string, method: string, body: string, maxredirects: integer? }
---@param body? string|{ headers: table<string,string>, value: string, method: string, body: string, maxredirects: integer?, keepalive: boolean? }
---@return integer status, table<string,string> headers, string body/
---@nodiscard
---@overload fun(url:string, body?: string|{ headers: table<string,string>, value: string, method: string, body: string, maxredirects?: integer }): nil, error: string
---@overload fun(url:string, body?: string|{ headers: table<string,string>, value: string, method: string, body: string, maxredirects?: integer, keepalive: boolean? }): nil, error: string
function Fetch(url, body) end
--- Converts UNIX timestamp to an RFC1123 string that looks like this:
@ -1196,7 +1218,14 @@ function GetHost() end
---@nodiscard
function GetHostOs() end
---@return "X86_64"|"AARCH64"|"POWERPC64"|"S390X" isaname string that describes the host instruction set architecture
--- Returns string describing host instruction set architecture.
---
--- This can return:
---
--- - `"X86_64"` for Intel and AMD systems
--- - `"AARCH64"` for ARM64, M1, and Raspberry Pi systems
--- - `"POWERPC64"` for OpenPOWER Raptor Computing Systems
---@return "X86_64"|"AARCH64"|"POWERPC64"
---@nodiscard
function GetHostIsa() end
@ -1585,9 +1614,13 @@ function ProgramBrand(str) end
--- Configures Cache-Control and Expires header generation for static asset serving.
--- A negative value will disable the headers. Zero means don't cache. Greater than
--- zero asks public proxies and browsers to cache for a given number of seconds.
--- The directive value is added to the Cache-Control header when specified (with
--- "must-revalidate" provided by default) and can be set to an empty string to
--- remove the default value.
--- This should only be called from `/.init.lua`.
---@param seconds integer
function ProgramCache(seconds) end
---@param directive string?
function ProgramCache(seconds, directive) end
--- This function is the same as the -C flag if called from `.init.lua`, e.g.
--- `ProgramCertificate(LoadAsset("/.sign.crt"))` for zip loading or
@ -2117,6 +2150,186 @@ function bin(int) end
---@overload fun(hostname: string): nil, error: string
function ResolveIp(hostname) end
--- Returns `true` if IP address is trustworthy.
--- If the `ProgramTrustedIp()` function has NOT been called then redbean
--- will consider the networks 127.0.0.0/8, 10.0.0.0/8, 172.16.0.0/12,
--- and 192.168.0.0/16 to be trustworthy too. If `ProgramTrustedIp()` HAS
--- been called at some point earlier in your redbean's lifecycle, then
--- it'll trust the IPs and network subnets you specify instead.
--- The network interface addresses used by the host machine are always
--- considered trustworthy, e.g. 127.0.0.1. This may change soon, if we
--- decide to export a `GetHostIps()` API which queries your NIC devices.
---@param ip integer
---@return boolean
function IsTrustedIp(ip) end
--- Trusts an IP address or network
--- This function may be used to configure the `IsTrustedIp()` function
--- which is how redbean determines if a client is allowed to send us
--- headers like X-Forwarded-For (cf `GetRemoteAddr` vs. `GetClientAddr`)
--- without them being ignored. Trusted IPs is also how redbean turns
--- off token bucket rate limiting selectively, so be careful. Here's
--- an example of how you could trust all of Cloudflare's IPs:
---
--- ProgramTrustedIp(ParseIp("103.21.244.0"), 22);
--- ProgramTrustedIp(ParseIp("103.22.200.0"), 22);
--- ProgramTrustedIp(ParseIp("103.31.4.0"), 22);
--- ProgramTrustedIp(ParseIp("104.16.0.0"), 13);
--- ProgramTrustedIp(ParseIp("104.24.0.0"), 14);
--- ProgramTrustedIp(ParseIp("108.162.192.0"), 18);
--- ProgramTrustedIp(ParseIp("131.0.72.0"), 22);
--- ProgramTrustedIp(ParseIp("141.101.64.0"), 18);
--- ProgramTrustedIp(ParseIp("162.158.0.0"), 15);
--- ProgramTrustedIp(ParseIp("172.64.0.0"), 13);
--- ProgramTrustedIp(ParseIp("173.245.48.0"), 20);
--- ProgramTrustedIp(ParseIp("188.114.96.0"), 20);
--- ProgramTrustedIp(ParseIp("190.93.240.0"), 20);
--- ProgramTrustedIp(ParseIp("197.234.240.0"), 22);
--- ProgramTrustedIp(ParseIp("198.41.128.0"), 17);
---
--- Although you might want consider trusting redbean's open source
--- freedom embracing solution to DDOS protection instead!
---@param ip integer
---@param cidr integer?
function ProgramTrustedIp(ip, cidr) end
--- Enables DDOS protection.
---
--- Imagine you have 2**32 buckets, one for each IP address. Each bucket
--- can hold about 127 tokens. Every second a background worker puts one
--- token in each bucket. When a TCP client socket is opened, it takes a
--- token from its bucket, and then proceeds. If the bucket holds only a
--- third of its original tokens, then redbean sends them a 429 warning.
--- If the client ignores this warning and keeps sending requests, until
--- there's no tokens left, then the banhammer finally comes down.
---
--- function OnServerStart()
--- ProgramTokenBucket()
--- ProgramTrustedIp(ParseIp('x.x.x.x'), 32)
--- assert(unix.setrlimit(unix.RLIMIT_NPROC, 1000, 1000))
--- end
---
--- This model of network rate limiting generously lets people "burst" a
--- tiny bit. For example someone might get a strong craving for content
--- and smash the reload button in Chrome 64 times in a fow seconds. But
--- since the client only get 1 new token per second, they'd better cool
--- their heels for a few minutes after doing that. This amount of burst
--- can be altered by choosing the `reject` / `ignore` / `ban` threshold
--- arguments. For example, if the `reject` parameter is set to 126 then
--- no bursting is allowed, which probably isn't a good idea.
---
--- redbean is programmed to acquire a token immediately after accept()
--- is called from the main server process, which is well before fork()
--- or read() or any Lua code happens. redbean then takes action, based
--- on the token count, which can be accept / reject / ignore / ban. If
--- redbean determines a ban is warrented, then 4-byte datagram is sent
--- to the unix domain socket `/var/run/blackhole.sock` which should be
--- operated using the blackholed program we distribute separately.
---
--- The trick redbean uses on Linux for example is insert rules in your
--- raw prerouting table. redbean is very fast at the application layer
--- so the biggest issue we've encountered in production is are kernels
--- themselves, and programming the raw prerouting table dynamically is
--- how we solved that.
---
--- `replenish` is the number of times per second a token should be
--- added to each bucket. The default value is 1 which means one token
--- is granted per second to all buckets. The minimum value is 1/3600
--- which means once per hour. The maximum value for this setting is
--- 1e6, which means once every microsecond.
---
--- `cidr` is the specificity of judgement. Since creating 2^32 buckets
--- would need 4GB of RAM, redbean defaults this value to 24 which means
--- filtering applies to class c network blocks (i.e. x.x.x.*), and your
--- token buckets only take up 2^24 bytes of RAM (16MB). This can be set
--- to any number on the inclusive interval [8,32], where having a lower
--- number means you use less ram/cpu, but splash damage applies more to
--- your clients; whereas higher numbers means more ram/cpu usage, while
--- ensuring rate limiting only applies to specific compromised actors.
---
--- `reject` is the token count or treshold at which redbean should send
--- 429 Too Many Request warnings to the client. Permitted values can be
--- anywhere between -1 and 126 inclusively. The default value is 30 and
--- -1 means disable to disable (assuming AcquireToken() will be used).
---
--- `ignore` is the token count or treshold, at which redbean should try
--- simply ignoring clients and close the connection without logging any
--- kind of warning, and without sending any response. The default value
--- for this setting is `MIN(reject / 2, 15)`. This must be less than or
--- equal to the `reject` setting. Allowed values are [-1,126] where you
--- can use -1 as a means of disabling `ignore`.
---
--- `ban` is the token count at which redbean should report IP addresses
--- to the blackhole daemon via a unix-domain socket datagram so they'll
--- get banned in the kernel routing tables. redbean's default value for
--- this setting is `MIN(ignore / 10, 1)`. Permitted values are [-1,126]
--- where -1 may be used as a means of disabling the `ban` feature.
---
--- This function throws an exception if the constraints described above
--- are not the case. Warnings are logged should redbean fail to connect
--- to the blackhole daemon, assuming it hasn't been disabled. It's safe
--- to use load balancing tools when banning is enabled, since you can't
--- accidentally ban your own network interface addresses, loopback ips,
--- or ProgramTrustedIp() addresses where these rate limits don't apply.
---
--- It's assumed will be called from the .init.lua global scope although
--- it could be used in interpreter mode, or from a forked child process
--- in which case the only processes that'll have ability to use it will
--- be that same process, and any descendent processes. This function is
--- only able to be called once.
---
--- This feature is not available in unsecure mode.
---@param replenish number?
---@param cidr integer?
---@param reject integer?
---@param ignore integer?
---@param ban integer?
function ProgramTokenBucket(replenish, cidr, reject, ignore, ban) end
--- Atomically acquires token.
---
--- This routine atomically acquires a single token for an `ip` address.
--- The return value is the token count before the subtraction happened.
--- No action is taken based on the count, since the caller will decide.
---
--- `ip` should be an IPv4 address and this defaults to `GetClientAddr()`,
--- although other interpretations of its meaning are possible.
---
--- Your token buckets are stored in shared memory so this can be called
--- from multiple forked processes. which operate on the same values.
---@param ip uint32?
---@return int8
function AcquireToken(ip) end
--- Counts number of tokens in bucket.
---
--- This function is the same as AcquireToken() except no subtraction is
--- performed, i.e. no token is taken.
---
--- `ip` should be an IPv4 address and this defaults to GetClientAddr(),
--- although other interpretations of its meaning are possible.
---@param ip uint32?
---@return int8
function CountTokens(ip) end
--- Sends IP address to blackholed service.
---
--- `ProgramTokenBucket()` needs to be called beforehand. The default
--- settings will blackhole automatically, during the `accept()` loop
--- based on the banned threshold. However if your Lua code calls
--- `AcquireToken()` manually, then you'll need this function to take
--- action on the returned values.
---
--- This function returns true if a datagram could be sent sucessfully.
--- Otherwise false is returned, which can happen if blackholed isn't
--- running, or if a lot of processes are sending messages to it and the
--- operation would have blocked.
---
--- It's assumed that the blackholed service is running locally in the
--- background.
---@param ip uint32
function Blackhole(ip) end
-- MODULES
---Please refer to the LuaSQLite3 Documentation.
@ -3921,7 +4134,8 @@ unix = {
CLOCK_REALTIME_FAST = nil,
--- @type integer
CLOCK_TAI = nil,
---@type integer
CLOCK_THREAD_CPUTIME_ID = nil,
--- @type integer
DT_BLK = nil,
--- @type integer