|
| 1 | +/* |
| 2 | + * Copyright (c) 2024-2025 Elide Technologies, Inc. |
| 3 | + * |
| 4 | + * Licensed under the MIT license (the "License"); you may not use this file except in compliance |
| 5 | + * with the License. You may obtain a copy of the License at |
| 6 | + * |
| 7 | + * https://opensource.org/license/mit/ |
| 8 | + * |
| 9 | + * Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on |
| 10 | + * an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the |
| 11 | + * License for the specific language governing permissions and limitations under the License. |
| 12 | + */ |
| 13 | +package elide.runtime.intrinsics.js.s3 |
| 14 | + |
| 15 | +import org.graalvm.polyglot.Value |
| 16 | +import org.graalvm.polyglot.proxy.ProxyObject |
| 17 | +import elide.runtime.gvm.js.JsError |
| 18 | +import elide.runtime.intrinsics.js.Blob |
| 19 | +import elide.runtime.intrinsics.js.JsPromise |
| 20 | +import elide.runtime.intrinsics.js.ReadableStream |
| 21 | +import elide.runtime.node.buffer.GuestBytes |
| 22 | +import elide.vm.annotations.Polyglot |
| 23 | + |
| 24 | +private const val ACCESS_KEY_ID = "accessKeyId" |
| 25 | +private const val SECRET_ACCESS_KEY = "secretAccessKey" |
| 26 | +private const val BUCKET = "bucket" |
| 27 | +private const val SESSION_TOKEN = "sessionToken" |
| 28 | +private const val ACL = "acl" |
| 29 | +private const val ENDPOINT = "endpoint" |
| 30 | +private const val REGION = "region" |
| 31 | +private const val VIRTUAL_HOSTED_STYLE = "virtualHostedStyle" |
| 32 | + |
| 33 | +/** |
| 34 | + * # S3 |
| 35 | + * |
| 36 | + * Facade for calling out to AWS S3 SDK. Meant to be used to provide an S3 |
| 37 | + * API from within the Elide runtime. |
| 38 | + * |
| 39 | + * It consists of two major objects, the S3Client which tracks the configuration for authentication and how to connect |
| 40 | + * and the S3File which represents a file in S3 that can be read, written to, or presigned. |
| 41 | + * |
| 42 | + * |
| 43 | + * |
| 44 | + * ## Usage |
| 45 | + * |
| 46 | + * In the following example, the S3Client will connect to Backblaze B2 (an S3 compatible service) |
| 47 | + * using a path style endpoint. If the endpoint is not specified, by default it will use AWS S3. |
| 48 | + * If region is unspecified it will use us-east-1. |
| 49 | + * It will use path style URLs by default. |
| 50 | + * |
| 51 | + * Please look at AWS's S3 documentation or the documentation for whatever S3 compatible API is being used for more |
| 52 | + * information on what these options mean. |
| 53 | + * |
| 54 | + * ```javascript |
| 55 | + * const { S3Client } = require("elide:s3"); |
| 56 | + * const client = new S3Client({ |
| 57 | + * // required options |
| 58 | + * accessKeyId: "...", |
| 59 | + * secretAccessKey: "...", |
| 60 | + * bucket: "my-bucket", |
| 61 | + * // optional options |
| 62 | + * sessionToken: "...", |
| 63 | + * acl: "public-read", |
| 64 | + * endpoint: "https://s3.us-east-005.backblazeb2.com/my-bucket", |
| 65 | + * region: "us-east-005", |
| 66 | + * virtualHostedStyle: false |
| 67 | + * }); |
| 68 | + * const file = client.file("test.txt"); |
| 69 | + * await file.write("This is a test", { type: "text/plain" }); |
| 70 | + * console.assert(await file.text() === "This is a test"); |
| 71 | + * ``` |
| 72 | + * |
| 73 | + * Write method takes either a String or any array type object and returns a promise |
| 74 | + * containing the content length. |
| 75 | + * |
| 76 | + * Read methods include: text, json, bytes, and arrayBuffer. Which are self-explanatory. |
| 77 | + * |
| 78 | + * Presign allows one to presign a URL to be passed to the client so the client can do the |
| 79 | + * actual action, minimizing a redundant data transfer, a common pattern with S3 usage. |
| 80 | + * eg |
| 81 | + * ``` |
| 82 | + * file.presign({ method: "GET", expiresIn: 3600 }); // expiresIn is in seconds |
| 83 | + * ``` |
| 84 | + * |
| 85 | + * `delete` and `unlink` are identical. Both allow the user to delete a file from S3. |
| 86 | + * |
| 87 | + * Finally, `stat` returns the metadata and objects in the HTTP header in a JSON format. It |
| 88 | + * is equivalent to the "HeadObject" action. |
| 89 | + */ |
| 90 | +public interface S3Client : ProxyObject { |
| 91 | + @Polyglot public fun file(path: String): S3File |
| 92 | +} |
| 93 | + |
| 94 | +public interface S3File : ProxyObject { |
| 95 | + // write methods |
| 96 | + @Polyglot public fun write(data: String, contentType: String?): JsPromise<Number> |
| 97 | + @Polyglot public fun write(data: GuestBytes, contentType: String?): JsPromise<Number> |
| 98 | + @Polyglot public fun write(data: Blob, contentType: String?): JsPromise<Number> |
| 99 | + @Polyglot public fun write(data: ReadableStream, contentType: String?): JsPromise<Number> |
| 100 | + |
| 101 | + // read methods |
| 102 | + @Polyglot public fun text(): JsPromise<String> |
| 103 | + @Polyglot public fun json(): JsPromise<Value> |
| 104 | + @Polyglot public fun bytes(): JsPromise<Value> |
| 105 | + @Polyglot public fun arrayBuffer(): JsPromise<Value> |
| 106 | + |
| 107 | + @Polyglot public fun presign(method: String, duration: Long): String |
| 108 | + @Polyglot public fun delete(): JsPromise<Unit> |
| 109 | + |
| 110 | + @Polyglot public fun exists(): JsPromise<Boolean> |
| 111 | + @Polyglot public fun stat(): JsPromise<ProxyObject> |
| 112 | +} |
| 113 | + |
| 114 | +@JvmRecord public data class S3ClientConstructorOptions( |
| 115 | + @get:Polyglot val accessKeyId: String, |
| 116 | + @get:Polyglot val secretAccessKey: String, |
| 117 | + @get:Polyglot val bucket: String, |
| 118 | + @get:Polyglot val sessionToken: String?, |
| 119 | + @get:Polyglot val acl: String?, |
| 120 | + @get:Polyglot val endpoint: String?, |
| 121 | + @get:Polyglot val region: String?, |
| 122 | + @get:Polyglot val virtualHostedStyle: Boolean? |
| 123 | +) { |
| 124 | + public companion object { |
| 125 | + @JvmStatic public fun from(value: Value): S3ClientConstructorOptions { |
| 126 | + return S3ClientConstructorOptions( |
| 127 | + // required |
| 128 | + accessKeyId = value.getMember(ACCESS_KEY_ID).asString() |
| 129 | + ?: throw JsError.typeError("S3Client constructor missing accessKeyId"), |
| 130 | + secretAccessKey = value.getMember(SECRET_ACCESS_KEY).asString() |
| 131 | + ?: throw JsError.typeError("S3Client constructor missing secretAccessKey"), |
| 132 | + bucket = value.getMember(BUCKET).asString() |
| 133 | + ?: throw JsError.typeError("S3Client constructor missing bucket"), |
| 134 | + |
| 135 | + // optional |
| 136 | + sessionToken = value.getMember(SESSION_TOKEN)?.asString(), |
| 137 | + acl = value.getMember(ACL)?.asString(), |
| 138 | + endpoint = value.getMember(ENDPOINT)?.asString(), |
| 139 | + region = value.getMember(REGION)?.asString(), |
| 140 | + virtualHostedStyle = value.getMember(VIRTUAL_HOSTED_STYLE)?.asBoolean() |
| 141 | + ) |
| 142 | + } |
| 143 | + } |
| 144 | +} |
0 commit comments