specs/056-s3.md

Rama main · réplica de lectura del repositorio original.

# Spec: S3 Actions

## Status

Partially implemented.

## Scope

This spec covers configuration acceptance and required fields for
`s3.upload`, `s3.download`, `s3.list`, and `s3.delete`.

Conformance does not require an S3 service. Transfers, listing formats,
content-type inference, multipart tuning, credentials, and service errors
belong to executor unit and integration coverage.

## Goal

Workflow authors can configure S3 actions and receive useful errors for
incomplete action configuration.

## Behavior

A DAG containing configured upload, download, list, and delete actions
passes `dagu validate` without contacting an S3 service or reading upload
sources. A DAG-level `s3:` block may provide the bucket and region.

Every operation requires a bucket. Upload requires a source and key;
download requires a key and destination; delete requires a key or prefix.
These required-field checks occur when the step starts, before contacting
the service.

## Errors

The following incomplete configurations fail with a nonzero exit code
and an error identifying the missing field:

- No bucket: `bucket is required`.
- Upload without a source: `source is required for upload`.
- Download without a destination: `destination is required for download`.
- Delete without a key or prefix: `key or prefix is required for delete`.

Timeout, abort, transfer cleanup, and service failure behavior are outside
this configuration conformance scope.

## Example

```yaml
s3:
  bucket: my-artifacts
  region: us-east-1
steps:
  - action: s3.upload
    with:
      source: ./dist/app.tar.gz
      key: releases/app.tar.gz
```