// Copyright (c) 2019-2026 Alexander Medvednikov. All rights reserved.
// Use of this source code is governed by an MIT license
// that can be found in the LICENSE file.
module s3

import net.http
import time

// Client is the entry point for S3 operations. It carries default credentials
// and tuneable HTTP behaviour; per-call overrides go through the option params
// of each method. Instantiate once, reuse for many objects.
@[heap]
pub struct Client {
pub:
	credentials Credentials
	// part_size is the multipart-upload chunk size in bytes (default 5 MiB,
	// the S3 minimum).
	part_size i64 = 5 * 1024 * 1024
	// queue_size is the intended parallel-upload concurrency for multipart
	// (currently sequential; reserved).
	queue_size int = 5
	// retry is the number of retry attempts for failed uploads.
	retry int = 3
	// read_timeout / write_timeout map onto V's net.http settings.
	// Defaults are generous because parts can be 5 MiB+ on slow links.
	read_timeout  i64 = 5 * 60 * time.second
	write_timeout i64 = 5 * 60 * time.second
}

// new_client builds a Client. Pass an empty Credentials to fall back to env vars.
pub fn new_client(creds Credentials) Client {
	resolved := if creds.access_key_id == '' && creds.secret_access_key == '' {
		Credentials.from_env().merge(creds)
	} else {
		creds
	}
	return Client{
		credentials: resolved
	}
}

// PutOptions configures a put / write call.
@[params]
pub struct PutOptions {
pub:
	bucket              string
	content_type        string
	content_disposition string
	content_encoding    string
	cache_control       string
	acl                 Acl
	storage_class       StorageClass
	request_payer       bool
	// hash_payload, when true, computes SHA-256 of the body before signing
	// instead of using `UNSIGNED-PAYLOAD`. Slightly stronger integrity guarantee
	// at the cost of one full body scan.
	hash_payload bool
}

// GetOptions configures a get / read call.
@[params]
pub struct GetOptions {
pub:
	bucket        string
	range         string // e.g. 'bytes=0-1023' for partial downloads
	version_id    string
	request_payer bool
}

// StatOptions configures stat / size / exists checks.
@[params]
pub struct StatOptions {
pub:
	bucket        string
	request_payer bool
}

// put uploads `data` to `key`. Use `upload_file` / `upload_bytes_multipart`
// for streaming or for files larger than ~100 MiB; `put` keeps everything in
// memory.
pub fn (c &Client) put(key string, data []u8, opts PutOptions) ! {
	creds := c.creds_for(opts.bucket)
	host := canonical_host(creds, opts.bucket)
	if host == '' {
		return new_error('InvalidEndpoint', 'cannot determine S3 host (set endpoint or bucket)')
	}
	path := build_object_path(creds, opts.bucket, key)!
	payload_hash := if opts.hash_payload { sha256_hex(data) } else { unsigned_payload }
	signed := sign_request(creds, SignRequest{
		method:        'PUT'
		path:          path
		payload_hash:  payload_hash
		extra_headers: put_object_headers(opts)
	})!
	resp := c.do_http(signed, data.bytestr())!
	if resp.status_code !in [200, 204] {
		return new_http_error(resp.status_code, key, resp.body)
	}
}

// put_object_headers maps `PutOptions` to the wire headers used by both the
// single-shot `put` and the multipart `initiate_multipart` paths. Keeping the
// mapping in one place ensures the two upload modes accept the exact same set
// of options without drift.
fn put_object_headers(opts PutOptions) map[string]string {
	mut headers := map[string]string{}
	if opts.content_type != '' {
		headers['content-type'] = opts.content_type
	}
	if opts.content_disposition != '' {
		headers['content-disposition'] = opts.content_disposition
	}
	if opts.content_encoding != '' {
		headers['content-encoding'] = opts.content_encoding
	}
	if opts.cache_control != '' {
		headers['cache-control'] = opts.cache_control
	}
	if opts.acl != .unset {
		headers['x-amz-acl'] = opts.acl.to_header_value()
	}
	if opts.storage_class != .unset {
		headers['x-amz-storage-class'] = opts.storage_class.to_header_value()
	}
	if opts.request_payer {
		headers['x-amz-request-payer'] = 'requester'
	}
	return headers
}

