File Coverage

blib/lib/PAGI/Response.pm

Criterion	Covered	Total	%
statement	261	264	98.8
branch	101	112	90.1
condition	44	51	86.2
subroutine	46	46	100.0
pod	27	27	100.0
total	479	500	95.8

package PAGI::Response;

use strict;
use warnings;

use Future::AsyncAwait;
use Carp qw(croak);
use Encode qw(encode FB_CROAK);
use JSON::MaybeXS ();


=head1 NAME

PAGI::Response - Fluent response builder for PAGI applications

=head1 SYNOPSIS

    use PAGI::Response;
    use Future::AsyncAwait;

    # Basic usage in a raw PAGI app
    async sub app ($scope, $receive, $send) {
        my $res = PAGI::Response->new($scope, $send);

        # Fluent chaining - set status, headers, then send
        await $res->status(200)
                  ->header('X-Custom' => 'value')
                  ->json({ message => 'Hello' });
    }

    # Various response types
    await $res->text("Hello World");
    await $res->html("Hello");
    await $res->json({ data => 'value' });
    await $res->redirect('/login');

    # Streaming large responses
    await $res->stream(async sub ($writer) {
        await $writer->write("chunk1");
        await $writer->write("chunk2");
        await $writer->close();
    });

    # File downloads
    await $res->send_file('/path/to/file.pdf', filename => 'doc.pdf');

=head1 DESCRIPTION

PAGI::Response provides a fluent interface for building HTTP responses in
raw PAGI applications. It wraps the low-level C<$send> callback and provides
convenient methods for common response types.

B (C, C, C, C)
return C<$self> for fluent chaining.

B (C, C, C, C, etc.) return
Futures and actually send the response. Once a finisher is called, the
response is sent and cannot be modified.

B Each PAGI::Response instance can only send one response.
Attempting to call a finisher method twice will throw an error.

=head1 CONSTRUCTOR

=head2 new

    my $res = PAGI::Response->new($scope, $send);

Creates a new response builder.

=over 4

=item C<$send> - Required. The PAGI send callback (coderef).

=item C<$scope> - Required. The PAGI scope hashref.

=back

The scope is required because PAGI::Response stores the "response sent" flag
in C<< $scope->{'pagi.response.sent'} >>. This ensures that if multiple
Response objects are created from the same scope (e.g., in middleware chains),
they all share the same "sent" state and prevent double-sending responses.

B Per-object state like C and C is NOT shared between
Response objects. Only the "sent" flag is shared via scope. This matches the
ASGI pattern where middleware wraps the C<$send> callable to intercept/modify
responses, and Response objects build their own status/headers before sending.

=head1 CHAINABLE METHODS

These methods return C<$self> for fluent chaining.

=head2 status

    $res->status(404);
    my $code = $res->status;

Set or get the HTTP status code (100-599). Returns C<$self> when setting
for fluent chaining. When getting, returns 200 if no status has been set.

    my $res = PAGI::Response->new($scope, $send);
    $res->status;           # 200 (default, nothing set yet)
    $res->has_status;       # false
    $res->status(201);      # set explicitly
    $res->has_status;       # true

=head2 status_try

    $res->status_try(404);

Set the HTTP status code only if one hasn't been set yet. Useful in
middleware or error handlers to provide fallback status codes without
overriding choices made by the application:

    $res->status_try(202);  # sets to 202 (nothing was set)
    $res->status_try(500);  # no-op, 202 already set

=head2 header

    $res->header('X-Custom' => 'value');
    my $value = $res->header('X-Custom');

Add a response header. Can be called multiple times to add multiple headers.
If called with only a name, returns the last value for that header or C.

=head2 headers

    my $headers = $res->headers;

Returns the full header arrayref C<[ name, value ]> in order.

=head2 header_all

    my @values = $res->header_all('Set-Cookie');

Returns all values for the given header name (case-insensitive).

=head2 header_try

    $res->header_try('X-Custom' => 'value');

Add a response header only if that header name has not already been set.

=head2 content_type

    $res->content_type('text/html; charset=utf-8');
    my $type = $res->content_type;

Set the Content-Type header, replacing any existing one.

=head2 content_type_try

    $res->content_type_try('text/html; charset=utf-8');

Set the Content-Type header only if it has not already been set.

