AWS.S3Control reference

AccessPoint

Source: packages/aws/src/S3Control/AccessPoint.ts

An Amazon S3 Access Point — a named network endpoint attached to a bucket with its own policy, public-access-block settings, and optional VPC restriction. Use access points to manage shared-dataset access at scale instead of maintaining one giant bucket policy.

AccessPoint: Creating Access Points

Internet access point on a bucket

import * as S3 from "@alchemy.run/aws/S3";
import * as S3Control from "@alchemy.run/aws/S3Control";

const bucket = yield* S3.Bucket("data", {});
const accessPoint = yield* S3Control.AccessPoint("data-ap", {
  bucket: bucket.bucketName,
});

VPC-only access point

const accessPoint = yield* S3Control.AccessPoint("internal-ap", {
  bucket: bucket.bucketName,
  vpcConfiguration: { vpcId: vpc.vpcId },
});

Access point with explicit public-access-block

const accessPoint = yield* S3Control.AccessPoint("locked-ap", {
  bucket: bucket.bucketName,
  publicAccessBlock: {
    blockPublicAcls: true,
    ignorePublicAcls: true,
    blockPublicPolicy: true,
    restrictPublicBuckets: true,
  },
  tags: { team: "data" },
});

AccessPoint: Granting Access

yield* S3Control.AccessPointPolicy("data-ap-policy", {
  accessPointName: accessPoint.accessPointName,
  policy: {
    Version: "2012-10-17",
    Statement: [
      {
        Effect: "Allow",
        Principal: { AWS: `arn:aws:iam::${accountId}:role/reader` },
        Action: ["s3:GetObject"],
        Resource: [Output.interpolate`${accessPoint.accessPointArn}/object/*`],
      },
    ],
  },
});

AccessPoint: Looking up an existing access point

AccessPoint.lookup references an access point Alchemy doesn’t manage (created in the console or by another stack), found by accessPointName. It is read during plan/deploy and never created, updated or deleted.

const existing = AWS.S3Control.AccessPoint.lookup({ accessPointName: "..." });

AccessPointPolicy

Source: packages/aws/src/S3Control/AccessPointPolicy.ts

The resource policy of an S3 Access Point. Grants principals access to objects through the access point — the delegated replacement for a giant shared bucket policy.

Note that the underlying bucket must delegate access control to the access point (or the principals must also be allowed by the bucket policy).

AccessPointPolicy: Attaching a Policy

import * as S3Control from "@alchemy.run/aws/S3Control";

const accessPoint = yield* S3Control.AccessPoint("data-ap", {
  bucket: bucket.bucketName,
});

yield* S3Control.AccessPointPolicy("data-ap-policy", {
  accessPointName: accessPoint.accessPointName,
  policy: {
    Version: "2012-10-17",
    Statement: [
      {
        Effect: "Allow",
        Principal: { AWS: `arn:aws:iam::${accountId}:role/reader` },
        Action: ["s3:GetObject"],
        Resource: [Output.interpolate`${accessPoint.accessPointArn}/object/*`],
      },
    ],
  },
});

CreateJob

Source: packages/aws/src/S3Control/CreateJob.ts

Runtime binding for s3:CreateJob (S3 Batch Operations).

Submits a large-scale batch job — copy, tag, ACL, restore, or Lambda-invoke — over a manifest of S3 objects, e.g. an ingest Lambda that kicks off a bulk re-tagging run. The binding also grants iam:PassRole so the function can hand the service the job’s execution role. The account id is resolved once via sts:GetCallerIdentity. Provide the implementation with Effect.provide(AWS.S3Control.CreateJobHttp).

CreateJob: Running Batch Operations Jobs

// init — account-level binding, no resource argument
const createJob = yield* AWS.S3Control.CreateJob();

// runtime
const { JobId } = yield* createJob({
  ConfirmationRequired: true,
  Priority: 1,
  RoleArn: batchRoleArn,
  Operation: { S3PutObjectTagging: { TagSet: [{ Key: "swept", Value: "true" }] } },
  Report: { Enabled: false },
  ClientRequestToken: token,
  ManifestGenerator: {
    S3JobManifestGenerator: {
      SourceBucket: bucketArn,
      EnableManifestOutput: false,
    },
  },
});

