xrust-net 0.3.0

Support for Xrust
Documentation 
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36

# χrust-net

[![crates.io](https://img.shields.io/crates/v/xrust-net.svg)](https://crates.io/crates/xrust-net)
[![Released API docs](https://docs.rs/xrust-net/badge.svg)](https://docs.rs/xrust-net)
[![ALv2 licensed](https://img.shields.io/badge/license-ALv2-blue.svg)](./LICENSE)

Networking support for the [χrust crate](https://gitlab.gnome.org/World/Rust/markup-rs/xrust).

This crate provides a library with a function to resolve a URL to the content of the resource. In other words, it fetches a URL and returns a String containing the document. At a minimum it must support file: and http(s): schemes.

The intended use for this function is in the import and include methods for χrust's xslt module. One of the from_document function's argument is a closure. Use the [resolve](https://gitlab.gnome.org/World/Rust/markup-rs/xrust-net/-/blob/main/src/resolver.rs) function in that closure, for example:

```rust
from_document(
  style,
	Some(Base URI),
	|s| make_document(s),
	|url| resolve(url, &policy),
)
```

NB. the resolver function must be provided with a security policy to allow access to resources, see below.

The resolve function may also be used for external entities when parsing XML documents.

See the test in [resolver.rs](https://gitlab.gnome.org/World/Rust/markup-rs/xrust-net/-/blob/main/src/resolver.rs) for a complete example.

# Security

Accessing files and network resources is a security risk. χrust-net provides security [Feature]s, using χrust's [security mechanism](https://docs.rs/xrust/latest/xrust/security/index.html), to be able to restrict access to file and network resources. Details of the feature is given in the [resolver](https://gitlab.gnome.org/World/Rust/markup-rs/xrust-net/-/blob/main/src/resolver.rs) module.

The resolver is able to control:
* access to a resource, i.e. a file or a URL
* the size of the resource

Since the default is to not permit access to resources, an application must provide a security policy that permits access.