=head2 cookie

    $res->cookie('session' => 'abc123',
        max_age  => 3600,
        path     => '/',
        domain   => 'example.com',
        secure   => 1,
        httponly => 1,
        samesite => 'Strict',
    );

Set a response cookie. Options: max_age, expires, path, domain, secure,
httponly, samesite.

=head2 delete_cookie

    $res->delete_cookie('session');

Delete a cookie by setting it with Max-Age=0.

=head2 scope

    my $scope = $res->scope;

Returns the raw PAGI scope hashref. Useful for constructing helper
objects like L and L:

    my $stash = PAGI::Stash->new($res);

=head2 Per-Request Shared State

See L for per-request shared state. Construct from a
Response object or from the shared scope:

    use PAGI::Stash;
    my $stash = PAGI::Stash->new($res);

=head2 is_sent

    if ($res->is_sent) {
        warn "Response already sent, cannot send error";
        return;
    }

Returns true if the response has already been finalized (sent to the client).
Useful in error handlers or middleware that need to check whether they can
still send a response.

=head2 has_status

    if ($res->has_status) { ... }

Returns true if a status code has been explicitly set via C or
C.

=head2 has_header

    if ($res->has_header('content-type')) { ... }

Returns true if the given header name has been set via C or
C. Header names are case-insensitive.

=head2 has_content_type

    if ($res->has_content_type) { ... }

Returns true if Content-Type has been explicitly set via C,
C, or C/C with a Content-Type name.

=head2 cors

    # Allow all origins (simplest case)
    $res->cors->json({ data => 'value' });

    # Allow specific origin
    $res->cors(origin => 'https://example.com')->json($data);

    # Full configuration
    $res->cors(
        origin      => 'https://example.com',
        methods     => [qw(GET POST PUT DELETE)],
        headers     => [qw(Content-Type Authorization)],
        expose      => [qw(X-Request-Id X-RateLimit-Remaining)],
        credentials => 1,
        max_age     => 86400,
        preflight   => 0,
    )->json($data);

Add CORS (Cross-Origin Resource Sharing) headers to the response.
Returns C<$self> for chaining.

B

=over 4

=item * C - Allowed origin. Default: C<'*'> (all origins).
Can be a specific origin like C<'https://example.com'> or C<'*'> for any.

=item * C - Arrayref of allowed HTTP methods for preflight.
Default: C<[qw(GET POST PUT DELETE PATCH OPTIONS)]>.

=item * C - Arrayref of allowed request headers for preflight.
Default: C<[qw(Content-Type Authorization X-Requested-With)]>.

=item * C - Arrayref of response headers to expose to the client.
By default, only simple headers (Cache-Control, Content-Language, etc.)
are accessible. Use this to expose custom headers.

=item * C - Boolean. If true, sets
C, allowing cookies and
Authorization headers. Default: C<0>.

=item * C - How long (in seconds) browsers should cache preflight
results. Default: C<86400> (24 hours).

=item * C - Boolean. If true, includes preflight response headers
(Allow-Methods, Allow-Headers, Max-Age). Set this when handling OPTIONS
requests. Default: C<0>.

=item * C - The Origin header value from the request.
Required when C is true and C is C<'*'>, because
the CORS spec forbids using C<'*'> with credentials. Pass the actual
request origin to echo it back.

=back

B

=over 4

=item * When C is true, you cannot use C<< origin => '*' >>.
Either specify an exact origin, or pass C with the
client's actual Origin header.

=item * The C header is always set to ensure proper caching
when origin-specific responses are used.

=item * For preflight (OPTIONS) requests, set C<< preflight => 1 >> and
typically respond with C<< $res->status(204)->empty() >>.

=back

=head1 FINISHER METHODS

These methods return Futures and send the response.

=head2 text

    await $res->text("Hello World");

Send a plain text response with Content-Type: text/plain; charset=utf-8.

=head2 html

    await $res->html("Hello");

Send an HTML response with Content-Type: text/html; charset=utf-8.

=head2 json

    await $res->json({ message => 'Hello' });

Send a JSON response with Content-Type: application/json; charset=utf-8.

=head2 redirect

    await $res->redirect('/login');
    await $res->redirect('/new-url', 301);

Send a redirect response with an empty body. Default status is 302.

