From 67ef8eb26ee047c6a44d0bd95fee318de2637a8a Mon Sep 17 00:00:00 2001 From: Matteo Castellucci Date: Sun, 28 Jan 2024 19:58:33 +0100 Subject: [PATCH] docs: fix README.md with changes from last update --- README.md | 223 ++++++++++++++++++++++++++++++++++++++++-------------- 1 file changed, 167 insertions(+), 56 deletions(-) diff --git a/README.md b/README.md index 9022eabd..8d36c9e8 100644 --- a/README.md +++ b/README.md @@ -2,80 +2,99 @@ [![codecov](https://codecov.io/gh/Interactions-HSG/yggdrasil/graph/badge.svg?token=DhAW8ZB5zr)](https://codecov.io/gh/Interactions-HSG/yggdrasil) -A platform for [Hypermedia Multi-Agent Systems (MAS)](https://hyperagents.org/) [1] built with -[Vert.x](https://vertx.io/). The current implementation provides two core functionalities: +A platform for [Hypermedia Multi-Agent Systems (MAS)](https://hyperagents.org/) [1] built with [Vert.x](https://vertx.io/). +The current implementation provides two core functionalities: -* it allows to program and deploy hypermedia environments for autonomous agents that conform to the - _Agents & Artifacts_ meta-model [2] -* it partially implements the [W3C WebSub recommendation](https://www.w3.org/TR/2018/REC-websub-20180123/) - and can act as a WebSub hub +* it allows programming and deploying hypermedia environments for autonomous agents that conform to the _Agents & Artifacts_ metamodel [2] +* it partially implements the [W3C WebSub recommendation](https://www.w3.org/TR/2018/REC-websub-20180123/) and can act as a WebSub hub #### References [1] Andrei Ciortea, Olivier Boissier, Alessandro Ricci. 2019. Engineering World-Wide Multi-Agent Systems with Hypermedia. In: Weyns D., Mascardi V., Ricci A. (eds) Engineering Multi-Agent Systems. EMAS 2018. -Lecture Notes in Computer Science, vol 11375. Springer, Cham. https://doi.org/10.1007/978-3-030-25693-7_15 +Lecture Notes in Computer Science, vol 11375. Springer, Cham. [https://doi.org/10.1007/978-3-030-25693-7_15](https://doi.org/10.1007/978-3-030-25693-7_15) [2] Alessandro Ricci, Michele Piunti, and Mirko Viroli. 2011. Environment Programming in multi-agent -systems: an artifact-based perspective. Autonomous Agents and Multi-Agent Systems, 23(2):158-192. - +systems: an artifact-based perspective. Autonomous Agents and Multi-Agent Systems, 23(2):158–192. ## Prerequisites * JDK 21+ +* Gradle 8.4+ ## Building the project -To build the project, just use: +To build the project use: ```shell ./gradlew ``` -The default Gradle task `shadowJar` generates a fat-jar in the `build/libs` directory. - +The default Gradle task `shadowJar` generates a "fat" JAR file in the `build/libs` directory. ## Running Yggdrasil -To start an Yggdrasil node: +To start a Yggdrasil node: ```shell java -jar build/libs/yggdrasil-0.0.0-SNAPSHOT-all.jar -conf conf/localhost_memory_config.json ``` -The configuration file is optional. Open your browser to -[http://localhost:8080](http://localhost:8080). You should see an `Yggdrasil v0.0.0` message. - -## Running Yggdrasil as a Docker container - -Build the image with the current context and creates the image `yggdrasil`: +The configuration file is optional. +Open your browser to [http://localhost:8080](http://localhost:8080). +You should see a description of the platform like the following: -```shell -docker-compose build ``` +@prefix hmas: . +@prefix td: . +@prefix htv: . +@prefix hctl: . +@prefix wotsec: . +@prefix dct: . +@prefix js: . +@prefix saref: . + + a hmas:HypermediaMASPlatform, td:Thing; + td:hasSecurityConfiguration [ a wotsec:NoSecurityScheme + ]; + td:hasActionAffordance [ a td:ActionAffordance; + td:name "createWorkspace"; + td:hasForm [ + hctl:forContentType "application/json"; + hctl:hasOperationType td:invokeAction; + hctl:hasTarget ; + htv:methodName "POST" + ] + ]; + td:title "yggdrasil". +``` + +## Running Yggdrasil as a Docker container -Run with docker-compose (by default, it exposes the port `8899` of the host machine): +Run and build the Yggdrasil image in the project directory context +(by default, the service is exposed on port `8899` of the host machine): ```shell -docker-compose up +docker compose up ``` ## HTTP API Overview -The HTTP API implements CRUD operations for 2 types of resources: +The HTTP API implements CRUD operations for three types of resources: -* workspaces (URI template: `/workspaces/`) -* artifacts (URI template: `/artifacts/`) +* workspaces and sub-workspaces (URI template: `/workspaces/`) +* artifacts (URI template: `/workspaces//artifacts/`) +* body artifacts (URI template: `/workspaces//agents/`) -`POST` and `PUT` requests use [Turtle](http://www.w3.org/TR/2014/REC-turtle-20140225/) payloads -and the current implementation only validates the payload's syntax. +### Caveats -`POST` requests can use the `Slug` header (see [RFC 5023](https://tools.ietf.org/html/rfc5023#section-9.7)) -to hint at a preferred IRI for a resource to be created. If the IRI is not already in use, it will -be minted to the created resource. +The `POST` requests for creating a workspace (URI `/workspaces/`), +a sub-workspace (URI `/workspaces/`) or an artifact (URI `/workspaces//artifact/`) +can receive [Turtle](http://www.w3.org/TR/2014/REC-turtle-20140225/) payloads other than their default payloads, +and the current implementation only validates the payload's syntax. -When creating a resource via `POST`, the resource to be created is identified in the Turtle payload -via a null relative IRI: +When creating a resource via `POST`, +the resource to be created can be identified in the Turtle payload via a null relative IRI: ```shell curl -i -X POST \ @@ -85,37 +104,129 @@ curl -i -X POST \ -d '<> a .' ``` -When retrieving the representation of a resource from Yggdrasil, the HTTP response contains 2 `Link` -header fields that advertise a WebSub hub that clients can subscribe to in order to receive -notifications whenever the resource is updated (see the -[W3C WebSub recommendation](https://www.w3.org/TR/2018/REC-websub-20180123/)). -Sample request: +The `POST` requests for creating a workspace (URI `/workspaces/`) or a sub-workspace (URI `/workspaces/`) +can use the `Slug` header (see [RFC 5023](https://tools.ietf.org/html/rfc5023#section-9.7)) +to hint at a preferred IRI for a resource to be created. +If the IRI is not already in use, it will be minted to the created resource, +otherwise, a new random URI will be generated. + +All `PUT` requests (for updating a workspace, URI `/workspaces/`, +for updating an artifact, URI `/workspaces//artifacts/`, +and for updating an agent body, URI `/workspaces//agents/`), +can receive [Turtle](http://www.w3.org/TR/2014/REC-turtle-20140225/) payloads other than their default payloads, +and the current implementation only validates the payload's syntax. + +For more information, see the [documentation website](interactions-hsg.github.io/yggdrasil/). + +### WebSub + +When retrieving the representation of a resource from Yggdrasil, +the HTTP response contains 2 `Link` header fields +that advertise a WebSub hub that clients can subscribe to receive notifications whenever the resource is updated +(see the [W3C WebSub recommendation](https://www.w3.org/TR/2018/REC-websub-20180123/)). +A sample request follows: ```shell -GET /workspaces/wksp1 HTTP/1.1 +GET /workspaces/test HTTP/1.1 Host: yggdrasil.andreiciortea.ro HTTP/1.1 200 OK Content-Type: text/turtle -Link: ; rel="hub" -Link: ; rel="self" - - - a ; - "wksp1" ; - - , - . +Link: ; rel="hub" +Link: ; rel="self" + +@prefix hmas: . +@prefix td: . +@prefix htv: . +@prefix hctl: . +@prefix wotsec: . +@prefix dct: . +@prefix js: . +@prefix saref: . + + a td:Thing, hmas:Workspace; + td:hasActionAffordance [ a td:ActionAffordance; + td:name "joinWorkspace"; + td:hasForm [ + htv:methodName "POST"; + hctl:hasTarget ; + hctl:forContentType "application/json"; + hctl:hasOperationType td:invokeAction + ] + ], [ a td:ActionAffordance; + td:hasForm [ + htv:methodName "POST"; + hctl:hasTarget ; + hctl:forContentType "application/json"; + hctl:hasOperationType td:invokeAction + ]; + td:hasInputSchema [ a js:ObjectSchema; + js:properties [ a js:StringSchema; + js:propertyName "artifactName" + ], [ a js:ArraySchema; + js:propertyName "initParams" + ], [ a js:StringSchema; + js:propertyName "artifactClass"; + js:enum , + ]; + js:required "artifactName", "artifactClass" + ]; + td:name "makeArtifact" + ], [ a td:ActionAffordance; + td:name "focus"; + td:hasForm [ + htv:methodName "POST"; + hctl:hasTarget ; + hctl:forContentType "application/json"; + hctl:hasOperationType td:invokeAction + ]; + td:hasInputSchema [ a js:ObjectSchema; + js:properties [ a js:StringSchema; + js:propertyName "artifactName" + ], [ a js:StringSchema; + js:propertyName "callbackIri" + ]; + js:required "artifactName", "callbackIri" + ] + ], [ a td:ActionAffordance; + td:name "quitWorkspace"; + td:hasForm [ + htv:methodName "POST"; + hctl:hasTarget ; + hctl:forContentType "application/json"; + hctl:hasOperationType td:invokeAction + ] + ], [ a td:ActionAffordance; + td:name "createSubWorkspace"; + td:hasForm [ + htv:methodName "POST"; + hctl:forContentType "application/json"; + hctl:hasOperationType td:invokeAction; + hctl:hasTarget + ] + ] ; + td:title "test"; + td:hasSecurityConfiguration [ a wotsec:NoSecurityScheme + ]; + hmas:isHostedOn ; + hmas:contains ; + hmas:contains . + + a hmas:HypermediaMASPlatform . + a hmas:Workspace . + a hmas:Artifact . ``` -Using the discovered hub and topic IRIs, a client can subscribe for notification via a `POST` request -that contains a JSON payload with the following fields (see the -[W3C WebSub recommendation](https://www.w3.org/TR/2018/REC-websub-20180123/)): +Using the discovered hub and topic IRIs, +a client can subscribe for notification via a `POST` request that contains a JSON payload with the following fields +(see the [W3C WebSub recommendation](https://www.w3.org/TR/2018/REC-websub-20180123/)) to the "hub" URL: - * `hub.mode` - * `hub.topic` - * `hub.callback` + * `hub.mode` (could be either "subscribe" or "unsubscribe") + * `hub.topic` (the URI of the resource to subscribe to or unsubscribe from) + * `hub.callback` (the URI to be notified by the Yggdrasil platform upon updates) -When a resource is updated, Yggdrasil issues `POST` requests with the (updated) resource -representation to all registered callbacks. +When a resource is created, +updated or deleted, +Yggdrasil issues a `POST` request with the resource representation to all registered callbacks. +For more information, see the [documentation website](interactions-hsg.github.io/yggdrasil/).