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:

1. Direct descriptor URL
2. Web link relation (Link header or HTML link relation)
3. /.well-known/eosc-federation/node
4. 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