feat(storage): insert object acl

[brianquinlan]

This is the first step in implementing #179

[gemini-code-assist]

Code Review

This pull request introduces the insertObjectAcl method to the Storage class, enabling the creation of Access Control List entries for Google Cloud Storage objects. The implementation includes detailed documentation and a new test suite covering success cases, role updates, and error handling. Review feedback suggests fixing a documentation typo, reordering the new method for alphabetical consistency, adding support for generation and userProject parameters to achieve API parity, and removing a debug print statement from the tests.

[gemini-code-assist]

The insert operation for object ACLs supports generation and userProject query parameters. Adding these provides parity with the underlying API and other methods in this class. Note that the suggestion uses the Dart conditional map entry syntax (key: ?value) to handle nullable parameters.

  Future<ObjectAccessControl> insertObjectAcl(
    String bucket,
    String object,
    String entity,
    String role, {
    BigInt? generation,
    String? userProject,
    RetryRunner retry = defaultRetry,
  }) => retry.run(() async {
    final serviceClient = await _serviceClient;
    final url = _requestUrl([
      'storage',
      'v1',
      'b',
      bucket,
      'o',
      object,
      'acl',
    ], {
      'generation': ?generation?.toString(),
      'userProject': ?userProject,
    });
    final j = await serviceClient.post(
      url,
      body: _JsonEncodableWrapper({'entity': entity, 'role': role}),
    );
    return objectAccessControlFromJson(j as Map<String, Object?>)!;
  }, isIdempotent: false);

References

1. In Dart, the syntax key: ?value is valid in a map literal to conditionally include the entry if value is not null. This is a new language feature.