cluster_graph2

From 2e40af7c5fbfc2c057487d12d1b926b11185b6ea Mon Sep 17 00:00:00 2001 From: Carlos Garnacho Date: Mon, 6 Mar 2023 15:24:51 +0100 Subject: docs: Separate sandboxing documentation to its own doc Explain this a bit better, add some diagrams, etc. --- .../images/graph-example-diagram.dot | 28 +++++ .../images/graph-example-diagram.svg | 90 ++++++++++++++++ .../libtracker-sparql/images/sandbox-diagram.dot | 45 ++++++++ .../libtracker-sparql/images/sandbox-diagram.svg | 102 ++++++++++++++++++ docs/reference/libtracker-sparql/meson.build | 1 + docs/reference/libtracker-sparql/overview.md | 25 ----- docs/reference/libtracker-sparql/sandboxing.md.in | 120 +++++++++++++++++++++ 7 files changed, 386 insertions(+), 25 deletions(-) create mode 100644 docs/reference/libtracker-sparql/images/graph-example-diagram.dot create mode 100644 docs/reference/libtracker-sparql/images/graph-example-diagram.svg create mode 100644 docs/reference/libtracker-sparql/images/sandbox-diagram.dot create mode 100644 docs/reference/libtracker-sparql/images/sandbox-diagram.svg create mode 100644 docs/reference/libtracker-sparql/sandboxing.md.in diff --git a/docs/reference/libtracker-sparql/images/graph-example-diagram.dot b/docs/reference/libtracker-sparql/images/graph-example-diagram.dot new file mode 100644 index 000000000..56827d7f3 --- /dev/null +++ b/docs/reference/libtracker-sparql/images/graph-example-diagram.dot @@ -0,0 +1,28 @@ +digraph { + rankdir=LR; + fontname="sans-serif"; + compound=true; + node [shape="box", style="rounded", border=0, fontname="sans-serif"]; + + subgraph cluster_graph2 { + style="rounded"; + color="lightgrey"; + label = "example:B" + tooltip = "example:B" + fontsize=10; + item2[label="example:item2",tooltip="example:item2"]; + type2[label="rdfs:Resource",tooltip="rdfs:Resource"]; + item2 -> type2 [label="rdf:type",fontsize=10,fontname="sans-serif",tooltip="rdf:type",labeltooltip="rdf:type"]; + } + + subgraph cluster_graph1 { + style="rounded"; + color="lightgrey"; + label = "example:A" + tooltip = "example:A" + fontsize=10; + item1[label="example:item1",tooltip="example:item1"]; + type1[label="rdfs:Resource",tooltip="rdfs:Resource"]; + item1 -> type1 [label="rdf:type",fontsize=10,fontname="sans-serif",tooltip="rdf:type",labeltooltip="rdf:type"]; + } +} diff --git a/docs/reference/libtracker-sparql/images/graph-example-diagram.svg b/docs/reference/libtracker-sparql/images/graph-example-diagram.svg new file mode 100644 index 000000000..384bb9c57 --- /dev/null +++ b/docs/reference/libtracker-sparql/images/graph-example-diagram.svg @@ -0,0 +1,90 @@ + + + + + diff --git a/docs/reference/libtracker-sparql/images/sandbox-diagram.dot b/docs/reference/libtracker-sparql/images/sandbox-diagram.dot new file mode 100644 index 000000000..d8b9c505b --- /dev/null +++ b/docs/reference/libtracker-sparql/images/sandbox-diagram.dot @@ -0,0 +1,45 @@ +graph { + rankdir=LR; + fontname="sans-serif"; + compound=true; + node [shape="box", style="rounded", border=0, fontname="sans-serif"]; + + subgraph cluster_session { + style="rounded"; + color="lightgrey"; + label = "User session" + tooltip = "User session" + fontsize=10; + + Portal; + node [shape="cylinder"];"Provider #1"; "Provider #2"; + + "Provider #1" -- Portal; + "Provider #2" -- Portal; + } + + subgraph cluster_client1 { + style="dashed"; + color="lightgrey"; + label = "Sandbox #1" + tooltip = "Sandbox #1" + fontsize=10; + "App A"; + node [shape="cylinder"]; "Provider #3"; + "App A" -- "Provider #3"; + } + + subgraph cluster_client2 { + style="dashed"; + color="lightgrey"; + label = "Sandbox #2" + tooltip = "Sandbox #2" + fontsize=10; + "App B"; + node [shape="cylinder";style="invis"]; "Provider #4"; + "App B" -- "Provider #4" [style="invis"]; + } + + Portal -- "App A" [lhead=cluster_client1]; + Portal -- "App B" [lhead=cluster_client2]; +} diff --git a/docs/reference/libtracker-sparql/images/sandbox-diagram.svg b/docs/reference/libtracker-sparql/images/sandbox-diagram.svg new file mode 100644 index 000000000..ac643ad10 --- /dev/null +++ b/docs/reference/libtracker-sparql/images/sandbox-diagram.svg @@ -0,0 +1,102 @@ + + + + + diff --git a/docs/reference/libtracker-sparql/meson.build b/docs/reference/libtracker-sparql/meson.build index e49b31d8a..43f2e8880 100644 --- a/docs/reference/libtracker-sparql/meson.build +++ b/docs/reference/libtracker-sparql/meson.build @@ -89,6 +89,7 @@ endforeach generated_content_files = [ 'examples.md.in', 'tutorial.md.in', + 'sandboxing.md.in', ] generated_content = [] diff --git a/docs/reference/libtracker-sparql/overview.md b/docs/reference/libtracker-sparql/overview.md index 949d81c3f..cf183fe3d 100644 --- a/docs/reference/libtracker-sparql/overview.md +++ b/docs/reference/libtracker-sparql/overview.md @@ -32,28 +32,3 @@ one exposed by Tracker Miner FS, use [ctor@Tracker.SparqlConnection.bus_new]. To connect to another a database on a remote machine, use [ctor@Tracker.SparqlConnection.remote_new]. This can be used to query online databases that provide a SPARQL endpoint, such as [DBpedia](https://wiki.dbpedia.org/about). - . -## Connecting from Flatpak - -Tracker SPARQL provides a portal for the [Flatpak](https://flatpak.org/) -application sandboxing system. This lets you control which parts of a -database each app can query. - -The app's Flatpak manifest needs to specify which graph(s) the app will -access. See the [example app](https://gitlab.gnome.org/GNOME/tracker/-/blob/master/examples/flatpak/org.example.TrackerSandbox.json) -and the [portal documentation](https://gnome.pages.gitlab.gnome.org/tracker/docs/commandline/#tracker-xdg-portal-3) to see how. - -No code changes are needed in the app, as [ctor@Tracker.SparqlConnection.bus_new] -will automatically try connect via the portal if it can't talk to the -given D-Bus name directly. - -Tracker SPARQL is included in the -[GNOME Flatpak SDK and runtime](https://docs.flatpak.org/en/latest/available-runtimes.html#gnome). -If the app uses a different runtime, you may need to build Tracker -SPARQL in the app manifest. - -The app might use the Tracker Miner FS search index. Ideally this is done via the portal, -using the search index maintained on the host. Since not all OSes ship tracker-miner-fs-3, -we recommend that apps bundle it inside the Flatpak and connect to the bundled version as -a fallback. See [GNOME Music](https://gitlab.gnome.org/GNOME/gnome-music/) -for an example of how to do this. diff --git a/docs/reference/libtracker-sparql/sandboxing.md.in b/docs/reference/libtracker-sparql/sandboxing.md.in new file mode 100644 index 000000000..02fdb0613 --- /dev/null +++ b/docs/reference/libtracker-sparql/sandboxing.md.in @@ -0,0 +1,120 @@ +Title: Sandboxing and portals +slug: sandboxing-and-portals + +There are times when it does make sense to lend advanced querying +capabilities around your data to other processes of the same machine, +or even widely available to any application that might want to make +use of it. One real life example of this is [Tracker Miners](https://gitlab.gnome.org/GNOME/tracker-miners) +used as the [GNOME Desktop](https://gnome.org) indexer. + +But in this day and age, it is naive to make this data available +without constraints on what data can be accessed. Tracker provides a +portal for the [Flatpak](https://flatpak.org/) application sandboxing +system. This provides the mechanisms to filter the available data for +sandboxed users. + +# How it works + +The portal acts as a single entry point for sandboxed applications +to have read access to any D-Bus SPARQL endpoint. + +

+{{ images/sandbox-diagram.svg }} +

+ +The partitioning of the data is decided by the data provider at +the time of inserting this data in the RDF triple store, and relies +on graphs as the natural partitioning scheme of RDF data. As an +example, consider the following updates: + +```SPARQL +INSERT DATA { + GRAPH example:A { + example:item1 a rdfs:Resource ; + } + + GRAPH example:B { + example:item2 a rdfs:Resource ; + } +} +``` + +Resulting in the following simple diagram: + +

+{{ images/graph-example-diagram.svg }} +

+ +At that point, SPARQL queries may target either, both or any graph, e.g.: + +```SPARQL +# This will return example:item1 +SELECT ?element +FROM example:A +{ + ?element a rdfs:Resource +} +``` + +Or perhaps even poke at non-existing graphs: + +```SPARQL +# This will return no elements +SELECT ?element +FROM example:C +{ + ?element a rdfs:Resource +} +``` + +Graphs may overlap with other graphs, or extend each other. + +The data filtering performed by the portal strongly relies on these RDF +semantics for graphs, except that graph access is enforced through the +[`CONSTRAINT` syntax](sparql-and-tracker.html#constraint-syntax). These +policies prevail over any other SPARQL syntax to specify graphs, and +will result in filtered graphs being replaced by an empty graph. + +Likewise, notification of changes through [class@Tracker.Notifier] will +be filtered on the way to sandboxed applications, so that there are only +notifications on changes from the allowed graphs. + +# Using it from data providers + +Data providers are free to decide the data partitioning scheme available +to sandboxed applications, by creating graphs and inserting data to +those. Access to those graphs will be policied by the portal on their +behalf. + +Keep in mind that there are limits on the [number of graphs](limits.html#limits-on-the-number-of-graphs) +that apply on graph creation. + +# Using it from applications + +The portal is transparently integrated in the Tracker library. Applications +may write SPARQL queries so that they work the same while sandboxed or not. +No code changes are needed in the app, as [ctor@Tracker.SparqlConnection.bus_new] +will automatically try connect via the portal if it can not talk to the +given D-Bus name directly. + +The policy on the accessed graphs is usually defined in the flatpak manifest +at the time of bundling the software, e.g.: + +```json +{ + "finish-args" : [ + "--add-policy=Tracker3.dbus:org.example.Endpoint=example:A", + "--add-policy=Tracker3.dbus:org.example.Endpoint=example:B" + ] +} +``` + +The portal will pick the policy from the `/.flatpak-info` file created +by Flatpak, and (with the example arguments) allow access to graphs `example:A` +and `example:B` from the `org.example.Endpoint` D-Bus SPARQL endpoint. +Access to other graphs, or other services will be disallowed. + +The Tracker library is included in the +[GNOME Flatpak SDK and runtime](https://docs.flatpak.org/en/latest/available-runtimes.html#gnome). +If the app uses a different runtime, you may need to build Tracker +SPARQL in the app manifest. -- cgit v1.2.1 From 688d1a55c2091d3bedc7e305e01dc9fdbf34571f Mon Sep 17 00:00:00 2001 From: Carlos Garnacho Date: Mon, 6 Mar 2023 16:43:24 +0100 Subject: manpages: Do not recommend broken API commands The flatpak CLI parsing for additional policies changes at some point so that it is not possible to specify multiple values in a single call. Doing that results in the ';' being escaped, and the full string to be interpreted as a single value. In order to add multiple values, --add-policy can be called multiple times, recommend that in our manpage for the task. --- docs/manpages/tracker-xdg-portal-3.1.txt | 4 +++- 1 file changed, 3 insertions(+), 1 deletion(-) diff --git a/docs/manpages/tracker-xdg-portal-3.1.txt b/docs/manpages/tracker-xdg-portal-3.1.txt index 664db5b77..fe2884cdf 100644 --- a/docs/manpages/tracker-xdg-portal-3.1.txt +++ b/docs/manpages/tracker-xdg-portal-3.1.txt @@ -34,7 +34,9 @@ This will allow access to the endpoints behind the *org.example.SparqlEndpoint1* This policy can be set when building or running the sandboxed application through the --add-policy option. This can be set via **finish-args** in the flatpak manifest, specified along the build chain in *flatpak-build-finish*(1), or modified at start time with *flatpak-run*(1). For example: $ flatpak run \ - --add-policy=Tracker3.dbus:org.example.SparqlEndpoint1=graphA;graphB;default \ + --add-policy=Tracker3.dbus:org.example.SparqlEndpoint1=graphA \ + --add-policy=Tracker3.dbus:org.example.SparqlEndpoint1=graphB \ + --add-policy=Tracker3.dbus:org.example.SparqlEndpoint1=default \ --add-policy=Tracker3.dbus:org.example.SparqlEndpoint2=* \ org.freedesktop.TrackerSandbox -- cgit v1.2.1 From 08db9139999f2f06adb463604581fe1479542ceb Mon Sep 17 00:00:00 2001 From: Carlos Garnacho Date: Sun, 12 Mar 2023 18:44:40 +0100 Subject: docs: Refurbish overview Explain somewhat better what tracker is, does, and what possible advantages there could be in using it. --- docs/reference/libtracker-sparql/meson.build | 6 +- docs/reference/libtracker-sparql/overview.md | 34 ----------- docs/reference/libtracker-sparql/overview.md.in | 81 +++++++++++++++++++++++++ 3 files changed, 84 insertions(+), 37 deletions(-) delete mode 100644 docs/reference/libtracker-sparql/overview.md create mode 100644 docs/reference/libtracker-sparql/overview.md.in diff --git a/docs/reference/libtracker-sparql/meson.build b/docs/reference/libtracker-sparql/meson.build index 43f2e8880..507555b2c 100644 --- a/docs/reference/libtracker-sparql/meson.build +++ b/docs/reference/libtracker-sparql/meson.build @@ -87,6 +87,7 @@ foreach doc : generated_ontology_files endforeach generated_content_files = [ + 'overview.md.in', 'examples.md.in', 'tutorial.md.in', 'sandboxing.md.in', @@ -108,7 +109,6 @@ foreach doc : generated_content_files ]) endforeach -overview = ['overview.md'] content = [ 'ontologies.md', 'sparql-functions.md', @@ -121,7 +121,7 @@ content = [ # The TOML gi-docgen configuration wants a list of quoted file names. content_quoted = [] -foreach c : overview + generated_content + content + generated_ontology_content +foreach c : generated_content + content + generated_ontology_content content_quoted += '"@0@"'.format(c) endforeach @@ -149,7 +149,7 @@ reference = custom_target( '@INPUT1@', ], depends: [tracker_sparql_gir[0], generated_targets], - depend_files: [overview, content]) + depend_files: [content]) docs_name = 'Tracker-3.0' meson.add_install_script('install-devhelp.sh', docs_name, reference) diff --git a/docs/reference/libtracker-sparql/overview.md b/docs/reference/libtracker-sparql/overview.md deleted file mode 100644 index cf183fe3d..000000000 --- a/docs/reference/libtracker-sparql/overview.md +++ /dev/null @@ -1,34 +0,0 @@ -Title: Overview - -Tracker SPARQL allows creating and connecting to one or more -triplestore databases. It is used by the -[Tracker Miners filesystem indexer](https://gitlab.gnome.org/GNOME/tracker-miners/), -and can also store and publish any kind of app data. - -Querying data is done using the SPARQL graph query language. See the -[examples](examples.html) to find out how this works. -Storing data can also be done using SPARQL, or using the [class@Tracker.Resource] -API. - -You can share a database over D-Bus using the [class@Tracker.Endpoint] API, -allowing other libtracker-sparql users to query from it, either -by referencing it in a `SELECT { SERVICE ... }` query, or by connecting -directly with [ctor@Tracker.SparqlConnection.bus_new]. - -Tracker SPARQL partitions the database into multiple graphs. -You can implementing access control restrictions based on -graphs, and we provide a Flatpak portal that does so. -The number of graphs is [limited](limits.html). - -## Connection methods - -You can create and access a private store using -[ctor@Tracker.SparqlConnection.new]. This is useful to store -app-specific data. - -To connect to another database on the same local machine, such as the -one exposed by Tracker Miner FS, use [ctor@Tracker.SparqlConnection.bus_new]. - -To connect to another a database on a remote machine, use -[ctor@Tracker.SparqlConnection.remote_new]. This can be used to query online -databases that provide a SPARQL endpoint, such as [DBpedia](https://wiki.dbpedia.org/about). diff --git a/docs/reference/libtracker-sparql/overview.md.in b/docs/reference/libtracker-sparql/overview.md.in new file mode 100644 index 000000000..14e75d507 --- /dev/null +++ b/docs/reference/libtracker-sparql/overview.md.in @@ -0,0 +1,81 @@ +Title: Overview + +Tracker is a light-weight RDF [triple store](https://en.wikipedia.org/wiki/Triplestore) +implementation, with a [SPARQL 1.1](https://en.wikipedia.org/wiki/SPARQL) interface. +Tracker is implemented as a library, and may be used to create private databases, +in addition to connecting to remote endpoints for +[federated queries](https://en.wikipedia.org/wiki/Federated_search) or creating such +public endpoints. + +## Advantages + +Tracker offers the following advantages over other traditional databases: + +- It is based on open standards. [SPARQL](https://www.w3.org/TR/2013/REC-sparql11-overview-20130321/) + is a [W3C recommendation](https://www.w3.org/). So is the [RDF](https://www.w3.org/RDF/) data model + and the various file formats available for import/export ([Turtle](https://www.w3.org/TR/turtle/), + [Trig](https://www.w3.org/TR/trig/), [JSON-LD](https://www.w3.org/TR/json-ld11/)). +- Database format and schema updates are automatically managed. The user + just needs to write and update the [ontology](ontologies.html) defining + the structure of the contained data. Databases will be created and + implicitly updated to format changes without the need to write supporting code. +- It has versatile serialization capabilities. Tracker is able to export RDF data into the same + formats it can import and load into databases. It is possible to perform backups, data mirroring, + data synchronization… +- A complete set of CLI tools is included. Tracker databases are fully introspectable + and can be opened with no additional supporting files, the command line tools can do + anything the library could do, and a number of utilities is provided. +- Distributed data is a first class citizen. SPARQL has builtin capabilities to + operate in a distributed environment, which may make it desirable to manage data + that is naturally open to multiple users. Tracker may interoperate with other + SPARQL implementations. + +The Tracker library is written in C, but may be used from a number of languages +through [GObject introspection](https://gi.readthedocs.io/en/latest/), including +Rust, Python, or Javascript (through [GJS](https://gjs.guide/)). + +Tracker is designed to be small, fast, and scalable. It is also robust and +fully [ACID](https://en.wikipedia.org/wiki/ACID). There are ready-made +[examples](examples.html) on how the Tracker library is put to use. + +## Dependencies + +Tracker depends on the following libraries: + +- **GLib**: General-purpose utility library. GLib provides many useful data types, + macros, type conversions, string utilities, file utilities, a main loop abstraction, + and so on. More information available on the + [GLib API documentation](https://developer.gnome.org/glib/stable/). +- **GObject**: A library that provides a type system, a collection of fundamental + types including an object type, and a signal system. More information available + on the [GObject API documentation](https://developer.gnome.org/gobject/stable/). +- **GIO**: A modern, easy-to-use VFS API including abstractions for files, drives, + volumes, stream I/O, as well as network programming and IPC though D-Bus. More + information available on the [GIO API documentation](https://developer.gnome.org/gio/stable/). +- **SQLite**: SQLite is a C-language library that implements a small, fast, + self-contained, high-reliability, full-featured, SQL database engine. SQLite + is the most used database engine in the world. More information available on the + [SQLite website](https://sqlite.org). +- **Soup**: libsoup is an HTTP and HTTP/2 client/server library for GNOME. It uses + GObjects and the GLib main loop to integrate well with GNOME applications. More + information available on the [Soup API documentation](https://libsoup.org/libsoup-3.0/index.html) +- **LibXML2**: Libxml2 is the XML C parser and toolkit developed for the GNOME project. + More information at the [libXML2 website](https://gitlab.gnome.org/GNOME/libxml2/-/wikis/home). +- **JSON-GLib**: JSON-GLib is a library providing serialization and deserialization + support for the JavaScript Object Notation (JSON) format. More information at + the [API documentation](https://gnome.pages.gitlab.gnome.org/json-glib/). + +## Connection methods + +It is possible to create private databases in local storage, or to connect to +remote HTTP or D-Bus SPARQL endpoints. See [class@Tracker.SparqlConnection] +and its different constructors for each of these methods. + +

+{{ images/connections-diagram.svg }} +

+ +It is also possible to create public SPARQL endpoints, see [class@Tracker.Endpoint] +and its subclasses. Tracker can interoperate with any other SPARQL endpoint over HTTP, +such as [Wikidata](https://www.wikidata.org/wiki/Wikidata:Main_Page) or +[DBpedia](https://wiki.dbpedia.org/about). -- cgit v1.2.1 From cc9aa412bb8c3c2836af5944b96b9fa3baf1f7f2 Mon Sep 17 00:00:00 2001 From: Carlos Garnacho Date: Sun, 12 Mar 2023 18:45:28 +0100 Subject: docs: Fixes for dark theme variants Make the background of some images transparent, and add some CSS to ensure nodes, edges and arrows get proper colors on both light and dark themes. --- docs/reference/libtracker-sparql/images/graph-example-diagram.dot | 1 + docs/reference/libtracker-sparql/images/graph-example-diagram.svg | 1 - docs/reference/libtracker-sparql/images/sandbox-diagram.dot | 1 + docs/reference/libtracker-sparql/images/sandbox-diagram.svg | 1 - docs/reference/libtracker-sparql/overview.md.in | 2 ++ docs/reference/libtracker-sparql/sandboxing.md.in | 2 ++ docs/reference/libtracker-sparql/style.xml | 8 ++++++++ docs/reference/libtracker-sparql/tutorial.md.in | 2 ++ docs/tools/tracker-docgen-md.c | 4 ++++ 9 files changed, 20 insertions(+), 2 deletions(-) create mode 100644 docs/reference/libtracker-sparql/style.xml diff --git a/docs/reference/libtracker-sparql/images/graph-example-diagram.dot b/docs/reference/libtracker-sparql/images/graph-example-diagram.dot index 56827d7f3..22b7b646e 100644 --- a/docs/reference/libtracker-sparql/images/graph-example-diagram.dot +++ b/docs/reference/libtracker-sparql/images/graph-example-diagram.dot @@ -1,5 +1,6 @@ digraph { rankdir=LR; + bgcolor=transparent; fontname="sans-serif"; compound=true; node [shape="box", style="rounded", border=0, fontname="sans-serif"]; diff --git a/docs/reference/libtracker-sparql/images/graph-example-diagram.svg b/docs/reference/libtracker-sparql/images/graph-example-diagram.svg index 384bb9c57..18ae08536 100644 --- a/docs/reference/libtracker-sparql/images/graph-example-diagram.svg +++ b/docs/reference/libtracker-sparql/images/graph-example-diagram.svg @@ -7,7 +7,6 @@

\n"); g_fprintf (f, "\n"); g_fprintf (f, "{{ %s-diagram.svg }}\n", id); -- cgit v1.2.1