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
9 changes: 9 additions & 0 deletions .gitattributes
Original file line number Diff line number Diff line change
Expand Up @@ -9,3 +9,12 @@

.gitignore export-ignore
.gitattributes export-ignore

/tests/ export-ignore
/.github/ export-ignore
/phpunit.xml export-ignore
/.phpunit.cache/ export-ignore
/CONTRIBUTING.md export-ignore
/CODE_OF_CONDUCT.md export-ignore
/CHANGELOG.md export-ignore
/SECURITY.md export-ignore
52 changes: 52 additions & 0 deletions .github/ISSUE_TEMPLATE/bug_report.yml
Original file line number Diff line number Diff line change
@@ -0,0 +1,52 @@
name: Bug report
description: Report a reproducible problem in AstraHTTP
labels: ["bug"]
body:
- type: markdown
attributes:
value: |
Thanks for taking the time to file a bug. Please provide a minimal
reproduction so the issue can be investigated quickly.
- type: textarea
id: what-happened
attributes:
label: What happened?
description: Describe the actual behavior and the behavior you expected.
placeholder: "The request to ... returned ... but I expected ..."
validations:
required: true
- type: textarea
id: reproduction
attributes:
label: Minimal reproduction
description: The smallest code snippet that reproduces the problem.
render: php
validations:
required: true
- type: input
id: php-version
attributes:
label: PHP version
placeholder: "8.3.x"
validations:
required: true
- type: input
id: platform
attributes:
label: OS and architecture
placeholder: "Ubuntu 24.04 / x86_64"
validations:
required: true
- type: input
id: package-version
attributes:
label: AstraHTTP version
placeholder: "2.0.0"
validations:
required: true
- type: textarea
id: logs
attributes:
label: Relevant logs / errors
description: Paste any exception messages or worker output.
render: shell
5 changes: 5 additions & 0 deletions .github/ISSUE_TEMPLATE/config.yml
Original file line number Diff line number Diff line change
@@ -0,0 +1,5 @@
blank_issues_enabled: false
contact_links:
- name: Security report
url: https://github.com/astrahttp/http/security/advisories/new
about: Please report security vulnerabilities privately, not as public issues.
23 changes: 23 additions & 0 deletions .github/ISSUE_TEMPLATE/feature_request.yml
Original file line number Diff line number Diff line change
@@ -0,0 +1,23 @@
name: Feature request
description: Suggest an improvement or new capability
labels: ["enhancement"]
body:
- type: textarea
id: problem
attributes:
label: Problem / motivation
description: What are you trying to do, and what is missing or awkward today?
validations:
required: true
- type: textarea
id: proposal
attributes:
label: Proposed solution
description: Describe the API or behavior you would like. Code sketches welcome.
validations:
required: true
- type: textarea
id: alternatives
attributes:
label: Alternatives considered
description: Other approaches you evaluated and why they fall short.
22 changes: 22 additions & 0 deletions .github/PULL_REQUEST_TEMPLATE.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,22 @@
## Summary

<!-- What does this PR change, and why? -->

## Type of change

- [ ] Bug fix (non-breaking)
- [ ] New feature (non-breaking)
- [ ] Breaking change
- [ ] Documentation only

## Checklist

- [ ] `composer lint` passes
- [ ] `composer test` passes
- [ ] Added/updated tests for the changed behavior
- [ ] Public API preserved, or the break is documented in `CHANGELOG.md`
- [ ] No secrets, credentials, or binaries committed

## Notes for reviewers

<!-- Anything that needs special attention, trade-offs, or follow-ups. -->
47 changes: 47 additions & 0 deletions .github/workflows/ci.yml
Original file line number Diff line number Diff line change
@@ -0,0 +1,47 @@
name: CI

on:
push:
branches: ["1.x", "2.x", "main"]
pull_request:
workflow_dispatch:

permissions:
contents: read

jobs:
php:
name: PHP ${{ matrix.php }}
runs-on: ubuntu-latest
strategy:
fail-fast: false
matrix:
php: ['8.2', '8.3', '8.4']
steps:
- uses: actions/checkout@v4
- uses: shivammathur/setup-php@v2
with:
php-version: ${{ matrix.php }}
extensions: mbstring
coverage: none
tools: composer:v2
- run: composer validate --strict
- run: composer install --prefer-dist --no-interaction --no-progress
- run: composer lint
- run: composer test

