1import * as S3 from "@distilled.cloud/aws/s3";
2import * as Effect from "effect/Effect";
3import * as Binding from "../../Binding.ts";
4import type { Bucket } from "./Bucket.ts";
5
6export interface HeadObjectRequest extends Omit<
7 S3.HeadObjectRequest,
8 "Bucket"
9> {}
10
11/**
12 * Runtime binding for `s3:HeadObject`.
13 *
14 * Bind this operation to a bucket to get a callable that reads an object's
15 * metadata (size, content type, ETag) without downloading the body. Provide
16 * the implementation with `Effect.provide(AWS.S3.HeadObjectHttp)`.
17 *
18 * The HTTP implementation grants `s3:GetObject` for current-object reads and
19 * `s3:GetObjectVersion` because this request also supports `VersionId`. It
20 * additionally grants `s3:ListBucket` so a missing key produces AWS's
21 * documented `404`/`403` distinction instead of always being reported as
22 * `AccessDenied`. See the [HeadObject API](https://docs.aws.amazon.com/AmazonS3/latest/API/API_HeadObject.html)
23 * and [S3 required permissions](https://docs.aws.amazon.com/AmazonS3/latest/userguide/using-with-s3-policy-actions.html).
24 *
25 * ### Inspecting Objects
26 * **Example:** Check an Object's Metadata
27 * ```typescript
28 * // init — bind the operation to the bucket
29 * const headObject = yield* AWS.S3.HeadObject(bucket);
30 *
31 * // runtime — inspect without transferring the body
32 * const head = yield* headObject({ Key: "uploads/report.pdf" });
33 * const size = head.ContentLength;
34 * const contentType = head.ContentType;
35 * ```
36 *
37 * @see https://docs.aws.amazon.com/AmazonS3/latest/API/API_HeadObject.html
38 * @see https://docs.aws.amazon.com/AmazonS3/latest/userguide/using-with-s3-policy-actions.html
39 *
40 * @binding
41 */
42export interface HeadObject extends Binding.Service<
43 HeadObject,
44 "AWS.S3.HeadObject",
45 (
46 bucket: Bucket,
47 ) => Effect.Effect<
48 (
49 request: HeadObjectRequest,
50 ) => Effect.Effect<S3.HeadObjectOutput, S3.HeadObjectError>
51 >
52> {}
53
54export const HeadObject = Binding.Service<HeadObject>("AWS.S3.HeadObject");