Hacktoberfest 2026: the issues maintainers tagged for October, open and beginner-friendly. Browse Hacktoberfest issues

Announcement: Opt-in default socket timeout for the AWS SDK for PHP (2026)

Open
  • Is something wrong?
#3,369 0 comments 0 reactions 0 assignees View on GitHub

Maintainers usually reply within 2 days

Nobody has claimed this yet.

Assessment

Difficulty
4/5
Estimated time
3-5 days
Newbie friendliness
12/100
Issue type
Feature
Clarity
Mostly clear
Activity status
Active
Tech stack
aws, php
Domain
networking

Research direction

This is a maintainer announcement of an opt-in preview, not a defined task, so there is no change to make yet. The payload names the AWS_ENABLE_DEFAULT_SOCKET_TIMEOUT_2026 environment variable, the ext-curl handler, the http.curl client options, and the CURLOPT_LOW_SPEED_LIMIT and CURLOPT_LOW_SPEED_TIME settings. Done would mean a reported behavior question is answered or a concrete gap in the preview is identified, which needs familiarity with the SDK's HTTP layer.

Written by the indexing model from the issue text.

Description

announcement

The AWS SDK for PHP is making a default socket (inactivity) timeout available as an opt-in preview. This change applies only to the cURL HTTP handler (ext-curl). It is built on libcurl's low-speed options, which have no equivalent on the SDK's stream-wrapper transport, so an environment without ext-curl is unaffected. If you do not enable the preview, existing applications behave as they do today. We intend to make this behavior the default in the future.

Status
Applies to The cURL HTTP handler only (ext-curl). The stream-wrapper transport is unaffected.
Opt-in available in 3.400.0 and later
Opt-in flag Environment variable AWS_ENABLE_DEFAULT_SOCKET_TIMEOUT_2026=true

Why

A connection can be established successfully and then stop delivering data. Without a socket timeout, such a request waits until the OS gives up, unless the application configured its own timeout. This preview adds a per-service default that closes that gap on the cURL handler.

The default is a rolling inactivity window, not a deadline on the complete operation. It is implemented with libcurl's low-speed options: a fixed floor of 1 byte/second (CURLOPT_LOW_SPEED_LIMIT) combined with a per-service time (CURLOPT_LOW_SPEED_TIME). Any byte transferred in either direction keeps the transfer alive, so a slow response that continues making progress is not interrupted; the window trips only on genuine silence. A single window covers both read and write, since libcurl watches both directions.

The timeout is selected by service:

Service category Default timeout
Most services 5 minutes
Services with long-hold operations 15 minutes
Services with streaming or long-lived connections (exempt) No default

The exempt category covers APIs that legitimately hold a connection open without transferring data, including streaming request/response bodies and bidirectional streams. Exempt services receive no socket timeout even with the preview enabled. Applications can override any of these defaults per client.

Will this affect me?

Not unless you opt in. During the preview, leaving the opt-in setting disabled preserves the SDK's current behavior. The change is limited to the cURL handler, and any cURL options you set yourself take precedence over the service default. If you already set the cURL low-speed options on a client, the SDK leaves them untouched.

When the window elapses with no read or write progress, cURL aborts the transfer and the in-flight request fails with a cURL error, which is retried per the client's configured retry policy.

Opt in

Set the following environment variable before running your application:

export AWS_ENABLE_DEFAULT_SOCKET_TIMEOUT_2026=true

The gate is matched exactly against the string true. Any other value, including 1, TRUE, an empty string, or unset, counts as off.

To stop using the preview, set the flag to anything other than true, or remove it, then restart the application:

export AWS_ENABLE_DEFAULT_SOCKET_TIMEOUT_2026=false
# or remove it entirely:
unset AWS_ENABLE_DEFAULT_SOCKET_TIMEOUT_2026

No code change is required. With the preview enabled, every service client built on the cURL handler receives its service-specific default automatically. The example uses S3Client, but the same applies to every service client:

<?php
// Opt in via AWS_ENABLE_DEFAULT_SOCKET_TIMEOUT_2026=true
use Aws\S3\S3Client;

$s3 = new S3Client([
    'region'  => 'us-east-1',
    'version' => 'latest',
]);

Override or opt out for a specific client

The preview flag turns the service default on globally, but you can override it or opt out for an individual client, whether or not the preview is enabled. The SDK applies its default only when you have not set either cURL low-speed option yourself; set either one and you own the pair, and the SDK attaches nothing.

Use a different timeout. Set the cURL low-speed options explicitly through the client's http.curl options. They always take precedence over the service default. Keep CURLOPT_LOW_SPEED_LIMIT at 1 to express a pure read/write inactivity window, and set CURLOPT_LOW_SPEED_TIME to your chosen number of seconds:

<?php
use Aws\S3\S3Client;

$s3 = new S3Client([
    'region'  => 'us-east-1',
    'version' => 'latest',
    'http'    => [
        'curl' => [
            CURLOPT_LOW_SPEED_LIMIT => 1,
            CURLOPT_LOW_SPEED_TIME  => 30, // seconds of inactivity
        ],
    ],
]);

Opt a client out entirely. Setting either low-speed option disables the SDK default for that client. To opt out without imposing any inactivity window, set the time to 0 (cURL treats 0 as no low-speed abort):

<?php
use Aws\S3\S3Client;

$s3 = new S3Client([
    'region'  => 'us-east-1',
    'version' => 'latest',
    'http'    => [
        'curl' => [
            CURLOPT_LOW_SPEED_LIMIT => 1,
            CURLOPT_LOW_SPEED_TIME  => 0, // no inactivity timeout
        ],
    ],
]);

Feedback

If you encounter unexpected behavior or have questions, comment on this issue. Please include the SDK version, service client, operation, whether ext-curl is in use, and whether you set any cURL options or timeout explicitly. Your feedback during the opt-in period will help determine when and how we make this the default.

Dominant language
PHP
Stars
6.2k
Forks
1.3k
Avg merge
2d 7h
Merged PRs (30d)
11

Getting set up

First steps

  1. Read the whole issue, then the project's contributing guide.
  2. Comment on the issue to say you are picking it up — it saves two people doing the same work.
  3. Fork the repository and make your change on a branch.
  4. Open a pull request that references the issue number.

More from aws/aws-sdk-php

All issues in aws/aws-sdk-php

Similar issues

More PHP issues

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.