// get downloads the entire object body into memory. For large files set a
// `range` and assemble the result yourself, or use a presigned URL with an
// HTTP streaming client.
pub fn (c &Client) get(key string, opts GetOptions) ![]u8 {
	creds := c.creds_for(opts.bucket)
	path := build_object_path(creds, opts.bucket, key)!
	mut headers := map[string]string{}
	if opts.range != '' {
		headers['range'] = opts.range
	}
	if opts.request_payer {
		headers['x-amz-request-payer'] = 'requester'
	}
	mut query := ''
	if opts.version_id != '' {
		query = 'versionId=' + uri_encode_query(opts.version_id)
	}
	signed := sign_request(creds, SignRequest{
		method:        'GET'
		path:          path
		query:         query
		payload_hash:  empty_sha256
		extra_headers: headers
	})!
	resp := c.do_http(signed, '')!
	if resp.status_code !in [200, 206] {
		return new_http_error(resp.status_code, key, resp.body)
	}
	return resp.body.bytes()
}

// get_string is a convenience wrapper around `get` that returns the body as a
// V `string`.
pub fn (c &Client) get_string(key string, opts GetOptions) !string {
	bytes := c.get(key, opts)!
	return bytes.bytestr()
}

// stat returns the object metadata (size / last_modified / etag / content_type).
// Returns an `S3Error` with code `NoSuchKey` when the object doesn't exist.
pub fn (c &Client) stat(key string, opts StatOptions) !Stat {
	creds := c.creds_for(opts.bucket)
	path := build_object_path(creds, opts.bucket, key)!
	mut headers := map[string]string{}
	if opts.request_payer {
		headers['x-amz-request-payer'] = 'requester'
	}
	signed := sign_request(creds, SignRequest{
		method:        'HEAD'
		path:          path
		payload_hash:  empty_sha256
		extra_headers: headers
	})!
	resp := c.do_http(signed, '')!
	if resp.status_code == 404 {
		return new_error('NoSuchKey', 'No such key: ${key}')
	}
	if resp.status_code !in [200, 204] {
		return new_http_error(resp.status_code, key, resp.body)
	}
	return Stat{
		size:          resp.header.get(.content_length) or { '0' }.i64()
		last_modified: resp.header.get(.last_modified) or { '' }
		etag:          (resp.header.get(.etag) or { '' }).trim('"')
		content_type:  resp.header.get(.content_type) or { '' }
	}
}

// exists is `stat` + boolean: true on 200, false on 404, error otherwise.
pub fn (c &Client) exists(key string, opts StatOptions) !bool {
	c.stat(key, opts) or {
		if err is S3Error && err.code == 'NoSuchKey' {
			return false
		}
		return err
	}
	return true
}

// size returns just the Content-Length of the object.
pub fn (c &Client) size(key string, opts StatOptions) !i64 {
	st := c.stat(key, opts)!
	return st.size
}

// delete removes a single object. S3 returns 204 on success, 204 on
// already-absent (idempotent) — we surface success in both cases.
pub fn (c &Client) delete(key string, opts StatOptions) ! {
	creds := c.creds_for(opts.bucket)
	path := build_object_path(creds, opts.bucket, key)!
	mut headers := map[string]string{}
	if opts.request_payer {
		headers['x-amz-request-payer'] = 'requester'
	}
	signed := sign_request(creds, SignRequest{
		method:        'DELETE'
		path:          path
		payload_hash:  empty_sha256
		extra_headers: headers
	})!
	resp := c.do_http(signed, '')!
	if resp.status_code !in [200, 204] {
		return new_http_error(resp.status_code, key, resp.body)
	}
}

// presign generates a presigned URL — see PresignOptions for tunables.
pub fn (c &Client) presign(key string, opts PresignOptions) !string {
	creds := c.creds_for(opts.bucket)
	path := build_object_path(creds, opts.bucket, key)!
	mut extra := map[string]string{}
	if opts.acl != .unset {
		extra['X-Amz-Acl'] = opts.acl.to_header_value()
	}
	if opts.storage_class != .unset {
		extra['x-amz-storage-class'] = opts.storage_class.to_header_value()
	}
	if opts.content_type != '' {
		extra['response-content-type'] = opts.content_type
	}
	if opts.content_disposition != '' {
		extra['response-content-disposition'] = opts.content_disposition
	}
	if opts.request_payer {
		extra['x-amz-request-payer'] = 'requester'
	}
	return presign_url(creds, PresignRequest{
		method:      http_method_to_string(opts.method)
		path:        path
		expires_in:  opts.expires_in
		extra_query: extra
	})
}

// file returns a File reference for the given key, bound to this client.
// `path` may be `<bucket>/<key>` if the client has no default bucket and
// `bucket` here is empty.
pub fn (c &Client) file(key string, opts FileOptions) File {
	return File{
		client: c
		key:    key
		bucket: opts.bucket
	}
}

