The London Perl and Raku Workshop takes place on 26th Oct 2024. If your company depends on Perl, please consider sponsoring and/or attending.
 / 
XDI-0.05
River stage zero No dependents
/ XDI

NAME

XDI - Messaging client for XDI servers

VERSION

Version 0.01

SYNOPSIS

use XDI;

my $xdi = new XDI;

..

my $iname = '=tester';
my $xdi = XDI->new($iname);

..

my $hash = {
	'from' => '=tester',
	'from_graph' => '@xdiserver'
};

my $xdi = XDI->new($hash);

EXPORTS

pick_xdi_tuple

XDI

XDI is an open standard semantic graph model, data sharing format, and protocol.

Details on XDI can be found at https://wiki.oasis-open.org/xdi/FrontPage

XDI graphs are addressed via inames/inumbers which conform to the generic URI syntax as defined in IETF RFC 3986. inames resolve to inumbers. inames can be re-assigned while inumbers are permanent identifiers

inames/inumbers

=markus 			# individual context
=!91F2.8153.F600.AE24

@xdi				# institutional context
@!3D12.8C35.6FB3.E89C

An experimental service to provide XDI iname/inumber resolution is http://xri2xdi.net/index.html

CRUD permissions to an XDI database are defined by link contracts. Link contracts define a permission ($get,$add,$mod,$del) for a graph node and who has that permission

DESCRIPTION

The XDI perl module provides a client for communicating with XDI servers.

Notation and Conventions

$xdi	Root object defining identity of querier
$c	Connection object defining graph target and permissions
$msg	Message object for XDI messages
$hash	Reference to a hash of key/attribute values

Usage Outline

All XDI communications are between two graph entities, these are defined by inames/inumbers Identity verification and authority are still being developed under the XDI specification so this module allows the user to self-assert

use XDI;

$xdi = XDI->new('=tester');

This constructor assumes that the user making the query from is the same as the graph from which the query is being made from_graph. If you were implementing an XDI service that mediated queries on behalf of a user, it would be appropriate to set the from_graph to the identity of the service

$xdi = XDI->new({from => '=tester', from_graph => '@kynetx' });

To specify the graph to which you would like to query, you create a XDI::Connection

$c = $xdi->connect();

This is the primary method for creating a Connection object so that it can access the fields of the XDI object.

You can pass any XDI::Connection initialization parameters to connect()

$hash = {
	target => E<lt>iname|inumberE<gt>,  # eg: =my_personal_cloud
	secret => $secret
};

$c = $xdi->connect($hash);

Given an iname, the default behavior for XDI is to attempt to resolve the iname to it's corresponding inumber using the iname resolution service at xri2xdi.net. This service also returns the URI to the graph that is authoritative for said iname, during testing and development that often proves inconvenient so you can override this behavior

$c->resolve(0);

Of course, if you do that, you will have to specify the URI of the graph to which you are sending a query

$c->server("http://example/=my_personal_cloud");

You may have noticed that we haven't actually connected to anything yet. I reserve the right to make checking the target graph for a valid link contract part of the connection process

secret

    XDI security policy is currently under discussion by the XDI Technical Committee so the placeholder for a more robust policy is to use a shared secret. Please note that the policy allows for arbitrarily complex expressions and Javascript is proposed for the expression syntax. https://wiki.oasis-open.org/xdi/XdiPolicyExpression As the policy matures, I expect to need to update the client

Next step is to create an XDI::Message object

$msg = $c->message();

As usual, you can pass valid message constructor parameters to XDI::Connection::message

$hash = {
	link_contract => '=!1111'
};

The link_contract is the address of the node to which you have permissions. Note that you not only have to have permission to that node, but you have to have permission to execute your operation ($get,$mod,$add,$del,$all)

The process of a external party negotiating a link contract is still under development so an XDI server has the option of not enforcing link contracts. In such case, leave the link_contract parameter undefined and that statement will not be included as part of the message. More information on link contracts can be found at XDI::Message

Compose the message that you intend to send to the target graph

$msg->get('=!1111+tel');

An XDI message can only contain one type of operation, so it is an error to try to mix operations in a message, but it is possible to send multiple statements of the same operation

$msg->get('=!1111+tel');
$msg->get('=!1111+email');
$msg->get('=!1111+birthdate');

Each one of these operations composes an XDI statement. There is no order of execution for statements in a message. This has little consequence for $get operations, but needs to be taken into consideration for $add and $mod operations

Once the message is composed, use the XDI::Connection object to post the message to the target graph post performs an http post request to the server with the XDI message in the body.

$graph = $c->post($msg);

The result is a JSON encoded representation of the nodes requested in the $get operation. Other operations will return an empty hash {} upon success. Default behavior is to automatically convert the JSON to a perl hash object

SUBROUTINES/METHODS

XDI and it's members support the common PERL OO-style syntax via AUTOLOAD

Constructor

$xdi = XDI->new($iname);

$xdi = XDI->new({
	'from' => '=tester,
	'from_graph' => '@server'
});

$xdi = XDI->new($ref);

Constructs a new XDI object. Optional arguments consist of either a single iname|inumber string or a list of field => value pairs. The single argument will default values of from and from_graph to the same value.

$xdi->from()

$xdi->from($val)

Get/set from value. from is the identity of the entity making the XDI request

$xdi->from_graph()

$xdi->from_graph($val)

Get/set from_graph value. from_graph is the identity of the graph that is making the XDI request. In the case of a PERL client, the distinction between from and from_graph may be negligible, but could be significant when issues of authorized access via signed messages are implemented

connect

$c = $xdi->connect()

$c = $xdi->connect($hash)

This method returns a XDI::Connection object. Any parameters passed to the method will be used to invoke the XDI::Connection constructor.

pick_xdi_tuple

$tuple = pick_xdi_tuple($graph,[I<$subject>,I<$predicate>,I<$object>])

$graph is a perl hash object as returned by $c-post($msg)>

$subject,$predicate,$object are optional matching arguments (strings) used to match the returned tuple Any one or two of the parameters may be undef. Only the first matching tuple is returned

pick_xdi_tuple returns an array reference [$subject,$predicate,$object]

tuples

$tuples = tuples($graph,[I<$subject> | I<regex>,I<$predicate> | I<regex>,I<$object> | I<regex>])

tuples returns an array of array references. Any of the match elements can be substituted with a regular expression.

Usually the third element of the tuple is an array. If there is only 1 element to the array, the element is substituted for the array of 1 element

get_literal

get_literal($graph,I<$key>)
get_literal($graph,I<@key>)

get_literal is a convenience function to pull literals (subject/!/literal) from the graph. A single key or an array of keys is a valid parameter

If an array of keys @key is used, all of the values are placed into a single array that is returned

get_equivalent

get_equivalent($graph,$key)

get_equivalent is a convenience function to pull equivalance expressions (subject/$is/equivalent) from the graph.

get_property

get_property($graph,$key)

get_property is a convenience function to pull properties of subject (subject/()/property) from the graph.

get_context

get_context($graph,$key)

get_context is a convenience function to pull the contexts of definitions (+(+def)/$is()/[...]]) from the graph.

AUTHOR

Mark Horstmeier <solargroovey@gmail.com>

COPYRIGHT AND LICENSE

Copyright (C) 2007-2012 Kynetx, Inc.

The perl XDI client is free software; you can redistribute it and/or modify it under the terms of the GNU General Public License as published by the Free Software Foundation; either version 2 of the License, or (at your option) any later version.

This program is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License for more details.

You should have received a copy of the GNU General Public License along with this program; if not, write to the Free Software Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307 USA