README

Reference implementation of an EOSC node capabilities discovery library for PHP 8.2+.

What This Library Does

Given a URL that appears to represent an EOSC node, this package discovers and normalizes machine-readable node capabilities.

It answers one narrow question:

Given a URL that appears to represent an EOSC node, what machine-readable capabilities does that node advertise?

What This Library Does Not Do

v1 is discovery-only.

No catalogue harvesting
No service catalogue record validation
No authentication to private APIs
No endpoint uptime monitoring
No node registry crawling, unless an explicit public GET discovery endpoint is provided as input

Installation

composer require aria-php/eosc-node-discovery

Simple PHP Usage

<?php

declare(strict_types=1);

use EOSC\Node\Discovery\NodeDiscovery;

$discovery = NodeDiscovery::createDefault();
$node = $discovery->discover('https://node.example.org');

foreach ($node->getCapabilities() as $capability) {
    echo $capability->getType()->value . ' => ' . $capability->getEndpoint() . PHP_EOL;
}

Dependency-Injected Usage

<?php

declare(strict_types=1);

use EOSC\Node\Discovery\Discovery\DirectDescriptorDiscoveryStrategy;
use EOSC\Node\Discovery\Discovery\LegacyWellKnownNodeDiscoveryStrategy;
use EOSC\Node\Discovery\Discovery\LinkRelationDiscoveryStrategy;
use EOSC\Node\Discovery\Discovery\WellKnownFederationNodeDiscoveryStrategy;
use EOSC\Node\Discovery\NodeDiscovery;
use EOSC\Node\Discovery\Normalizer\FederationNodeDescriptorNormalizer;
use EOSC\Node\Discovery\Normalizer\LegacyEoscNodeDescriptorNormalizer;
use GuzzleHttp\Client;
use GuzzleHttp\Psr7\HttpFactory;

$discovery = new NodeDiscovery(
    httpClient: new Client(['http_errors' => false]),
    requestFactory: new HttpFactory(),
    strategies: [
        new DirectDescriptorDiscoveryStrategy(),
        new LinkRelationDiscoveryStrategy(),
        new WellKnownFederationNodeDiscoveryStrategy(),
        new LegacyWellKnownNodeDiscoveryStrategy(),
    ],
    normalizers: [
        new FederationNodeDescriptorNormalizer(),
        new LegacyEoscNodeDescriptorNormalizer(),
    ],
);

CLI Usage

Installed binary:

vendor/bin/eosc-node-discover

Examples:

vendor/bin/eosc-node-discover https://node.example.org
vendor/bin/eosc-node-discover https://node.example.org --format=json
vendor/bin/eosc-node-discover https://node.example.org --format=json --pretty
vendor/bin/eosc-node-discover https://node.example.org --show-warnings
vendor/bin/eosc-node-discover https://node.example.org --trace

Discovery Methods

Strategies run in priority order and stop at first success:

Direct descriptor URL
Web link relation (Link header or HTML link relation)
/.well-known/eosc-federation/node
Legacy /.well-known/eosc-node

Preferred relation:

https://w3id.org/eosc/federation/node

Also accepted:

eosc-federation-node

Supported Descriptor Formats

Federation node descriptor (/.well-known/eosc-federation/node)
Legacy EOSC node descriptor (/.well-known/eosc-node)

Normalized Capability Types

resource_catalogue
data_object_catalogue
monitoring
helpdesk
aai
front_office

Unknown capability types are rejected with warnings.

Normalized Capability Formats

eosc_service_catalogue_api
eosc_service_catalogue_v6_api
een_json
dcat_json_ld
aria_json
csv
website
oidc
rest
unknown

Unknown or ambiguous formats are normalized conservatively and can produce warnings.

Warning and Failure Behavior

Tolerant behavior (warning collection):

Unknown capability type rejected
Unknown capability format
Missing optional node metadata
Missing optional capability version
Relative endpoint resolved against descriptor URL
Ambiguous format inferred from URL/type hints
Legacy format used

Hard failures:

No discovery method succeeds
Descriptor URL returns non-success HTTP status
Descriptor body is not parseable JSON
Descriptor has no usable capabilities
Endpoint URL is malformed and cannot be resolved

Development

Run tests:

composer test

Run static analysis:

composer analyse

Run coding standard checks:

composer cs

Apply coding style fixes:

composer cs:fix

aria-php / eosc-node-discovery

Maintainers

Package info

Statistics

Security