// creds_for returns credentials with `bucket` overridden if the caller passed one.
fn (c &Client) creds_for(bucket string) Credentials {
	if bucket == '' {
		return c.credentials
	}
	mut copy := c.credentials
	copy = Credentials{
		...copy
		bucket: bucket
	}
	return copy
}

// build_object_path produces the canonical URI path for a key.
// Path style: `/<bucket>/<encoded-key>[+endpoint extra path]`
// Virtual hosted: `/<encoded-key>`
// Returns an error if neither bucket nor key is provided.
// The key is forwarded byte-exact (only percent-encoded): S3 treats keys as
// opaque identifiers, so `folder/`, `/x` and `a//b` all designate distinct
// objects and must reach the wire as written.
pub fn build_object_path(creds Credentials, bucket_override string, key string) !string {
	bucket := if bucket_override != '' { bucket_override } else { creds.bucket }
	if key == '' {
		return new_error('InvalidPath', 'Empty object key')
	}
	encoded_key := uri_encode_path(key)
	extra := creds.extra_path()
	if creds.virtual_hosted_style {
		return '${extra}/${encoded_key}'
	}
	if bucket == '' {
		return new_error('InvalidPath',
			'No bucket given (set Credentials.bucket or pass bucket via options)')
	}
	encoded_bucket := uri_encode_path(strip_slashes(bucket))
	return '${extra}/${encoded_bucket}/${encoded_key}'
}

// HttpResponse is the small subset of an HTTP response we surface to callers
// of the lower-level helpers. `body` is the raw response body for non-stream
// requests; `header` keeps V's typed Header for parsing.
pub struct HttpResponse {
pub:
	status_code int
	body        string
	header      http.Header
}

// do_http fires off the signed request via V's `net.http`. The HTTP method is
// taken from `signed.method` (set by `sign_request`) so callers cannot drift
// between what was signed and what is sent on the wire.
fn (c &Client) do_http(signed SignedRequest, body string) !HttpResponse {
	mut header := http.new_header()
	for k, v in signed.headers {
		// `Host` is set automatically by V's http client; skip to avoid duplicates.
		if k.to_lower() == 'host' {
			continue
		}
		header.add_custom(canonical_header_name(k), v)!
	}
	method_enum := parse_http_method(signed.method)!
	req := http.new_request(method_enum, signed.url, body)
	mut req_mut := http.Request{
		...req
		header:        header
		read_timeout:  c.read_timeout
		write_timeout: c.write_timeout
	}
	resp := req_mut.do() or {
		return new_error('NetworkError', 'HTTP request failed: ${err.msg()}')
	}
	$if s3_debug ? {
		eprintln('[s3] ${signed.method} ${signed.url}')
		for k, v in signed.headers {
			eprintln('[s3]   > ${k}: ${redacted_value(k, v)}')
		}
		eprintln('[s3] -> ${resp.status_code}')
		eprintln('[s3] body: ${resp.body}')
	}
	return HttpResponse{
		status_code: resp.status_code
		body:        resp.body
		header:      resp.header
	}
}

// redacted_value masks credentials so they cannot leak via s3_debug logs.
fn redacted_value(name string, value string) string {
	low := name.to_lower()
	if low == 'authorization' || low.starts_with('x-amz-security-token') {
		return '<redacted>'
	}
	return value
}

// canonical_header_name turns 'x-amz-content-sha256' into 'X-Amz-Content-Sha256'
// for the wire. HTTP/1.1 says headers are case-insensitive, but some
// intermediaries / mocks aren't, so we emit the canonical Title-Case form.
fn canonical_header_name(s string) string {
	mut out := []u8{cap: s.len}
	mut upper_next := true
	for b in s.bytes() {
		if b == `-` {
			out << b
			upper_next = true
			continue
		}
		if upper_next && b >= `a` && b <= `z` {
			out << b - 32
		} else {
			out << b
		}
		upper_next = false
	}
	return out.bytestr()
}

// parse_http_method maps a SigV4 canonical method string to V's `http.Method`.
// The signer enforces the supported set up-front, so anything unexpected here
// indicates a programming bug rather than user input.
fn parse_http_method(s string) !http.Method {
	return match s.to_upper() {
		'GET' { http.Method.get }
		'PUT' { http.Method.put }
		'POST' { http.Method.post }
		'DELETE' { http.Method.delete }
		'HEAD' { http.Method.head }
		else { new_error('InvalidMethod', 'Unsupported HTTP method: ${s}') }
	}
}