DescribeJob

Source: packages/aws/src/S3Control/DescribeJob.ts

Runtime binding for s3:DescribeJob (S3 Batch Operations).

Reads an S3 Batch Operations job’s configuration, status and progress summary — e.g. a controller polling a bulk copy it submitted with CreateJob. The account id is resolved once via sts:GetCallerIdentity. Provide the implementation with Effect.provide(AWS.S3Control.DescribeJobHttp).

DescribeJob: Running Batch Operations Jobs

// init — account-level binding, no resource argument
const describeJob = yield* AWS.S3Control.DescribeJob();

// runtime
const { Job } = yield* describeJob({ JobId: jobId });
// Job?.Status === "Complete"

GetAccessPoint

Source: packages/aws/src/S3Control/GetAccessPoint.ts

Runtime binding for s3:GetAccessPoint.

Reads the bound AccessPoint’s live configuration — bucket, network origin, public-access-block flags, alias and endpoints — e.g. an operational dashboard or a controller that verifies the access point is still wired to the expected bucket. The access point name and owning account are injected from the binding. Provide the implementation with Effect.provide(AWS.S3Control.GetAccessPointHttp).

GetAccessPoint: Observing an Access Point

// init — bind the operation to the access point
const getAccessPoint = yield* AWS.S3Control.GetAccessPoint(accessPoint);

// runtime
const live = yield* getAccessPoint();
// live.Bucket, live.NetworkOrigin, live.Endpoints

GetAccessPointPolicy

Source: packages/aws/src/S3Control/GetAccessPointPolicy.ts

Runtime binding for s3:GetAccessPointPolicy.

Reads the resource policy attached to the bound AccessPoint. An access point without a policy fails with the typed NoSuchAccessPointPolicy tag. Provide the implementation with Effect.provide(AWS.S3Control.GetAccessPointPolicyHttp).

GetAccessPointPolicy: Observing an Access Point

// init — bind the operation to the access point
const getPolicy = yield* AWS.S3Control.GetAccessPointPolicy(accessPoint);

// runtime
const policy = yield* getPolicy().pipe(
  Effect.catchTag("NoSuchAccessPointPolicy", () =>
    Effect.succeed({ Policy: undefined }),
  ),
);

GetAccessPointPolicyStatus

Source: packages/aws/src/S3Control/GetAccessPointPolicyStatus.ts

Runtime binding for s3:GetAccessPointPolicyStatus.

Indicates whether the bound AccessPoint’s policy currently allows public access — e.g. a compliance auditor Lambda that alerts on publicly exposed access points. An access point without a policy fails with the typed NoSuchAccessPointPolicy tag. Provide the implementation with Effect.provide(AWS.S3Control.GetAccessPointPolicyStatusHttp).

GetAccessPointPolicyStatus: Observing an Access Point

// init — bind the operation to the access point
const getPolicyStatus =
  yield* AWS.S3Control.GetAccessPointPolicyStatus(accessPoint);

// runtime
const status = yield* getPolicyStatus();
// status.PolicyStatus?.IsPublic === false

GetMultiRegionAccessPointRoutes

Source: packages/aws/src/S3Control/GetMultiRegionAccessPointRoutes.ts

Runtime binding for s3:GetMultiRegionAccessPointRoutes.

Reads the bound MultiRegionAccessPoint’s per-region routing configuration (each region’s TrafficDialPercentage) — the observe half of an active/passive failover controller. Requests are routed to the us-west-2 MRAP control plane. Provide the implementation with Effect.provide(AWS.S3Control.GetMultiRegionAccessPointRoutesHttp).

GetMultiRegionAccessPointRoutes: Controlling Multi-Region Failover

// init — bind the operation to the Multi-Region Access Point
const getRoutes =
  yield* AWS.S3Control.GetMultiRegionAccessPointRoutes(mrap);

// runtime
const { Routes } = yield* getRoutes();
// Routes?.map((r) => `${r.Region}: ${r.TrafficDialPercentage}%`)

ListAccessPoints

Source: packages/aws/src/S3Control/ListAccessPoints.ts

Runtime binding for s3:ListAccessPoints.