B This method sends the response but does NOT stop Perl execution.
Use C after redirect if you have more code below:

    await $res->redirect('/login');
    return;  # Important! Code below would still run otherwise

B While RFC 7231 suggests including a short HTML body with a
hyperlink for clients that don't auto-follow redirects, all modern browsers
and HTTP clients ignore redirect bodies. If you need a body for legacy
compatibility, use the lower-level C<$send-E()> calls directly.

=head2 empty

    await $res->empty();

Send an empty response with status 204 No Content (or custom status if set).

=head2 send

    await $res->send($text);
    await $res->send($text, charset => 'iso-8859-1');

Send text, encoding it to UTF-8 (or specified charset). Adds charset to
Content-Type if not present. This is the high-level method for sending
text responses.

=head2 send_raw

    await $res->send_raw($bytes);

Send raw bytes as the response body without any encoding. Use this for
binary data or when you've already encoded the content yourself.

=head2 stream

    await $res->stream(async sub ($writer) {
        await $writer->write("chunk1");
        await $writer->write("chunk2");
        await $writer->close();
    });

Stream response chunks via callback. The callback receives a writer object
with C, C, and C methods.

=head2 writer

    my $writer = await $res->writer;
    my $writer = await $res->writer(on_close => sub { cleanup() });
    my $writer = await $res->writer(on_close => async sub { await cleanup() });

Returns a L directly, sending headers immediately.
Unlike C, the writer is not scoped to a callback — you own it
and must call C when done.

This is useful when the writer needs to be passed to event handlers,
pub/sub callbacks, timers, or other contexts outside a single function:

    async sub live_feed {
        my ($self, $ctx) = @_;
        my $writer = await $ctx->response
            ->content_type('text/plain')
            ->writer(on_close => sub { $bus->unsubscribe($id) });

        my $id = $bus->subscribe(async sub ($line) {
            await $writer->write("$line\n");
        });

        await $ctx->receive;    # wait for disconnect
        await $writer->close;
    }

The optional C callback is registered before headers are sent,
eliminating any race window with fast client disconnects. Sync and async
callbacks are both supported — see L under L.

=head2 send_file

    await $res->send_file('/path/to/file.pdf');
    await $res->send_file('/path/to/file.pdf',
        filename => 'download.pdf',
        inline   => 1,
    );

    # Partial file (for range requests)
    await $res->send_file('/path/to/video.mp4',
        offset => 1024,       # Start from byte 1024
        length => 65536,      # Send 64KB
    );

Send a file as the response. This method uses the PAGI protocol's C
key for efficient server-side streaming. The file is B read into memory.
For production, use L to delegate file serving
to your reverse proxy.

B

=over 4

=item * C - Set Content-Disposition attachment filename

=item * C - Use Content-Disposition: inline instead of attachment

=item * C - Start position in bytes (default: 0). For range requests.

=item * C - Number of bytes to send. Defaults to file size minus offset.

=back

B

    # Manual range request handling
    async sub handle_video ($req, $send) {
        my $res = PAGI::Response->new($scope, $send);
        my $path = '/videos/movie.mp4';
        my $size = -s $path;

        my $range = $req->header('Range');
        if ($range && $range =~ /bytes=(\d+)-(\d*)/) {
            my $start = $1;
            my $end = $2 || ($size - 1);
            my $length = $end - $start + 1;

            return await $res->status(206)
                ->header('Content-Range' => "bytes $start-$end/$size")
                ->header('Accept-Ranges' => 'bytes')
                ->send_file($path, offset => $start, length => $length);
        }

        return await $res->header('Accept-Ranges' => 'bytes')
                         ->send_file($path);
    }

B For production file serving with full features (ETag caching,
automatic range request handling, conditional GETs, directory indexes),
use L instead:

    use PAGI::App::File;
    my $files = PAGI::App::File->new(root => '/var/www/static');
    my $app = $files->to_app;

=head1 EXAMPLES

=head2 Complete Raw PAGI Application

    use Future::AsyncAwait;
    use PAGI::Request;
    use PAGI::Response;

    my $app = async sub ($scope, $receive, $send) {
        return await handle_lifespan($scope, $receive, $send)
            if $scope->{type} eq 'lifespan';

        my $req = PAGI::Request->new($scope, $receive);
        my $res = PAGI::Response->new($scope, $send);

        if ($req->method eq 'GET' && $req->path eq '/') {
            return await $res->html('Welcome');
        }

        if ($req->method eq 'POST' && $req->path eq '/api/users') {
            my $data = await $req->json;
            # ... create user ...
            return await $res->status(201)
                             ->header('Location' => '/api/users/123')
                             ->json({ id => 123, name => $data->{name} });
        }

        return await $res->status(404)->json({ error => 'Not Found' });
    };

