{"id":13895753,"url":"https://github.com/leafo/cloud_storage","last_synced_at":"2025-10-17T15:12:15.517Z","repository":{"id":5360867,"uuid":"6547217","full_name":"leafo/cloud_storage","owner":"leafo","description":"A Lua library for communicating with Google Cloud Storage","archived":false,"fork":false,"pushed_at":"2025-09-03T19:15:26.000Z","size":109,"stargazers_count":39,"open_issues_count":2,"forks_count":13,"subscribers_count":9,"default_branch":"master","last_synced_at":"2025-09-03T21:23:02.369Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"language":"Lua","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/leafo.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":null,"code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null}},"created_at":"2012-11-05T16:04:50.000Z","updated_at":"2025-09-03T19:15:29.000Z","dependencies_parsed_at":"2022-07-06T06:32:02.267Z","dependency_job_id":null,"html_url":"https://github.com/leafo/cloud_storage","commit_stats":null,"previous_names":[],"tags_count":5,"template":false,"template_full_name":null,"purl":"pkg:github/leafo/cloud_storage","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/leafo%2Fcloud_storage","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/leafo%2Fcloud_storage/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/leafo%2Fcloud_storage/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/leafo%2Fcloud_storage/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/leafo","download_url":"https://codeload.github.com/leafo/cloud_storage/tar.gz/refs/heads/master","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/leafo%2Fcloud_storage/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":279366951,"owners_count":26156523,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","status":"online","status_checked_at":"2025-10-17T02:00:07.504Z","response_time":56,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2024-08-06T18:02:26.845Z","updated_at":"2025-10-17T15:12:15.509Z","avatar_url":"https://github.com/leafo.png","language":"Lua","funding_links":[],"categories":["MoonScript"],"sub_categories":[],"readme":"# `cloud_storage`\n\n![test](https://github.com/leafo/cloud_storage/workflows/test/badge.svg)\n\nA library for connecting to [Google Cloud Storage](https://cloud.google.com/products/cloud-storage) through Lua.\n\n## Tutorial\n\nYou can learn more about authenticating with Google Cloud Storage here:\n\u003chttps://cloud.google.com/storage/docs/authentication\u003e.\n\nHere's a quick guide to get you started:\n\nThe easiest way use this library is to create a service account for your\nproject. You'll need to generate a private key and store it alongside your\nconfiguration.\n\nGo to the cloud console: \u003chttps://console.cloud.google.com\u003e. Enable Cloud\nStorage if you haven't done so already. You may also need to enter billing\ninformation.\n\nNavigate to **IAM \u0026 admin** » **Service accounts**, located on the sidebar.\nClick **Create service account**.\n\n![Create service account](http://leafo.net/shotsnb/2018-03-31_20-54-45.png)\n\nSelect **Furnish a new private key** and select **JSON** as the type. After\ncreating the service account your browser will download a `.json` file. Store\nthat securely, since it grants access to your project.\n\nThe `.json` is used to create a new API client with this library:\n\n```lua\nlocal google = require \"cloud_storage.google\"\nlocal storage = google.CloudStorage:from_json_key_file(\"path/to/my-key.json\")\n\n-- you can now use any of the methods on the storage object\nlocal files = assert(storage:get_bucket(\"my_bucket\"))\n```\n\n\u003cdetails\u003e\n\n\u003csummary\u003e\n\n## Using a p12/pem secret key\n\n\u003c/summary\u003e\n\nUse these directions only if you have a key created with the `P12` type.\n\nThe private key downloaded from the Cloud Console is a `.p12` file. The key\nuses a hard coded password `notasecret`.\n\nIn order to use it, it must be converted to a `.pem` file. Run the following\ncommand (replacing `key.p12` and `key.pem` with the input filename and desired\noutput filename). Enter `notasecret` for the password.\n\n```bash\nopenssl pkcs12 -in key.p12 -out key.pem -nodes -clcerts\n```\n\nOne more piece of information is needed: the service account email address.\nYou'll find it labeled **Service account ID** on the service account list. It\nmight look something like `cloud-storage@my-project.iam.gserviceaccount.com`.\n\nYou can now connect to the API. Create a new client like this:\n\n```lua\nlocal oauth = require \"cloud_storage.oauth\"\nlocal google = require \"cloud_storage.google\"\n\n-- replace with your service account ID\nlocal o = oauth.OAuth(\"cloud-storage@my-project.iam.gserviceaccount.com\", \"path/to/key.pem\")\n\n-- use your id as the second argument, everything before the @ in your service account ID\nlocal storage = google.CloudStorage(o, \"cloud-storage\")\n\nlocal files = assert(storage:get_bucket(\"my_bucket\"))\n```\n\n\u003c/details\u003e\n\n## HTTP Client Customization\n\nBy default, this library uses `socket.http` for making HTTP requests. You can provide a custom HTTP client that supports the LuaSocket interface:\n\n```lua\nlocal http = require(\"cloud_storage.http\")\n\n-- Replace with your custom HTTP client\n-- Must implement a request() function compatible with LuaSocket\nhttp.set(require(\"lapis.http\"))\n\n-- Now all future requests will use the `request` function in your http client...\n```\n\nThis allows for custom timeout handling, proxy configuration, or mock clients for testing.\n\n## Reference\n\n### Module `cloud_storage.oauth`\n\nThis module contains the OAuth implementation used by the storage API.\n\n```lua\nlocal oauth = require \"cloud_storage.oauth\"\n```\n\n#### `ouath_instance = oauth.OAuth(service_email, path_to_pem_file=nil)`\n\nCreate a new OAuth object. Handles OAuth authenticated requests.\n\nIt's not necessary to use this module directly if loading private key from a\n`.json` file.\n\n### Module `cloud_storage.google`\n\nCommunicates with the Google cloud storage API.\n\n```lua\nlocal google = require \"cloud_storage.google\"\n```\n\n#### Error handling\n\nAny methods that fail to execute will return `nil`, an error message, and an\nobject that represents the error. Successful responses will return a Lua table\ncontaining the details of the operation.\n\n#### `storage = google.CloudStorage(ouath_instance, project_id)`\n\nCreate a new instance of a storage object from an OAuth instance. Note that the\n`from_json_key_file` interface is a simpler way of constructing the storage\ninterface.\n\n```lua\nlocal oauth = require \"cloud_storage.oauth\"\nlocal google = require \"cloud_storage.google\"\n\nlocal o = oauth.OAuth(\"me@my-project.iam.gserviceaccount.com\", \"key.pem\")\n\nlocal storage = google.CloudStorage(o, \"111111111111\")\n```\n\n#### `storage = google.CloudStorage:from_json_key_file(json_key_file_name)`\n\nCreate a new instance of a storage object from a `.json` private key file\ngenerated by the Google Cloud Console.\n\n```lua\nlocal google = require \"cloud_storage.google\"\nlocal storage = google.CloudStorage:from_json_key_file(\"my-storage-auth.json\")\n```\n\n#### `storage:get_service()`\n\n\u003chttps://cloud.google.com/storage/docs/xml-api/get-service\u003e\n\n#### `storage:get_bucket(bucket)`\n\n\u003chttps://cloud.google.com/storage/docs/xml-api/get-bucket\u003e\n\n#### `storage:get_file(bucket, key)`\n\n\u003chttps://cloud.google.com/storage/docs/xml-api/get-object\u003e\n\n#### `storage:delete_file(bucket, key)`\n\n\u003chttps://cloud.google.com/storage/docs/xml-api/delete-object\u003e\n\n#### `storage:head_file(bucket, key)`\n\n\u003chttps://cloud.google.com/storage/docs/xml-api/head-object\u003e\n\n#### `storage:copy_file(source_bucket, source_key, dest_bucket, dest_key, options={})`\n\n\u003chttps://cloud.google.com/storage/docs/xml-api/put-object-copy\u003e\n\nOptions:\n\n* `acl`: value to use for `x-goog-acl`, defaults to `public-read`\n* `headers`: table of additional headers to include in request\n\n#### `storage:compose(bucket, key, source_keys, options={})`\n\n\u003chttps://cloud.google.com/storage/docs/xml-api/put-object-compose\u003e\n\nComposes a new file from multiple source files in the same bucket by\nconcatenating them.\n\n`source_keys` is an array of keys as strings or an array of key declarations as\ntables.\n\nThe table format for a source key is structured like this:\n\n```lua\n{\n  name = \"file.png\",\n  -- optional fields:\n  generation = \"1361471441094000\",\n  if_generation_match = \"1361471441094000\",\n}\n```\n\nOptions:\n\n* `acl`: value to use for `x-goog-acl`, defaults to `public-read`\n* `mimetype`: sets `Content-type` header for the composed file\n* `headers`: table of additional headers to include in request\n\n#### `storage:put_file_string(bucket, key, data, opts={})`\n\n\u003e **Note:** this API previously had `key` as an option but it was moved to\n\u003e second argument\n\nUploads the string `data` to the bucket at the specified key.\n\nOptions include:\n\n * `mimetype`: sets `Content-type` header for the file, defaults to not being set\n * `acl`: sets the `x-goog-acl` header for file, defaults to `public-read`\n * `headers`: an optional array table of any additional headers to send\n\n```lua\nstorage:put_file_string(\"my_bucket\", \"message.txt\", \"hello world!\", {\n  mimetype = \"text/plain\",\n  acl = \"private\"\n})\n```\n\n#### `storage:put_file(bucket, fname, opts={})`\n\nReads `fname` from disk and uploads it. The key of the file will be the name of\nthe file unless `opts.key` is provided. The mimetype of the file is guessed\nbased on the extension unless `opts.mimetype` is provided.\n\n```lua\nstorage:put_file(\"my_bucket\", \"source.lua\", {\n  mimetype = \"text/lua\"\n})\n```\n\nAll the same options from `put_file_string` are available for this method.\n\n\u003e **Note:** This method is currently inefficient . The whole file is loaded\n\u003e into memory and sent at once in the request. An alternative implementation\n\u003e will be added in the future. Open a ticket if you need it.\n\n#### `storage:start_resumable_upload(bucket, key, options={})`\n\n\u003chttps://cloud.google.com/storage/docs/xml-api/resumable-upload\u003e\n\nOptions:\n\n* `acl`: value to use for `x-goog-acl`, defaults to `public-read`\n* `mimetype`: sets `Content-type` header for the composed file\n* `headers`: table of additional headers to include in request\n\n#### `storage:bucket_url(bucket, opts={})`\n\nReturns full URL for a bucket\n\nOptions:\n\n* `subdomain`:  use the `{bucket}.domain` format  instead of default `domain/{bucket}` format\n* `scheme`: protocol of returned URL, default `https`\n\n#### `storage:bucket_url(bucket, opts={})`\n\nReturns full URL for a key on a bucket. Supports the same options as `storage:bucket_url` method.\n\n```lua\nstorage:file_url(\"my-bucket\", \"pics/leafo.png\") --\u003e \"https://commondatastorage.googleapis.com/my-bucket/pics/leafo.png\"\nstorage:file_url(\"my-bucket\", \"pics/leafo.png\", {\n  scheme = \"http\",\n  subdomain = true,\n}) --\u003e \"http://my-bucket.commondatastorage.googleapis.com/pics/leafo.png\"\n```\n\nOptions:\n\n* `subdomain`:  use the `{bucket}.domain` format  instead of default `domain/{bucket}` format\n* `scheme`: protocol of returned URL, default `https`\n\n#### `storage:signed_url(bucket, key, expiration, opts={})`\n\nCreates a temporarily URL for downloading an object regardless of it's ACL.\n`expiration` is a Unix timestamp in the future, like one generated from\n`os.time()`.\n\n```lua\nprint(storage:signed_url(\"my_bucket\", \"message.txt\", os.time() + 100))\n```\n\nOptions:\n\n* `headers`: table of additional `x-goog` headers to embed into the signature\n* `verb`: HTTP verb to embed into the signature, deafult `GET`\n* `scheme`: protocol of returned URL, default `https`\n\n#### `storage:upload_url(bucket, key, opts={})`\n\nGenerate a signed URL for browser-based upload.\n\nOptions:\n\n* `content_disposition`\n* `filename` If provided, will append to content disposition as `filename=` (and set content disposition to `attachment` if none is provided)\n* `acl` default `project-private`\n* `success_action_redirect`\n* `expires` unix timestamp. Deafult: 1 hour from now\n* `size_limit`\n* `scheme` protocol of returned URL, default `https`\n\n\n#### `storage:put_file_acl(bucket, key, acl)`\n\n\u003chttps://cloud.google.com/storage/docs/xml-api/put-object-acls\u003e\n\n## Changelog\n\n### Future updates\n\nAll future changelogs will be post on github release notes: https://github.com/leafo/cloud_storage/releases\n\n### `1.0.0` Mar 31, 2018\n\n* **Changed** `put_file_string` now takes `key` as second argument, instead of within options table\n* Replace `luacrypto` with `luaossl`\n* Add support for `json` private keys\n* Better error handling for all API calls. (Failures return `nil`, error message, and error object)\n* Add `copy_file` and `compose` methods\n* Add `upload_url` method to create upload URLs\n* Add `start_resumable_upload` method for creating resumable uploads\n* Headers are canonicalized and sorted to make them consistent between calls\n* Fix bug where special characters in key were not being URL encoded\n* Fix bug where some special characters were not being encoded for signed URLs\n* Rewrite documentation tutorial\n\n### `0.1.0` Sep 29, 2013\n\n* Initial release\n\n  [0]: https://developers.google.com/storage/docs/accesscontrol\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fleafo%2Fcloud_storage","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fleafo%2Fcloud_storage","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fleafo%2Fcloud_storage/lists"}