Lists the access points in the caller’s account, optionally filtered to a single bucket — e.g. an inventory Lambda that audits which endpoints expose a shared dataset. The account id is resolved once via sts:GetCallerIdentity. Provide the implementation with Effect.provide(AWS.S3Control.ListAccessPointsHttp).

ListAccessPoints: Listing Access Points

// init — account-level binding, no resource argument
const listAccessPoints = yield* AWS.S3Control.ListAccessPoints();

// runtime
const page = yield* listAccessPoints({ Bucket: bucketName });
// page.AccessPointList?.map((ap) => ap.Name)

ListJobs

Source: packages/aws/src/S3Control/ListJobs.ts

Runtime binding for s3:ListJobs (S3 Batch Operations).

Lists the account’s current jobs and the jobs that ended within the last 90 days, optionally filtered by status — e.g. an operations dashboard summarizing in-flight bulk operations. The account id is resolved once via sts:GetCallerIdentity. Provide the implementation with Effect.provide(AWS.S3Control.ListJobsHttp).

ListJobs: Running Batch Operations Jobs

// init — account-level binding, no resource argument
const listJobs = yield* AWS.S3Control.ListJobs();

// runtime
const { Jobs } = yield* listJobs({ JobStatuses: ["Active"] });

MultiRegionAccessPoint

Source: packages/aws/src/S3Control/MultiRegionAccessPoint.ts

An Amazon S3 Multi-Region Access Point — a single global endpoint that routes requests to buckets in multiple regions over the AWS global network.

Provisioning is asynchronous and slow (several minutes); the provider submits the request and waits until the access point reaches READY. All control-plane requests are routed through us-west-2, as required by the Multi-Region Access Point API.

MultiRegionAccessPoint: Creating Multi-Region Access Points

Route between two regional buckets

import * as S3Control from "@alchemy.run/aws/S3Control";

const mrap = yield* S3Control.MultiRegionAccessPoint("global", {
  regions: [
    { bucket: usWestBucket.bucketName },
    { bucket: euCentralBucket.bucketName },
  ],
});

Single-region Multi-Region Access Point

const mrap = yield* S3Control.MultiRegionAccessPoint("global", {
  regions: [{ bucket: bucket.bucketName }],
});

MultiRegionAccessPoint: Looking up an existing multi region access point

MultiRegionAccessPoint.lookup references a multi region access point Alchemy doesn’t manage (created in the console or by another stack), found by multiRegionAccessPointName. It is read during plan/deploy and never created, updated or deleted.

const existing = AWS.S3Control.MultiRegionAccessPoint.lookup({ multiRegionAccessPointName: "..." });

ObjectLambdaAccessPoint

Source: packages/aws/src/S3Control/ObjectLambdaAccessPoint.ts

An S3 Object Lambda Access Point — intercepts S3 GetObject / HeadObject / ListObjects requests through a supporting access point and transforms responses with a Lambda function (redaction, resizing, format conversion, …).

ObjectLambdaAccessPoint: Creating Object Lambda Access Points

Transform GetObject responses with a Lambda

import * as S3Control from "@alchemy.run/aws/S3Control";

const accessPoint = yield* S3Control.AccessPoint("data-ap", {
  bucket: bucket.bucketName,
});

const olap = yield* S3Control.ObjectLambdaAccessPoint("transform-ap", {
  supportingAccessPoint: accessPoint.accessPointArn,
  transformationConfigurations: [
    {
      Actions: ["GetObject"],
      ContentTransformation: {
        AwsLambda: { FunctionArn: transformer.functionArn },
      },
    },
  ],
});

Pass Range/PartNumber through and enable metrics

const olap = yield* S3Control.ObjectLambdaAccessPoint("transform-ap", {
  supportingAccessPoint: accessPoint.accessPointArn,
  allowedFeatures: ["GetObject-Range", "GetObject-PartNumber"],
  cloudWatchMetricsEnabled: true,
  transformationConfigurations: [
    {
      Actions: ["GetObject"],
      ContentTransformation: {
        AwsLambda: { FunctionArn: transformer.functionArn },
      },
    },
  ],
});

ObjectLambdaAccessPoint: Looking up an existing object lambda access point

ObjectLambdaAccessPoint.lookup references an object lambda access point Alchemy doesn’t manage (created in the console or by another stack), found by objectLambdaAccessPointName. It is read during plan/deploy and never created, updated or deleted.

