tourze/relay-service-contracts

Relay service contracts providing interfaces for frontend servers, landing providers, and landing servers

0.0.1 2025-06-03 04:07 UTC

Requires

• php: ^8.1
• symfony/security-core: ^6.4
• tourze/gb-t-2659: 0.0.*
• tourze/server-node-bundle: 0.0.*

Requires (Dev)

• phpstan/phpstan: ^2.1
• phpunit/phpunit: ^10.0

MIT

README

English | 中文

A collection of interfaces for relay service implementations, providing contracts for frontend servers, landing providers, and landing servers.

Features

• Standardized Contracts: Well-defined interfaces for relay service architecture
• Frontend Server Management: Interface for handling client connections and server binding
• Landing Provider System: Contract for managing landing servers and connection parameters
• Landing Server Abstraction: Interface for actual relay connection handling
• Geographic Location Support: Integration with country codes and server nodes
• User Authentication: Integration with Symfony Security UserInterface
• Type Safety: Full PHP 8.1+ type declarations and PHPStan level 5 compliance

Installation

composer require tourze/relay-service-contracts

Quick Start

<?php

use Tourze\RelayServiceContracts\FrontendServerInterface;
use Tourze\RelayServiceContracts\LandingProviderInterface;
use Tourze\RelayServiceContracts\LandingServerInterface;

// Implement a frontend server
class MyFrontendServer implements FrontendServerInterface
{
    public function getId(): ?string
    {
        return 'frontend-1';
    }

    public function getAccessHost(): string
    {
        return 'relay.example.com';
    }

    public function getBindPort(): int
    {
        return 8080;
    }
}

// Implement a landing server
class MyLandingServer implements LandingServerInterface
{
    public function getServerType(): string
    {
        return 'http';
    }

    public function getConnectHost(): string
    {
        return '10.0.0.1';
    }

    public function getConnectPort(): int
    {
        return 3128;
    }

    public function getConnectParams(): ?array
    {
        return ['timeout' => 30];
    }

    public function getLocation(): ?Alpha2Code
    {
        return Alpha2Code::US;
    }

    public function getURI(): string
    {
        return 'http://10.0.0.1:3128';
    }

    public function getNode(): ?Node
    {
        return null;
    }
}

Interfaces

FrontendServerInterface

Represents a frontend server that handles client connections:

interface FrontendServerInterface
{
    public function getId(): ?string;
    public function getAccessHost(): string;
    public function getBindPort(): int;
}

LandingProviderInterface

Manages landing servers and connection parameters:

interface LandingProviderInterface
{
    public function getLandingServers(): iterable;
    public function getLandingServerFromURI(string $uri): ?LandingServerInterface;
    public function getConnectParams(
        FrontendServerInterface $frontendServer,
        LandingServerInterface $landingServer,
        ?UserInterface $user = null
    ): ?array;
}

LandingServerInterface

Represents a landing server that handles relay connections:

interface LandingServerInterface
{
    public function getServerType(): string;
    public function getConnectHost(): string;
    public function getConnectPort(): int;
    public function getConnectParams(): ?array;
    public function getLocation(): ?Alpha2Code;
    public function getURI(): string;
    public function getNode(): ?Node;
}

Usage

Implement these interfaces in your relay service implementation:

use Tourze\RelayServiceContracts\FrontendServerInterface;
use Tourze\RelayServiceContracts\LandingProviderInterface;
use Tourze\RelayServiceContracts\LandingServerInterface;

class MyFrontendServer implements FrontendServerInterface
{
    public function getId(): ?string
    {
        return 'frontend-1';
    }

    public function getAccessHost(): string
    {
        return 'relay.example.com';
    }

    public function getBindPort(): int
    {
        return 8080;
    }
}

class MyLandingServer implements LandingServerInterface
{
    // Implement all required methods...
}

class MyLandingProvider implements LandingProviderInterface
{
    // Implement all required methods...
}

Requirements

• PHP 8.1+
• Symfony Security Core 6.4+

Dependencies

• tourze/gb-t-2659: For country code handling
• tourze/server-node-bundle: For server node entities

Testing

Run the test suite:

vendor/bin/phpunit

Contributing

Please see CONTRIBUTING.md for details.

License

The MIT License (MIT). Please see License File for more information.