Verified Commit f4e91ced authored by Karel Koci's avatar Karel Koci 🤘

Add documentation for Lua URI API

parent 1fe00a40
Pipeline #47280 passed with stages
in 4 minutes and 49 seconds
......@@ -123,6 +123,86 @@ Note::
There is some problem with printing from lua to stdout in callback on some
platforms.
URI
---
This allows code to receive resources from URI in general way. To use this you
have to first initialize URI master handler which is intended as a handler for
multiple URIs. You can do that with `uri.new()`. URI master provides you with
following methods:
to_file(uri, path, parent)::
Creates new URI which content will be written to file on provided path. It
returns handler object for created URI.
to_temp_file(uri, template, parent)::
Creates new URI which content will be written to file which name (path) is
generated from provided template ensuring previous non-existence. Template has
to be path to file with six trailing `X`-ses (for example:
`/tmp/updater-XXXXXX`). This is intended to be used for temporally files but
removal has to be handled by user. This method returns handler object for
created URI.
to_buffer(uri, parent)::
This creates new URI which content is received to internal buffer and is
provided to called on URI finish. It returns handler object for created URI.
download()::
Runs download for all URIs created by given master. It returns `nil` on no error
or an problematic URI handler.
The methods that create new URI handler objects take as an optional argument
`parent`. This can be some other URI handler and in that case created URI is
derived from it. It inherits same settings and if `uri` is just an relative one
then it is combined with parent one.
URI handler is object that provides you with following methods:
uri()::
This returns string representation of URI. Note that it is canonized and it
might not be same as the string provided to `uri` argument of method that
creates URI handler.
path()::
This returns UNIX path for `file` scheme URI. Note that this should be called
only on `file` scheme URIs and not to any others. This can be used to get path
to file from URI without even finishing it.
output_path()::
This returns path to output file. Note that this is only valid for handlers
create with `to_file` and `to_temp_file` method. In case of `to_file` it returns
same path as specified to `path` argument. In case of `to_temp_file` it returns
path that was generated from provided template.
is_local()::
Returns boolean whatever this URI is considered local or not. URIs that are
considered local can be finished without first calling to `download()` method of
their respective URI master.
finish()::
Finishes URI in form of reporting errors and output syncing and in case of URI
created with `to_buffer` it also returns as a second argument received content.
set_ssl_verify(enable)::
Sets if SSL certificate should be verified for `https` scheme.
add_ca(ca)::
Adds given CA URI as the one that is considered when certificates are verified.
You can pass `nil` and in such case all previously added CAs are dropped and
system certificates are used instead. `ca` argument URI has to be local one,
otherwise an error is raised.
add_crl(crl)::
Add given CRL URI as the one that is considered when certificates are verified.
You can pass `nil` and in such case all previously added CRLs are dropped and
CRL verification is disabled. `crl` argument URI has to be local one otherwise
an error is raised.
set_ocsp(enable)::
Sets if OCSP should be used to check for certificate validity.
add_pubkey(pubkey)::
Adds given public key to the list of considered keys when signature is verified.
You can pass `nil` and inc such case all previously added keys are dropped and
signatures verification is disabled. `pubkey` URI has to be only local one,
otherwise an error is raised.
set_sig(signature)::
Sets path to signature file for given URI. You can pass `nil` and in such case
default signature is generated for given URI, that is `.sig` is appended to URI.
If this is not called at all and some public keys are provided then default
signature URI is used.
download_error()::
This method returns string describing why download of URI failed. This should be
called only on instances that were returned by master method `download()`.
Asynchronous events
-------------------
......
Markdown is supported
0% or
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment