awyeah-api - aws-api for babashka

Cognitect's aws-api and babashka. Aw yeah.

Alpha Only gently tested.

awyeah-api is another Clojure library which provides programmatic access to AWS services from your Clojure or babashka program. Its raison d'être is to be a drop-in replacement for Cognitect's brilliant aws-api that will work from source with babashka.

awyeah-api should work with com.cognitect.aws/endpoints and com.cognitect.aws service packages.

Acknowledgements (and disclaimer)

This port is based on the great work done by the fine folks at Cognitect. I am not affiliated with Cognitect and this is not a Cognitect-distributed library.

Requirements

Requires babashka 0.7.0 or later (clojure.spec.alpha support).

deps

com.grzm/awyeah-api {:git/url "https://github.com/grzm/awyeah-api"
                     :git/sha "a3ce8c515c3c381fa46efea37ec680631641f52b"}

In brief

Add to your deps.edn for Clojure or bb.edn for babashka:

`deps.edn`

{:deps {com.cognitect.aws/endpoints {:mvn/version "1.1.12.206"}
        com.cognitect.aws/s3 {:mvn/version "822.2.1109.0"}
        com.github.grzm/awyeah-api {:git/url "https://github.com/grzm/awyeah-api"
                                    :git/sha "a3ce8c515c3c381fa46efea37ec680631641f52b"}}}

`bb.edn`

Include org.babashka/spec.alpha

{:deps {com.cognitect.aws/endpoints {:mvn/version "1.1.12.206"}
        com.cognitect.aws/s3 {:mvn/version "822.2.1109.0"}
        com.grzm/awyeah-api {:git/url "https://github.com/grzm/awyeah-api"
                             :git/sha "a3ce8c515c3c381fa46efea37ec680631641f52b"}
        org.babashka/spec.alpha {:git/url "https://github.com/babashka/spec.alpha"
                                 :git/sha "433b0778e2c32f4bb5d0b48e5a33520bee28b906"}}}

(require '[com.grzm.awyeah.client.api :as aws])

(def s3 (aws/client {:api :s3}))

(def buckets (-> (aws/invoke s3 {:op :ListBuckets})
                 :Buckets))

(prn buckets)

Differences from aws-api

The awyeah-api client does not auto-refresh AWS credentials. The aws-api behavior relies on features that aren't present in babashka, and I haven't figured out an alternative implementation of the behavior. My use case is short-lived scripts, where JVM start-up time can dwarf script execution time: credentials don't have much time to get stale. If I had longer-lived processes, start-up time wouldn't be an issue and I'd just use the Clojure.

The com.cognitect/http-client used by aws-api automatically uncompresses S3 objects if they have the appropriate content-type metadata in S3. I've chosen not to replicate this behavior with the bundled HTTP client based on java.net.http as I think it's a bit of a misfeature to have enabled by default in a programmatic client library like this. (That said, that makes it less of a drop-in replacement, doesn't it? I may revisit this.)

See Porting Decisions if you're interested in the nitty gritty or are wondering why I made some decision or other.

Development

Get thee to a repl!

bb --classpath $(clojure -Spath -A:bb:dev:test) nrepl-server 1138

Testing

Run the tests against a LocalStack Docker container.

bin/dc up
bin/test
bin/dc down

Known infelicities

Reflection warnings

There are currently a couple of reflection warnings I haven't sussed yet.

Reflection warning, com/grzm/awyeah/http_client.clj:116:34 - call to method timeout can't be resolved (target class is unknown).
Reflection warning, com/grzm/awyeah/http_client.clj:114:5 - reference to field build can't be resolved.

Lint warnings and errors

There are a few lint warnings to be addressed.

src/com/grzm/awyeah/client/api.clj:94:94: error: com.grzm.awyeah.endpoint/fetch is called with 1 arg but expects 2
src/com/grzm/awyeah/util.clj:126:10: error: Function arguments should be wrapped in vector.
src/com/grzm/awyeah/util.clj:214:10: error: Function arguments should be wrapped in vector.

All three of these are present in the upstream aws-api library itself. The first may well be a bug in code that's not regularly exercised or tested. The latter two I think may be a misunderstanding in clj-kondo. But I haven't dug into either.

Thanks

Much thanks to Michiel Borkent for babashka and providing support and guidance in getting the pieces in place (java.net.http and various other Java classes) to make this library possible.

Copyright and License

Licensed under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at

http://www.apache.org/licenses/LICENSE-2.0

Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License.

cap10morgan/awyeah-api