Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension


Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
19 changes: 19 additions & 0 deletions .github/workflows/ci.yml
Original file line number Diff line number Diff line change
Expand Up @@ -45,3 +45,22 @@ jobs:
- name: Vet
working-directory: src-go
run: go vet ./...

integration:
name: Integration (real worker)
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v4
- uses: shivammathur/setup-php@v2
with:
php-version: '8.3'
extensions: mbstring, sockets
coverage: none
tools: composer:v2
- run: composer install --prefer-dist --no-interaction --no-progress
# Downloads the Go worker on demand and exercises it against a TLS
# fingerprint reflector. Tests skip (not fail) if the worker or the
# reflector is unavailable; a reachable reflector reporting the wrong
# fingerprint fails the job.
- name: Integration tests
run: vendor/bin/phpunit tests/Integration
1 change: 1 addition & 0 deletions .gitignore
Original file line number Diff line number Diff line change
Expand Up @@ -2,3 +2,4 @@ exec/
vendor/
composer.lock
.phpunit.cache/
/src-go/worker
4 changes: 4 additions & 0 deletions README.md
Original file line number Diff line number Diff line change
@@ -1,5 +1,9 @@
# AstraHTTP PHP

[![CI](https://github.com/astrahttp/http/actions/workflows/ci.yml/badge.svg)](https://github.com/astrahttp/http/actions/workflows/ci.yml)
[![Latest Stable Version](https://img.shields.io/packagist/v/astrahttp/http.svg)](https://packagist.org/packages/astrahttp/http)
[![License](https://img.shields.io/packagist/l/astrahttp/http.svg)](LICENSE)

AstraHTTP PHP is a production-oriented wrapper around a Go-based transport engine. It is designed for high-concurrency HTTP traffic with shared worker management, TLS fingerprint customization, streaming response handling, multipart form encoding, retry support, and WebSocket / SSE protocol hooks.

This document explains the package in detail: installation, architecture, API surface, request options, response methods, streaming, retries, WebSocket / SSE usage, multipart uploads, and practical examples.
Expand Down
1 change: 1 addition & 0 deletions phpunit.xml
Original file line number Diff line number Diff line change
Expand Up @@ -9,6 +9,7 @@
<testsuites>
<testsuite name="unit">
<directory>tests</directory>
<exclude>tests/Integration</exclude>
</testsuite>
</testsuites>
<source>
Expand Down
143 changes: 143 additions & 0 deletions tests/Integration/FingerprintTest.php
Original file line number Diff line number Diff line change
@@ -0,0 +1,143 @@
<?php

declare(strict_types=1);

namespace Astra\Http\Tests\Integration;

use Astra\Http\Client;
use Astra\Http\Contract\RequestOptions;
use Astra\Http\WorkerDownloader;
use PHPUnit\Framework\TestCase;

/**
* End-to-end integration tests that exercise the real Go worker.
*
* These require the worker binary (downloaded on demand) and outbound network
* access to a TLS-fingerprint reflector. They are NOT part of the default unit
* suite (phpunit.xml excludes tests/Integration) and run in the dedicated
* "integration" CI job. Any environment problem (worker cannot be installed or
* started, every reflector unreachable) marks the test skipped rather than
* failed, so the job never produces a false red; a reachable reflector that
* reports the wrong fingerprint is a real failure.
*/
final class FingerprintTest extends TestCase
{
/** Reflectors that echo the TLS fingerprint as JSON with a `ja3_hash` field. */
private const REFLECTORS = [
'https://tls.browserleaks.com/json',
'https://tls.peet.ws/api/clean',
];

// Two deliberately different JA3 strings (GREASE disabled for determinism).
private const JA3_A = '771,4865-4866-4867-49195-49199-49196-49200-52393-52392-49171-49172-156-157-47-53,0-23-65281-10-11-35-16-5-13-18-51-45-43-27,29-23-24,0';
private const JA3_B = '771,49195-49199-49196-49200-52393-52392-49171-49172-156-157-47-53-10,0-23-65281-10-11-35-16-5-13-51-45-43,29-23-24-25,0';

private function makeClientOrSkip(): Client
{
try {
WorkerDownloader::ensureInstalled();
return new Client();
} catch (\Throwable $e) {
self::skip('Worker unavailable in this environment: ' . $e->getMessage());
}
}

private static function skip(string $reason): never
{
// Surface the reason in CI logs even without --display-skipped.
fwrite(STDERR, "[integration skipped] {$reason}\n");
self::markTestSkipped($reason);
}

/**
* Fetch the observed ja3_hash for a given JA3 input, trying each reflector
* until one responds with a usable value. Throws if none do.
*/
private function observedJa3Hash(Client $client, string $ja3): string
{
$errors = [];

foreach (self::REFLECTORS as $url) {
try {
$response = $client->get($url, new RequestOptions([
'ja3' => $ja3,
'disableGrease' => true,
'responseType' => 'json',
'timeout' => 30000, // milliseconds
'userAgent' => 'AstraHTTP-IntegrationTest',
]))->await();

if ($response->status !== 200) {
$errors[] = "{$url}: HTTP {$response->status}";
continue;
}

$data = $response->json();
if (is_array($data) && isset($data['ja3_hash']) && is_string($data['ja3_hash']) && $data['ja3_hash'] !== '') {
return $data['ja3_hash'];
}

$errors[] = "{$url}: response missing ja3_hash";
} catch (\Throwable $e) {
$errors[] = "{$url}: " . $e->getMessage();
}
}

throw new \RuntimeException('no reflector usable (' . implode(' | ', $errors) . ')');
}

public function testWorkerPerformsHttpsRequestEndToEnd(): void
{
$client = $this->makeClientOrSkip();

$status = null;
$body = null;
$errors = [];
foreach (self::REFLECTORS as $url) {
try {
$response = $client->get($url, new RequestOptions([
'responseType' => 'json',
'timeout' => 30000, // milliseconds
'userAgent' => 'AstraHTTP-IntegrationTest',
]))->await();
$status = $response->status;
$body = $response->body;
break;
} catch (\Throwable $e) {
$errors[] = "{$url}: " . $e->getMessage();
}
}

if ($status === null) {
$client->close();
self::skip('No reflector reachable: ' . implode(' | ', $errors));
}

$client->close();

// Proves the PHP -> Go worker -> network -> response path works.
self::assertSame(200, $status);
self::assertNotSame('', (string) $body);
}

public function testDistinctJa3InputsProduceDistinctObservedFingerprints(): void
{
$client = $this->makeClientOrSkip();

try {
$hashA = $this->observedJa3Hash($client, self::JA3_A);
$hashB = $this->observedJa3Hash($client, self::JA3_B);
$hashA2 = $this->observedJa3Hash($client, self::JA3_A);
} catch (\Throwable $e) {
$client->close();
self::skip('Reflector unreachable: ' . $e->getMessage());
}

$client->close();

// The worker actually applied our fingerprint: different JA3 in -> different
// fingerprint observed on the wire; the same JA3 in -> the same fingerprint.
self::assertNotSame($hashA, $hashB, 'Different JA3 inputs must yield different observed fingerprints');
self::assertSame($hashA, $hashA2, 'The same JA3 input must yield the same observed fingerprint');
}
}
Loading