go:
name: Go transport
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v4
- uses: actions/setup-go@v5
with:
go-version: '1.26.x'
cache-dependency-path: src-go/go.sum
- name: Build
working-directory: src-go
run: go build ./...
- name: Vet
working-directory: src-go
run: go vet ./...
2 changes: 2 additions & 0 deletions .gitignore
Original file line number Diff line number Diff line change
@@ -1,2 +1,4 @@
exec/
vendor/
composer.lock
.phpunit.cache/
43 changes: 43 additions & 0 deletions CHANGELOG.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,43 @@
# Changelog

All notable changes to this project are documented here. The format is based on
[Keep a Changelog](https://keepachangelog.com/en/1.1.0/), and the project aims
to follow [Semantic Versioning](https://semver.org/spec/v2.0.0.html).

> Note: entries for releases before this file was introduced are reconstructed
> from Git tags. Where a tag's exact scope was not recorded in commit history,
> the entry is intentionally conservative rather than inventing detail.

## [Unreleased]

### Added
- `LICENSE` file (MIT) matching the license declared in `composer.json`.
- PHPUnit test suite covering `MultipartEncoder`, `PacketBuffer` and
`RequestOptions` transport normalization.
- `CONTRIBUTING.md`, `SECURITY.md`, `CODE_OF_CONDUCT.md`, issue/PR templates.
- GitHub Actions CI (PHP lint + unit tests on PHP 8.2–8.4, Go build/vet).

### Changed
- `MultipartEncoder::encode()` now validates file readability before reading,
throwing `AstraException` cleanly instead of emitting a raw PHP warning on a
missing or unreadable upload path.

## [2.0.0]
- Tagged release `v2.0.0`. See Git history for the included commits.

## [1.3.1]
- Documentation updates.

## [1.3.0]
- Executable path handling fixes and documentation updates.

## [1.0.0]
- Initial public release: Go-transport-backed async HTTP client for PHP,
shared worker management, streaming responses, multipart encoding,
TLS fingerprint options, and WebSocket / SSE entry points.

[Unreleased]: https://github.com/astrahttp/http/compare/v2.0.0...HEAD
[2.0.0]: https://github.com/astrahttp/http/releases/tag/v2.0.0
[1.3.1]: https://github.com/astrahttp/http/releases/tag/v1.3.1
[1.3.0]: https://github.com/astrahttp/http/releases/tag/v1.3.0
[1.0.0]: https://github.com/astrahttp/http/releases/tag/v1.0.0
35 changes: 35 additions & 0 deletions CODE_OF_CONDUCT.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,35 @@
# Code of Conduct

## Our pledge

We as members, contributors, and maintainers pledge to make participation in
this project a harassment-free experience for everyone, regardless of age, body
size, visible or invisible disability, ethnicity, sex characteristics, gender
identity and expression, level of experience, education, socio-economic status,
nationality, personal appearance, race, religion, or sexual identity and
orientation.

## Our standards

Examples of behavior that contributes to a positive environment:

- Demonstrating empathy and kindness toward other people.
- Being respectful of differing opinions, viewpoints, and experiences.
- Giving and gracefully accepting constructive feedback.
- Focusing on what is best for the community and the project.

Unacceptable behavior includes:

- Harassment, insulting or derogatory comments, and personal or political attacks.
- Public or private harassment.
- Publishing others' private information without explicit permission.
- Other conduct which could reasonably be considered inappropriate.

## Enforcement

Instances of abusive, harassing, or otherwise unacceptable behavior may be
reported to the maintainer at `ajmalalkhaledi@gmail.com`. All complaints will be
reviewed and investigated promptly and fairly.

This Code of Conduct is adapted from the [Contributor Covenant](https://www.contributor-covenant.org),
version 2.1.
62 changes: 62 additions & 0 deletions CONTRIBUTING.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,62 @@
# Contributing to AstraHTTP

Thanks for your interest in improving AstraHTTP. This document explains how to
set up the project, run the checks, and submit changes.

## Project layout

- `src/` — the PHP library (`Astra\Http` namespace, PSR-4).
- `src-go/` — the Go transport worker that PHP talks to over a local socket.
- `bin/astrahttp` — the installer/entry CLI shipped with the package.
- `tests/` — PHPUnit tests. Unit tests under `tests/` do **not** require a
running Go worker; they exercise pure-PHP units (encoding, buffer parsing,
request-option normalization).

## Requirements

- PHP 8.2+ with Composer.
- Go 1.22+ (only if you change the transport in `src-go/`).

## Getting started

```bash
git clone https://github.com/astrahttp/http.git
cd http
composer install
```

## Running the checks

```bash
composer lint # php -l across src/
composer test # PHPUnit unit suite
```

For the Go transport:

```bash
cd src-go
go build ./...
go vet ./...
```

## Pull requests

1. Create a topic branch from the default branch.
2. Keep changes focused; avoid unrelated refactors in the same PR.
3. Add or update tests for behavior you change. New pure-PHP logic should come
with unit tests.
4. Run `composer lint` and `composer test` locally before pushing.
5. Describe the motivation and the user-visible impact in the PR description.
6. Preserve the public API (`Astra\Http\Client`, `RequestOptions`, `Response`)
unless a breaking change is clearly justified and documented in
`CHANGELOG.md`.

## Reporting bugs and requesting features

Use the GitHub issue templates. Include PHP version, OS/architecture, a minimal
reproduction, and the actual vs. expected behavior.

## Security

Do not open public issues for security problems. See [SECURITY.md](SECURITY.md).
21 changes: 21 additions & 0 deletions LICENSE
Original file line number Diff line number Diff line change
@@ -0,0 +1,21 @@
MIT License

Copyright (c) 2026 Ajmal Alkhaledi

Permission is hereby granted, free of charge, to any person obtaining a copy
of this software and associated documentation files (the "Software"), to deal
in the Software without restriction, including without limitation the rights
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
copies of the Software, and to permit persons to whom the Software is
furnished to do so, subject to the following conditions:

The above copyright notice and this permission notice shall be included in all
copies or substantial portions of the Software.

THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
SOFTWARE.
32 changes: 32 additions & 0 deletions SECURITY.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,32 @@
# Security Policy

## Supported versions

Security fixes are provided for the latest released major version. Older
versions may receive fixes at the maintainer's discretion.

| Version | Supported |
| ------- | --------- |
| 2.x | ✅ |
| < 2.0 | ❌ |

## Reporting a vulnerability

Please report security issues **privately**. Do not open a public GitHub issue.

- Preferred: open a private advisory via GitHub Security Advisories
("Report a vulnerability" on the repository Security tab).
- Alternatively, email the maintainer at `ajmalalkhaledi@gmail.com` with:
- a description of the issue and its impact,
- a minimal reproduction or proof of concept,
- affected version(s) and environment.

You can expect an initial acknowledgement within a reasonable time frame. Please
allow time for a fix before any public disclosure.

## Scope notes

AstraHTTP exposes transport-level options such as `insecureSkipVerify` and
custom TLS fingerprints. These are powerful and can weaken connection security
if misused; that is expected behavior, not a vulnerability. Reports about the
library enabling such options by explicit user request are out of scope.
9 changes: 8 additions & 1 deletion composer.json
Original file line number Diff line number Diff line change
@@ -1,6 +1,6 @@
{
"name": "astrahttp/http",
"description": "A high-performance, async-first HTTP client for PHP 8.2+ powered by CycleTLS. Features shared worker management, JA3/JA4 fingerprinting, and full streaming support.",
"description": "Async PHP HTTP client with browser-grade TLS/HTTP fingerprint control (JA3/JA4), backed by a Go transport. Supports HTTP/2, HTTP/3, streaming, WebSockets and SSE.",
"keywords": [
"php",
"security",
Expand Down Expand Up @@ -34,11 +34,18 @@
"src/functions.php"
]
},
"require-dev": {
"phpunit/phpunit": "^11.0"
},
"autoload-dev": {
"psr-4": {
"Astra\\Http\\Tests\\": "tests/"
}
},
"scripts": {
"test": "phpunit",
"lint": "find src -name '*.php' -print0 | xargs -0 -n1 php -l"
},
"bin": [
"bin/astrahttp"
],
Expand Down
Loading
Loading