=head2 Form Validation with Error Response

    async sub handle_contact ($req, $send) {
        my $res = PAGI::Response->new($scope, $send);
        my $form = await $req->form_params;

        my @errors;
        my $email = $form->get('email') // '';
        my $message = $form->get('message') // '';

        push @errors, 'Email required' unless $email;
        push @errors, 'Invalid email' unless $email =~ /@/;
        push @errors, 'Message required' unless $message;

        if (@errors) {
            return await $res->status(422)
                             ->json({ error => 'Validation failed', errors => \@errors });
        }

        # Process valid form...
        return await $res->json({ success => 1 });
    }

=head2 Authentication with Cookies

    async sub handle_login ($req, $send) {
        my $res = PAGI::Response->new($scope, $send);
        my $data = await $req->json;

        my $user = authenticate($data->{email}, $data->{password});

        unless ($user) {
            return await $res->status(401)->json({ error => 'Invalid credentials' });
        }

        my $session_id = create_session($user);

        return await $res->cookie('session' => $session_id,
                path     => '/',
                httponly => 1,
                secure   => 1,
                samesite => 'Strict',
                max_age  => 86400,  # 24 hours
            )
            ->json({ user => { id => $user->{id}, name => $user->{name} } });
    }

    async sub handle_logout ($req, $send) {
        my $res = PAGI::Response->new($scope, $send);

        return await $res->delete_cookie('session', path => '/')
                         ->json({ logged_out => 1 });
    }

=head2 File Download

    async sub handle_download ($req, $send) {
        my $res = PAGI::Response->new($scope, $send);
        my $file_id = $req->path_param('id');

        my $file = get_file($file_id); # Be sure to clean $file
        unless ($file && -f $file->{path}) {
            return await $res->status(404)->json({ error => 'File not found' });
        }

        return await $res->send_file($file->{path},
            filename => $file->{original_name},
        );
    }

=head2 Streaming Large Data

    async sub handle_export ($req, $send) {
        my $res = PAGI::Response->new($scope, $send);

        await $res->content_type('text/csv')
                  ->header('Content-Disposition' => 'attachment; filename="export.csv"')
                  ->stream(async sub ($writer) {
                      # Write CSV header
                      await $writer->write("id,name,email\n");

                      # Stream rows from database
                      my $cursor = get_all_users_cursor();
                      while (my $user = $cursor->next) {
                          await $writer->write("$user->{id},$user->{name},$user->{email}\n");
                      }
                  });
    }

=head2 Server-Sent Events Style Streaming

    async sub handle_events ($req, $send) {
        my $res = PAGI::Response->new($scope, $send);

        await $res->content_type('text/event-stream')
                  ->header('Cache-Control' => 'no-cache')
                  ->stream(async sub ($writer) {
                      for my $i (1..10) {
                          await $writer->write("data: Event $i\n\n");
                          await some_delay(1);  # Wait 1 second
                      }
                  });
    }

=head2 Conditional Responses

    async sub handle_resource ($req, $send) {
        my $res = PAGI::Response->new($scope, $send);
        my $etag = '"abc123"';

        # Check If-None-Match for caching
        my $if_none_match = $req->header('If-None-Match') // '';
        if ($if_none_match eq $etag) {
            return await $res->status(304)->empty();
        }

        return await $res->header('ETag' => $etag)
                         ->header('Cache-Control' => 'max-age=3600')
                         ->json({ data => 'expensive computation result' });
    }

=head2 CORS API Endpoint

    # Simple CORS - allow all origins
    async sub handle_api ($scope, $receive, $send) {
        my $res = PAGI::Response->new($scope, $send);

        return await $res->cors->json({ status => 'ok' });
    }

    # CORS with credentials (e.g., cookies, auth headers)
    async sub handle_api_with_auth ($scope, $receive, $send) {
        my $req = PAGI::Request->new($scope, $receive);
        my $res = PAGI::Response->new($scope, $send);

        # Get the Origin header from request
        my $origin = $req->header('Origin');

        return await $res->cors(
            origin         => 'https://myapp.com',  # Or use request_origin
            credentials    => 1,
            expose         => [qw(X-Request-Id)],
        )->json({ user => 'authenticated' });
    }

=head2 CORS Preflight Handler

    # Handle OPTIONS preflight requests
    async sub app ($scope, $receive, $send) {
        my $req = PAGI::Request->new($scope, $receive);
        my $res = PAGI::Response->new($scope, $send);

        # Handle preflight
        if ($req->method eq 'OPTIONS') {
            return await $res->cors(
                origin      => 'https://myapp.com',
                methods     => [qw(GET POST PUT DELETE)],
                headers     => [qw(Content-Type Authorization X-Custom-Header)],
                credentials => 1,
                max_age     => 86400,
                preflight   => 1,  # Include preflight headers
            )->status(204)->empty();
        }

        # Handle actual request
        return await $res->cors(
            origin      => 'https://myapp.com',
            credentials => 1,
        )->json({ data => 'response' });
    }

=head2 Dynamic CORS Origin

    # Allow multiple origins dynamically
    my %ALLOWED_ORIGINS = map { $_ => 1 } qw(
        https://app1.example.com
        https://app2.example.com
        https://localhost:3000
    );

    async sub handle_api ($scope, $receive, $send) {
        my $req = PAGI::Request->new($scope, $receive);
        my $res = PAGI::Response->new($scope, $send);

        my $request_origin = $req->header('Origin') // '';

        # Check if origin is allowed
        if ($ALLOWED_ORIGINS{$request_origin}) {
            return await $res->cors(
                origin      => $request_origin,  # Echo back the allowed origin
                credentials => 1,
            )->json({ data => 'allowed' });
        }

        # Origin not allowed - respond without CORS headers
        return await $res->status(403)->json({ error => 'Origin not allowed' });
    }

=head1 WRITER OBJECT

The C method passes a writer object to its callback, and
C returns one directly. The writer has the following methods:

=head3 write

    await $writer->write($chunk);

Write a chunk of data to the response stream. Returns a L.

Writing after close returns a failed L rather than throwing.
This allows cleanup code that races with close to handle the error
gracefully via C.

=head3 close

    await $writer->close;

Close the stream. Returns a L. Calling close multiple times is
safe — subsequent calls are no-ops.

=head3 bytes_written

    my $n = $writer->bytes_written;

Returns the total number of bytes written so far.

=head3 on_close

    # Sync callback
    $writer->on_close(sub { cleanup() });

    # Async callback — return value is awaited automatically
    $writer->on_close(async sub {
        await notify_stream_ended();
    });

    # Chaining
    $writer->on_close(sub { ... })
           ->on_close(sub { ... });

Registers a callback to fire when the writer closes (either explicitly
or via C auto-close). Callbacks can be regular subs or async
subs — async results are automatically awaited. Multiple callbacks run
in registration order. Exceptions are caught and warned but do not
prevent other callbacks from running. Returns C<$self> for chaining.

B If your callback captures the writer
object in a closure, use C to avoid a memory leak:

    use Scalar::Util qw(weaken);
    my $weak_writer = $writer;
    weaken($weak_writer);
    $writer->on_close(sub { $weak_writer->... if $weak_writer });

The callback array is cleared after firing, so any cycle via a closure
is broken when the writer closes, but C prevents the object
from being kept alive until that point.

=head3 is_closed

    if ($writer->is_closed) { ... }

Returns true if the writer has been closed.

The writer automatically closes when the C callback completes,
but calling C explicitly is recommended for clarity.

=head1 ERROR HANDLING

All finisher methods return Futures. Errors in encoding (e.g., invalid UTF-8
when C mode would be enabled) will cause the Future to fail.

    use Syntax::Keyword::Try;

    try {
        await $res->json($data);
    }
    catch ($e) {
        warn "Failed to send response: $e";
    }

=head1 SEE ALSO

L, L, L

=head1 AUTHOR

PAGI Contributors

=cut

sub new {
    my ($class, $scope, $send) = @_;
    croak("scope is required") unless $scope && ref($scope) eq 'HASH';
    croak("send is required") unless $send;
    croak("send must be a coderef") unless ref($send) eq 'CODE';

    my $self = bless {
        send              => $send,
        scope             => $scope,
        # _status not set here - uses exists() check and lazy default of 200
        _headers            => [],
        _header_set         => {},
    }, $class;

    return $self;
}

sub status {
    my ($self, $code) = @_;
    return $self->{_status} // 200 if @_ == 1;  # lazy default
    croak("Status must be a number between 100-599")
        unless $code =~ /^\d+$/ && $code >= 100 && $code <= 599;
    $self->{_status} = $code;
    return $self;
}

sub status_try {
    my ($self, $code) = @_;
    return $self if exists $self->{_status};
    return $self->status($code);
}

sub header {
    my ($self, $name, $value) = @_;
    croak("Header name is required") unless defined $name;
    if (@_ == 2) {
        my $key = lc($name);
        for (my $i = $#{$self->{_headers}}; $i >= 0; $i--) {
            my $pair = $self->{_headers}[$i];
            return $pair->[1] if lc($pair->[0]) eq $key;
        }
        return undef;
    }
    push @{$self->{_headers}}, [$name, $value];
    my $key = lc($name // '');
    $self->{_header_set}{$key} = 1 if length $key;
    if ($key eq 'content-type') {
        $self->{_content_type} = $value;
    }
    return $self;
}

sub headers {
    my ($self) = @_;
    return $self->{_headers};
}

sub header_all {
    my ($self, $name) = @_;
    croak("Header name is required") unless defined $name;
    my $key = lc($name);
    my @values;
    for my $pair (@{$self->{_headers}}) {
        push @values, $pair->[1] if lc($pair->[0]) eq $key;
    }
    return @values;
}

sub header_try {
    my ($self, $name, $value) = @_;
    return $self if $self->has_header($name);
    return $self->header($name, $value);
}

sub content_type {
    my ($self, $type) = @_;
    return $self->{_content_type} if @_ == 1;
    # Remove existing content-type headers
    $self->{_headers} = [grep { lc($_->[0]) ne 'content-type' } @{$self->{_headers}}];
    push @{$self->{_headers}}, ['content-type', $type];
    $self->{_header_set}{'content-type'} = 1;
    $self->{_content_type} = $type;
    return $self;
}

sub content_type_try {
    my ($self, $type) = @_;
    return $self if exists $self->{_content_type};
    return $self->content_type($type);
}

sub has_status {
    my ($self) = @_;
    return exists $self->{_status} ? 1 : 0;
}

sub has_header {
    my ($self, $name) = @_;
    my $key = lc($name // '');
    return 0 unless length $key;
    return $self->{_header_set}{$key} ? 1 : 0;
}

sub has_content_type {
    my ($self) = @_;
    return exists $self->{_content_type} ? 1 : 0;
}

sub scope { shift->{scope} }


sub is_sent {
    my ($self) = @_;
    return $self->{scope}{'pagi.response.sent'} ? 1 : 0;
}

sub _mark_sent {
    my ($self) = @_;
    croak("Response already sent") if $self->{scope}{'pagi.response.sent'};
    $self->{scope}{'pagi.response.sent'} = 1;
}

async sub send_raw {
    my ($self, $body) = @_;
    $self->_mark_sent;

    # Send start
    await $self->{send}->({
        type    => 'http.response.start',
        status  => $self->status,  # uses lazy default of 200
        headers => $self->{_headers},
    });

    # Send body
    await $self->{send}->({
        type => 'http.response.body',
        body => $body,
        more => 0,
    });
}

async sub send {
    my ($self, $body, %opts) = @_;
    my $charset = $opts{charset} // 'utf-8';

    # Ensure content-type has charset
    my $has_ct = 0;
    for my $h (@{$self->{_headers}}) {
        if (lc($h->[0]) eq 'content-type') {
            $has_ct = 1;
            unless ($h->[1] =~ /charset=/i) {
                $h->[1] .= "; charset=$charset";
            }
            last;
        }
    }
    unless ($has_ct) {
        push @{$self->{_headers}}, ['content-type', "text/plain; charset=$charset"];
    }

    # Encode body
    my $encoded = encode($charset, $body // '', FB_CROAK);

    await $self->send_raw($encoded);
}

async sub text {
    my ($self, $body) = @_;
    $self->content_type('text/plain; charset=utf-8');
    await $self->send($body);
}

async sub html {
    my ($self, $body) = @_;
    $self->content_type('text/html; charset=utf-8');
    await $self->send($body);
}

async sub json {
    my ($self, $data) = @_;
    $self->content_type('application/json; charset=utf-8');
    my $body = JSON::MaybeXS->new(utf8 => 1, canonical => 1)->encode($data);
    await $self->send_raw($body);
}

async sub redirect {
    my ($self, $url, $status) = @_;
    $status //= 302;
    $self->{_status} = $status;
    $self->header('location', $url);
    await $self->send_raw('');
}

async sub empty {
    my ($self) = @_;
    # Use 204 if status hasn't been explicitly set
    unless (exists $self->{_status}) {
        $self->{_status} = 204;
    }
    await $self->send_raw(undef);
}

sub cookie {
    my ($self, $name, $value, %opts) = @_;
    my @parts = ("$name=$value");

    push @parts, "Max-Age=$opts{max_age}" if defined $opts{max_age};
    push @parts, "Expires=$opts{expires}" if defined $opts{expires};
    push @parts, "Path=$opts{path}" if defined $opts{path};
    push @parts, "Domain=$opts{domain}" if defined $opts{domain};
    push @parts, "Secure" if $opts{secure};
    push @parts, "HttpOnly" if $opts{httponly};
    push @parts, "SameSite=$opts{samesite}" if defined $opts{samesite};

    my $cookie_str = join('; ', @parts);
    push @{$self->{_headers}}, ['set-cookie', $cookie_str];

    return $self;
}

sub delete_cookie {
    my ($self, $name, %opts) = @_;
    return $self->cookie($name, '',
        max_age => 0,
        path    => $opts{path},
        domain  => $opts{domain},
    );
}

sub cors {
    my ($self, %opts) = @_;
    my $origin      = $opts{origin} // '*';
    my $credentials = $opts{credentials} // 0;
    my $methods     = $opts{methods} // [qw(GET POST PUT DELETE PATCH OPTIONS)];
    my $headers     = $opts{headers} // [qw(Content-Type Authorization X-Requested-With)];
    my $expose      = $opts{expose} // [];
    my $max_age     = $opts{max_age} // 86400;
    my $preflight   = $opts{preflight} // 0;

    # Determine the origin to send back
    my $allow_origin;
    if ($origin eq '*' && $credentials) {
        # With credentials, can't use wildcard - use request_origin if provided
        $allow_origin = $opts{request_origin} // '*';
    } else {
        $allow_origin = $origin;
    }

    # Core CORS headers (always set)
    $self->header('Access-Control-Allow-Origin', $allow_origin);
    $self->header('Vary', 'Origin');

    if ($credentials) {
        $self->header('Access-Control-Allow-Credentials', 'true');
    }

    if (@$expose) {
        $self->header('Access-Control-Expose-Headers', join(', ', @$expose));
    }

    # Preflight headers (for OPTIONS responses or when explicitly requested)
    if ($preflight) {
        $self->header('Access-Control-Allow-Methods', join(', ', @$methods));
        $self->header('Access-Control-Allow-Headers', join(', ', @$headers));
        $self->header('Access-Control-Max-Age', $max_age);
    }

    return $self;
}

async sub stream {
    my ($self, $callback) = @_;
    $self->_mark_sent;

    # Send start
    await $self->{send}->({
        type    => 'http.response.start',
        status  => $self->status,  # uses lazy default of 200
        headers => $self->{_headers},
    });

    # Create writer and call callback
    my $writer = PAGI::Response::Writer->new($self->{send});
    await $callback->($writer);

    # Ensure closed
    await $writer->close() unless $writer->is_closed;
}

async sub writer {
    my ($self, %opts) = @_;
    $self->_mark_sent;

    # Send headers
    await $self->{send}->({
        type    => 'http.response.start',
        status  => $self->status,
        headers => $self->{_headers},
    });

    return PAGI::Response::Writer->new($self->{send}, %opts);
}

# Simple MIME type mapping
my %MIME_TYPES = (
    '.html' => 'text/html',
    '.htm'  => 'text/html',
    '.txt'  => 'text/plain',
    '.css'  => 'text/css',
    '.js'   => 'application/javascript',
    '.json' => 'application/json',
    '.xml'  => 'application/xml',
    '.pdf'  => 'application/pdf',
    '.zip'  => 'application/zip',
    '.png'  => 'image/png',
    '.jpg'  => 'image/jpeg',
    '.jpeg' => 'image/jpeg',
    '.gif'  => 'image/gif',
    '.svg'  => 'image/svg+xml',
    '.ico'  => 'image/x-icon',
    '.woff' => 'font/woff',
    '.woff2'=> 'font/woff2',
);

sub _mime_type {
    my ($path) = @_;
    my ($ext) = $path =~ /(\.[^.]+)$/;
    return $MIME_TYPES{lc($ext // '')} // 'application/octet-stream';
}

async sub send_file {
    my ($self, $path, %opts) = @_;
    croak("File not found: $path") unless -f $path;
    croak("Cannot read file: $path") unless -r $path;

    # Get file size
    my $file_size = -s $path;

    # Handle offset and length for range requests
    my $offset = $opts{offset} // 0;
    my $length = $opts{length};

    # Validate offset
    croak("offset must be non-negative") if $offset < 0;
    croak("offset exceeds file size") if $offset > $file_size;

    # Calculate actual length to send
    my $max_length = $file_size - $offset;
    if (defined $length) {
        croak("length must be non-negative") if $length < 0;
        $length = $max_length if $length > $max_length;
    } else {
        $length = $max_length;
    }

    # Set content-type if not already set
    my $has_ct = grep { lc($_->[0]) eq 'content-type' } @{$self->{_headers}};
    unless ($has_ct) {
        $self->content_type(_mime_type($path));
    }

    # Set content-length based on actual bytes to send
    $self->header('content-length', $length);

    # Set content-disposition
    my $disposition;
    if ($opts{inline}) {
        $disposition = 'inline';
    } elsif ($opts{filename}) {
        # Sanitize filename for header
        my $safe_filename = $opts{filename};
        $safe_filename =~ s/["\r\n]//g;
        $disposition = "attachment; filename=\"$safe_filename\"";
    }
    $self->header('content-disposition', $disposition) if $disposition;

    $self->_mark_sent;

    # Send response start
    await $self->{send}->({
        type    => 'http.response.start',
        status  => $self->status,  # uses lazy default of 200
        headers => $self->{_headers},
    });

    # Use PAGI file protocol for efficient server-side streaming
    my $body_event = {
        type => 'http.response.body',
        file => $path,
    };

    # Add offset/length only if not reading from start or not full file
    $body_event->{offset} = $offset if $offset > 0;
    $body_event->{length} = $length if $length < $max_length;

    await $self->{send}->($body_event);
}

# Writer class for streaming responses
package PAGI::Response::Writer {
    use strict;
    use warnings;
    use Future::AsyncAwait;
    use Carp qw(croak);
    use Scalar::Util qw(blessed);

    sub new {
        my ($class, $send, %opts) = @_;
        my $self = bless {
            send          => $send,
            bytes_written => 0,
            closed        => 0,
            _on_close     => [],
        }, $class;
        push @{$self->{_on_close}}, $opts{on_close} if $opts{on_close};
        return $self;
    }

    async sub write {
        my ($self, $chunk) = @_;
        die 'Writer already closed' if $self->{closed};
        $self->{bytes_written} += length($chunk // '');
        await $self->{send}->({
            type => 'http.response.body',
            body => $chunk,
            more => 1,
        });
    }

    async sub close {
        my ($self) = @_;
        return if $self->{closed};
        $self->{closed} = 1;
        await $self->{send}->({
            type => 'http.response.body',
            body => '',
            more => 0,
        });
        for my $cb (@{$self->{_on_close}}) {
            eval {
                my $r = $cb->();
                if (blessed($r) && $r->isa('Future')) {
                    await $r;
                }
            };
            if ($@) {
                warn "PAGI::Response::Writer on_close callback error: $@";
            }
        }

        # Clear callback array to break any closure-based cycles
        $self->{_on_close} = [];
    }

    sub on_close {
        my ($self, $cb) = @_;
        push @{$self->{_on_close}}, $cb;
        return $self;
    }

    sub is_closed { $_[0]->{closed} }

    sub bytes_written { $_[0]->{bytes_written} }
}

1;