aws / aws/jsii

Ruby Language Support for jsii

Open
#5,129 9 comments 1 reaction 0 assignees View on GitHub
feature-request p2
Dominant language
TypeScript
Stars
2.9k
Forks
267
Avg merge
1d 25m
Merged PRs (30d)
14

Description

### Describe the feature

This issue tracks **Ruby language support in the `jsii` monorepo** — the runtime (`@jsii/ruby-runtime`), the `jsii-pacmak` Ruby target, and the compliance suite.

> **Umbrella tracking:** the cross-repo Ruby effort (compiler, rosetta, docgen, aws-cdk) and the RFC itself are coordinated in the RFC tracking issue **[aws/aws-cdk-rfcs#935](https://github.com/aws/aws-cdk-rfcs/issues/935)**. This issue is scoped to the jsii monorepo and actively tracks its PR.

### 🚀 Implementation Progress & Status

| Package / Repository | Status | PR / Link | Description |
| --- | --- | --- | --- |
| **`aws/jsii` (monorepo)** | Submitted (draft) | [aws/jsii#5178](https://github.com/aws/jsii/pull/5178) | Ruby runtime core (`@jsii/ruby-runtime`), tests (`@jsii/ruby-runtime-test`), and the `jsii-pacmak` Ruby target. |
| **`aws/jsii-compiler`** (dependency) | Submitted | [aws/jsii-compiler#2663](https://github.com/aws/jsii-compiler/pull/2663) | Ruby `targets.ruby` metadata schema validation. |

### Key Technical Architecture Details

1. **Ruby-to-Kernel IPC Proxy (`@jsii/ruby-runtime`)**:
Built a robust IPC client that communicates with the `jsii` Node.js kernel. The bidirectional JSON IPC uses a re-entrant `Monitor` for thread safety, safely draining stderr and handling async nested callbacks.
2. **Type Validation & Coercion**:
Strict runtime type validation and coercion for primitives (including date/boolean parsing), collections, structs, and dynamic unions.
3. **Dynamic Proxying (`method_missing`)**:
Instance methods follow Ruby standard `snake_case` (e.g. `bucket_name`, `grant_read_write_data`), which are proxy-forwarded to JavaScript's `camelCase` counterpart.
4. **Interface & Inheritance Support**:
Supports implementing and overriding JSII interfaces and abstract classes natively in Ruby, including async method overrides.
5. **Namespacing & Acronyms**:
Module names follow PascalCase (`AWSCDK::AWSS3::Bucket`). Acronyms are PascalCased correctly (e.g. `APIGateway`, `RestAPI`, `CloudFront`, `CertificateManager`, `DynamoDB`) across compile time and code generation.
6. **Code Translation (`jsii-rosetta`)**:
Translates TypeScript examples into valid and idiomatic Ruby code snippets.

### Use Case Example

Here is a preview of the syntax of a real stack that compiles, translates, and deploys using our Ruby bindings:

```ruby
require 'aws-cdk-lib'

class BlogStack < AWSCDK::Stack
DOMAIN = 'omarqureshi.net'

def initialize(scope, id, props = nil)
super(scope, id, props)

@site_bucket = AWSCDK::S3::Bucket.new(
self,
'SiteBucket',
{
bucket_name: DOMAIN,
website_index_document: 'index.html',
public_read_access: true,
removal_policy: AWSCDK::RemovalPolicy::DESTROY
}
)

@certificate = AWSCDK::CertificateManager::Certificate.new(
self,
'SiteCertificate',
{
domain_name: DOMAIN,
validation: AWSCDK::CertificateManager::CertificateValidation.from_dns(load_zone)
}
)
end

private

def load_zone
AWSCDK::Route53::HostedZone.from_lookup(
self,
'HostedZone',
{ domain_name: DOMAIN }
)
end
end
```

### Additional References
- **RFC**: https://github.com/omarqureshi/aws-cdk-rfcs/blob/112e8691e482c53d9de54ccd499a98d76d5eeb47/text/0935-ruby-language-bindings.md - https://github.com/aws/aws-cdk-rfcs/issues/935
- **Demo Repository**: https://github.com/omarqureshi/blog (where live deployments using the generated gems have been validated)

### Acknowledgements

- [x] I may be able to implement this feature request
- [ ] This feature might incur a breaking change

### CDK version used

2.1124.1 (build 791408c)

### Environment details (OS name and version, etc.)

Ubuntu 24.04.1 LTS (WSL2), ruby 3.2.3 (2024-01-18 revision 52bb2ac0a6) [x86_64-linux-gnu], node v24.15.0
macOS Tahoe, ruby 3.3/3.2, node v22

Contributor guide

Open the contributing guide

Research direction

Start by reading the draft implementation in aws/jsii#5178, especially @jsii/ruby-runtime, @jsii/ruby-runtime-test, and the jsii-pacmak Ruby target. Check the linked compiler PR #2663 and the compliance-suite coverage; done means the listed runtime, code-generation, metadata, and test pieces are complete and coordinated with the RFC.

Written by the indexing model from the issue text.

Assessment

Tech stack
node.js, ruby, typescript
Domain
compilers, developer-experience, tooling
Issue type
Feature
Difficulty
5/5
Estimated time
Over a week
Activity status
Stale
Clarity
Needs clarification
Newbie friendliness
15/100

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.