feat: Split fallback into enableS3AccessGrantsFallback and enableDire…

[rajasbh-aws]

Description

Split the single enableFallback option into two independent fallback toggles that give
callers explicit control over the fallback chain when Lake Formation credential resolution
fails:

• enableS3AccessGrantsFallback (default true) — Lake Formation → S3 Access Grants → IAM.
  This is the renamed former enableFallback; the default behavior is unchanged.
• enableDirectIAMFallback (default false) — Lake Formation → IAM directly, skipping
  S3 Access Grants.

Motivation

The fallback chain was always Lake Formation → S3 Access Grants → IAM. Customers who do not use
S3 Access Grants still incur a failed S3 Access Grants call on every Lake Formation failure
before finally falling through to IAM, adding latency and CloudTrail noise. Splitting the flag
lets those customers opt into a direct Lake Formation → IAM fallback while leaving the existing
behavior as the default for everyone else.

Behavior

On a Lake Formation failure the identity provider resolves in priority order:

1. If enableS3AccessGrantsFallback is true (and an S3 Access Grants provider is available) →
   fall back to S3 Access Grants (which in turn falls back to IAM).
2. Otherwise, if enableDirectIAMFallback is true → fall back directly to the original IAM
   credentials provider, skipping S3 Access Grants.
3. Otherwise → fail with an SdkClientException.

enableS3AccessGrantsFallback	enableDirectIAMFallback	Behavior on Lake Formation failure
true (default)	false (default)	Lake Formation → S3 Access Grants → IAM
false	true	Lake Formation → IAM (skip S3 Access Grants)
true	true	Lake Formation → S3 Access Grants → IAM (S3 Access Grants takes priority)
false	false	Lake Formation only — request fails if Lake Formation cannot resolve

Changes

• AccessGrantsPluginBuilder: added enableS3AccessGrantsFallback(Boolean) and
  enableDirectIAMFallback(Boolean). The old enableFallback(Boolean) is retained as a
  @Deprecated default method that forwards to enableS3AccessGrantsFallback(...), preserving
  source and binary compatibility for existing consumers.
• LakeFormationAccessGrantsPlugin: two independent fields/defaults/accessors/builder impls;
  passes both flags into the identity provider. The inner S3AccessGrantsPlugin continues to
  receive the S3 Access Grants fallback setting.
• LakeFormationAccessGrantsIdentityProvider: two-flag priority fallback logic in the
  failure path (S3 Access Grants → direct IAM → fail).
• README: documents both options, the resolution order, and the behavior matrix.

Testing

• mvn clean test — full suite green (95 tests).
• New identity-provider tests cover: direct IAM fallback skips S3 Access Grants, S3 Access
  Grants takes priority when both are enabled, direct IAM used when the S3 Access Grants provider
  is null, and both-disabled fails without any fallback attempt.
• New plugin/builder tests cover the new defaults (enableDirectIAMFallback=false,
  enableS3AccessGrantsFallback=true), null handling, and toBuilder round-tripping of both flags.

Compatibility

Fully backward compatible. The default (enableS3AccessGrantsFallback=true,
enableDirectIAMFallback=false) preserves the exact prior behavior. The old
enableFallback(...) builder method is retained as a @Deprecated alias that forwards to
enableS3AccessGrantsFallback(...), so existing source and pre-compiled callers continue to work
without changes; it will be removed in a future major version.

---

By submitting this pull request, I confirm that you can use, modify, copy, and redistribute this
contribution, under the terms of your choice.