const existing = AWS.S3Control.ObjectLambdaAccessPoint.lookup({ objectLambdaAccessPointName: "..." });

StorageLensConfiguration

Source: packages/aws/src/S3Control/StorageLensConfiguration.ts

An Amazon S3 Storage Lens configuration — an account-wide (or organization-wide) storage analytics dashboard aggregating usage and activity metrics across buckets, with optional daily export to S3 or CloudWatch.

StorageLensConfiguration: Creating Dashboards

Free-metrics dashboard over the whole account

import * as S3Control from "@alchemy.run/aws/S3Control";

const lens = yield* S3Control.StorageLensConfiguration("account-lens", {});

Dashboard scoped to specific buckets

const lens = yield* S3Control.StorageLensConfiguration("data-lens", {
  include: {
    Buckets: [bucket.bucketArn],
  },
});

Advanced metrics with S3 export

const lens = yield* S3Control.StorageLensConfiguration("advanced-lens", {
  accountLevel: {
    ActivityMetrics: { IsEnabled: true },
    BucketLevel: {
      ActivityMetrics: { IsEnabled: true },
    },
  },
  dataExport: {
    S3BucketDestination: {
      Format: "CSV",
      OutputSchemaVersion: "V_1",
      AccountId: accountId,
      Arn: reportBucket.bucketArn,
    },
  },
});

Disable a dashboard without deleting it

const lens = yield* S3Control.StorageLensConfiguration("account-lens", {
  isEnabled: false,
});

SubmitMultiRegionAccessPointRoutes

Source: packages/aws/src/S3Control/SubmitMultiRegionAccessPointRoutes.ts

Runtime binding for s3:SubmitMultiRegionAccessPointRoutes.

Shifts traffic between the bound MultiRegionAccessPoint’s regions by dialing each region’s TrafficDialPercentage (0 = passive, 100 = active) — the act half of an automated failover controller, e.g. a health-check Lambda that dials a degraded region to 0. Requests are routed to the us-west-2 MRAP control plane. Provide the implementation with Effect.provide(AWS.S3Control.SubmitMultiRegionAccessPointRoutesHttp).

SubmitMultiRegionAccessPointRoutes: Controlling Multi-Region Failover

// init — bind the operation to the Multi-Region Access Point
const submitRoutes =
  yield* AWS.S3Control.SubmitMultiRegionAccessPointRoutes(mrap);

// runtime
yield* submitRoutes({
  RouteUpdates: [
    { Region: "us-west-2", TrafficDialPercentage: 0 },
    { Region: "eu-west-1", TrafficDialPercentage: 100 },
  ],
});

UpdateJobPriority

Source: packages/aws/src/S3Control/UpdateJobPriority.ts

Runtime binding for s3:UpdateJobPriority (S3 Batch Operations).

Re-prioritizes an existing job relative to the account’s other jobs — e.g. bumping an urgent restore ahead of routine re-tagging runs. The account id is resolved once via sts:GetCallerIdentity. Provide the implementation with Effect.provide(AWS.S3Control.UpdateJobPriorityHttp).

UpdateJobPriority: Running Batch Operations Jobs

// init — account-level binding, no resource argument
const updateJobPriority = yield* AWS.S3Control.UpdateJobPriority();

// runtime
const updated = yield* updateJobPriority({ JobId: jobId, Priority: 10 });
// updated.Priority === 10

UpdateJobStatus

Source: packages/aws/src/S3Control/UpdateJobStatus.ts

Runtime binding for s3:UpdateJobStatus (S3 Batch Operations).

Confirms a suspended job so it runs (Ready) or cancels it (Cancelled) — e.g. an approval workflow that releases a bulk delete only after a human signs off. The account id is resolved once via sts:GetCallerIdentity. Provide the implementation with Effect.provide(AWS.S3Control.UpdateJobStatusHttp).

UpdateJobStatus: Running Batch Operations Jobs

// init — account-level binding, no resource argument
const updateJobStatus = yield* AWS.S3Control.UpdateJobStatus();

// runtime
yield* updateJobStatus({
  JobId: jobId,
  RequestedJobStatus: "Cancelled",
  StatusUpdateReason: "superseded by newer manifest",
});