Type Casting in TypeScript

Ilya SherLeave a comment

( During code review, looking at TypeScript code. )

Colleague: … type casting …

Me: hold a sec, I don’t remember about anything called type casting in TypeScript

Colleague: you know, “as”

Me: yep, there is “as”, I just don’t think it was called type casting when I last re-read the official documentation a couple of months ago.

Colleague: hold a sec, here (shows me Google search results)

Search Results

My suspicion that something is off just grew when no result came from the official documentation.

TypeScript’s “as”

Clicked on few of this articles. They are talking about “as”. What does official TypeScript documentation tell us about “as”? It’s found under the heading Type Assertions. I didn’t see anything about type casting in the documentation.

Type Assertion vs Type Casting

Same thing, you are just showing off by being pedantic about naming!

Statistically probable response

What if I told you there is a practical difference between type assertion and type casting which confused my colleague?

Sometimes you will have information about the type of a value that TypeScript can’t know about… Like a type annotation, type assertions are removed by the compiler and won’t affect the runtime behavior of your code.

Official TypeScript documentation

You are letting TS know which type the value is. This information is used at compile time. Nothing happens at runtime. “cast” to the wrong object and no exception is thrown. That’s type assertion in TS.

In other languages casting has runtime implications.

Reality Check 1

Googled “type assertion vs casting typescript”. First result is What are the difference between these type assertion or casting methods in TypeScript (Stack Overflow). Oops. People are using “casting” all over, even on Stack Overflow… except that one comment at the end of the page:

(myStr as string) isn’t a cast, it’s a type assertion. So you are telling the compiler that even though it doesn’t know for sure that myStr is a string you know better and it should believe you. It doesn’t actually affect the object itself.

Duncan, Apr 13, 2018 at 14:26

… which is countered by

Coming from C# and since Typescript has many C# features, I’d say it is

user2347763, Apr 13, 2018 at 15:17

I’ll have to disagree on the grounds that cast expression in C# “At run time, … might throw an exception.”

Reality Check 2

… whether the underlying data representation is converted from one representation into another, or a given representation is merely reinterpreted as the representation of another data type …

https://en.wikipedia.org/wiki/Type_conversion

So, apparently, type assertion is a specific case of type casting.

Conclusion

I was wrong thinking that “type assertion” is not “type casting”. Apparently, it is. It’s just a specific case. The phrase “In other languages casting has runtime implications.” (that I wrote above) is apparently not correct in the general sense despite Java and C# popping up immediately.

What I’m still having hard time to understand is why those articles choose to use the generic wording. I think we should always strive for precise wording.

If you want to be part of search results, fine, I get it. What’s preventing you from “In TypeScript, type casting is implemented using type assertions (a special case of type casting) that only have compile time implications” (or something similar) though?

Takeaways

  • Always check official documentation (apparently it needs to be said for the 1000th time)
  • If you are posting an article, I recommend sticking to the wording in official documentation, especially when it’s more precise.

Can we make this article more precise? Let me know 🙂

Feedback Essentials

Ilya SherLeave a comment

This is a concise post, summarizing Manager Tools podcasts about feedback. Examples are mine, I couldn’t remember specific examples.

Manager Tools recommendations are based on data about what’s effective gathered from companies from different industries and of different sizes.

Purpose of Feedback

The only purpose of feedback is to encourage productive behavior and to discourage unproductive behavior in the future.

Why Give Feedback?

As a manager, you are measured by results and retention. Results are achievable through behaviors. Your job as a manager is to adjust the behaviors, mostly through feedback, in order to improve results.

Prerequisites

For a feedback to be effective, there must be established relationship. In a professional context, the way to establish and maintain a relationship between a manager and their directs are weekly one-on-one meetings (which deserve a separate post). Without established relationship, feedback will most likely be ineffective. After having one-on-ones for some time, you can start with positive feedback, then add negative.

Be calm when giving feedback. If you are angry, wait until you are calm to give feedback.

Frequency

Overwhelming majority of directs want more feedback. Therefore, the feedback must be short. If it’s not short, it won’t be frequent.

Length

One feedback instance should take 30-90 seconds. (Don’t remember the exact numbers but something close to this).

Timing

The more adjacent in time the feedback is to the discussed behavior, the more effective it is.

Positive to Negative Ratio

Positive feedback is when you encourage productive behavior. Negative feedback is when you discourage unproductive behavior.

Ideally, for 10 positive pieces of feedback there would be one negative piece.

What’s Worthy of Feedback?

Pretty much any behavior, positive or negative.

Note that the amorphous “culture” is just a set of accepted behaviors. Maintaining “culture” can only be done through continuous feedback (by managers on all levels) and can not be done by producing the famous “our culture” style documents alone.

Delivery

Deliver in private. In order of decreasing effectiveness, as for any other communication:

  • Face to face
  • Video conference
  • Voice call

Procedure and Content

Giving feedback consists of the following steps.

Ask

Ask if the recipient is ready: “Can I give you some feedback?”

Do not proceed with feedback if the answer is no. In general, don’t ask questions when the response is irrelevant.

Describe the Situation

Example: “yesterday during the meeting”.

Describe the Behavior

Example: “you were talking over other people “

Describe the Effect

Example: “it made the discussion less effective” (TODO: better phrasing)

Ask to do More or Less

Example: “please don’t talk over other people in future meetings”

This part is left out if the person you are talking to is not under your management. You can’t ask of more or less of a particular behavior in this case. You operate under assumption that the person was not aware of the effect of their behavior and providing the insight can help. If you omit this part, the conversation is not called feedback (according to this model) anymore.

Positive Example

– Can I give you some feedback?

– Sure

– You had deliverable X. You had delivered it on time and the quality met the expectations. This unblocked team Y on time and we are on schedule to finish the whole project, which is important for the client. Please continue delivering on time and to the expected quality.

– Good. Thanks!

Notes:

  • The feedback is about specific behaviors.
  • Schedule and quality of the deliverables are also behaviors.

Common Mistakes

Discussing Attitudes

Do not discuss attitudes, only behaviors. “You have a shitty attitude” is too amorphous and will cause “no, I don’t”. That’s an argument that you can’t possibly win. You should only give feedback about behaviors.

Root Cause Analysis

Don’t try to do root cause analysis with the direct. You are not well equipped to analyze what’s going on inside a head of another person.

More generally, don’t slip into digging into the past. The focus of feedback is future behavior.

Accumulating

Don’t wait for several instances of behavior to occur before giving feedback. Common mistake is to wait “to make sure we have a real issue here”.

Ignoring “Normal” Behavior

The excuse “this is the expected behavior of a person in this role” is invalid. Do give positive feedback for any behavior you want to continue in the future.

Asymmetric Delivery

Making positive and negative feedback items delivery asymmetrical is a mistake. They should be delivered in an identical manner except for the last section when you ask to do more or less of the behavior.

I intend to update this post for better phrasing and possibly more content (still keeping it concise).

Ideally, each point should have a link to the original podcast for deeper understanding. Hope I’ll get to do this some day.

AWS SDK pagination – disregard for Developer Experience

Ilya SherLeave a comment

According to Pagination using Async Iterators in modular AWS SDK for JavaScript, state of the art for pagination in AWS JS SDK is:

const client = new DynamoDBClient({}); 
const tableNames = [];
for await (const page of paginateListTables({ client }, {})) {
    // page contains a single paginated output.
    tableNames.push(...page.TableNames);
}

While having paginators is an improvement over previous atrocities like making the client code track the pagination state (through variously named next page fields of course), it’s still wrong.

Wouldn’t it make way more sense to have SDK where the developer doesn’t need to deal with pagination at all? Like this:

const client = new DynamoDBClient({}); 
const tableNames = [];
for await (const tableName of client.listTablesV2()) {
    tableNames.push(tableName);
}

… where pagination is hidden behind hypothetical listTablesV2(). Note that collecting into tableNames probably wouldn’t be necessary anymore, just do what you need with client.listTablesV2().

I’m thrilled to hear any justification for bothering developers with implementation detail such as pagination. Let me know.

If your justification is “… but that’s how API works” then you made a mental shortcut here. Why SDK should be one to one with API? Even AWS themselves think it shouldn’t. They even added the paginators abstraction. It’s just the wrong one.

If your justification is “there will be cases where you will want explicit control over pagination” – while it’s hard for me to imagine such use case, the solution would be to provide the low level API in addition.

If your justification involves how we got here and/or why it was easier for AWS to implement pagination this way – that’s not the justification I’m looking for. The answer to “daddy, what’s your job?” shouldn’t be “mostly working around AWS”.

Edit 2023-10-28: Clarification. In the proposed SDK, the pages should be fetched on demand so cost of API calls is not an argument for explicit pagination.

Nitpick: should probably be called tablesNames, not tableNames. These are names for different tables, not multiple names for the same table.

2023-10-30 Update (WIP, I’ll be editing)

The input for the update is the Reddit discussion.

The Reddit Discussion

The responses ranged from “I like the pagination” to “I think it’s a fair point – perhaps in the evolution of the sdks, nobody raised your exact question (which I think is valid) …”

Chi Ma (u/chigia001) had an insightful perspective. I assume he spent quite some time thinking about pagination as he is a maintainer of an SDK that also has pagination.

Clarification

The original post doesn’t mention but the thought about the current low level API was: “it might need to be exposed too for some reason which is not currently apparent to me”.

What I Missed

I didn’t pay much attention that we are talking about AsyncIter, not the finest part of JavaScript particularly convenient feature of JavaScript. ( to be continued )

My Opinion – Unchanged Part

The basic premise of this blog post stays the same. My code should not have to deal with pagination when I don’t want to. It’s just unergonomic boilerplate. Same way I usually don’t care about lower level things such as TCP, TLS, and serialization, I don’t want to care about how the items I need are batched.

I propose to

  • Focus on finding better solutions rather than on justifying what we have.
  • Use dissatisfaction as a driver for progress.

Update 2023-11-25: boto3 (AWS SDK for Python) does have a way to iterate over collection of items where pagination is handled behind the scenes. From my perspective, it proves the basic premise.

My Opinion – Changed Parts

From 99% sure that I have obvious and straightforward solution (listTablesV2 above) it changed to

  • It’s a meh solution
    • AsyncIter is not very friendly and according to Chi Ma, not very well known.
  • There are other solutions
  • The low level API with pagination should be exposed
  • It’s a tradeoff
  • Exposing several similar APIs might be confusing and presents a challenge for SDK developers.
  • I don’t see a good solution. Maybe custom lazy list type. More thought should be invested in finding a better solution.

( to be continued )

Have a nice and productive day … to the extent possible of course 🙂

Empty Arrays for Cleaner Code

Ilya SherLeave a comment

Background

Let’s look at the following piece of code (in an abstract programming language) :

if chairs {
  for chair in chairs {
    clean(chair)
  }
}

The Problem

It’s more code that we would like to have. What’s holding us back? chairs can be null, which is not an array (aka list), therefore requiring the wrapping if. Without that if, for can fail with an error because it won’t be able to iterate over chairs (when it’s null).

Side note: any time a variable can be of different types (in our case chairs can be an array or null), there will be some code to deal with this situation. Try to avoid these situations.

Solution

Decide on a code convention that says that absence of items is represented by an empty array, not null. Your code will become more uniform and you will get rid of the if. Then the code above becomes:

for chair in chairs {
  clean(chair)
}

Please note that this solution is a tradeoff. If memory usage is very important in the application, this might not be a good solution.

Hope this helps. Have a nice day!

Update 2023-07-13

Real code example:

const tags = describeImagesCommandOutput.Images[0].Tags ?? [];
console.log('tags', tags);
const newTags = tags.filter(tag => tag.Key && TAGS_TO_COPY.has(tag.Key));
console.log('newTags', newTags);

My advice above would eliminate the ?? [] part.

Naming in Software – Practical Guide

Ilya SherLeave a comment

The title of the post is the title of the book that I wanted to publish for quite some time now. While I was thinking about phrasing and gathering content, somebody else beat me to it with Naming Things: The Hardest Problem in Software Engineering. The main issue that I wanted to solve is now solved. Programmers don’t have an excuse for poor naming anymore.

In light of this event, I’ve decided to make small complementary post out of the materials that I have gathered and move on, focusing on Next Generation Shell.

Me and Naming

I have over 20 years of professional experience in programming. During that time, as many others, I’ve also noted the struggle when it comes to naming.

Here is a list of my accepted naming contributions to various projects.

  1. iterators – function shoes_in_my_size naming 2020-02-16, “The Rust Programming Language” book
  2. Constructors – Get_Contents() method is misnamed 2020-02-23, MS C++ Documentation
  3. Rename howMany() to countSelected() 2023-01, MDN
  4. nilJson naming issue in readme 2023-04, Otterize

Naming Things, the Book

I skimmed Tom’s book to understand how similar it was to what I was about to write. Quite close. If you are struggling with naming, go and read it.

There is some amount of fluff which I think my book would have less. Example: convincing people that naming is important while they are already reading the book.

Overall, I do recommend the book though.

Especially I recommend this book to AWS as an organization, I guess along with other books about code quality in general. AWS, your de-prioritization of code quality is staggering. I mean observable output here, not the stated “Insist on the Highest Standards”.

6.2.6 Use accurate parts of speech

Adding negative example from AWS:

https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/crpg-ref-responses.html

SUCCESS and FAILED are not the same part of speech.

7.2.3 Omit Metadata

Additional reason to exclude data type from the name is to avoid additional changes anywhere in the code except for the declaration.

elt in items

Is items a list here or a set? Probably not important, the code should work with either. On the other hand, changing data type from list to set in the following example will make the code incorrect:

elt in items_list

8.2.4 Use similar names for similar concepts

Adding negative example from AWS, which time after time fails to give consistent names across their APIs.

How do you limit number of results from an API? MaxResults, maxResults, MaxRecords, MaxItems, Limit, limit, … Details at AWS API pagination naming.

It looks like consistent naming is valued less than independence of teams and ability of teams to perform uncoordinated work.

8.2.5 Use consistent antonyms

Adding example.

When I’ve got to name Option type (represents a container that can hold a value or can be empty) in Next Generation Shell, I went with straightforward antonyms.

  • Box (super type)
  • EmptyBox
  • FullBox

Authors of other languages preferred other naming conventions:

Scala: Option, None, Some

Haskell: Maybe, Nothing, Just

Perspective

Information Loss

In my perspective, giving inadequate names is part of a larger issue – Information Loss. Each time you give a name, think which information is now in your head which will be helpful to the reader of the code. If you don’t phrase it concisely and precisely, information loss occurs between your head and the code you are working on. There are several common types of errors one can make:

  1. Don’t provide enough information. Causes the reader to investigate in order to recover the information.
  2. Provide wrong information. That’s the worst, it’s misleading the reader.
  3. Provide too much information. The reader then must sift through the information to get to the relevant parts.

API

Sometimes it’s useful to think of methods as an API. That’s why method names shouldn’t include implementation details (with rare exceptions when they are important to the caller). Think of methods’ names and parameters’ names as a short version of API specification.

Identifiers

Tom’s book deals with naming identifiers, such as functions, classes, variables, etc. One step before naming an identifier is the question whether there should be an identifier.

Avoid Naming

Sometimes, the additional cognitive load is not worth it.

# Bad
chairs = fetch_chairs()
sorted_chairs = chairs.sort()
# also, now have to use the longer identifier in the code below

# Good
chairs = fetch_chairs().sort()

Apply your judgement of course. If it’s a 20 step process, additional identifiers in the middle do contribute to understanding. You still probably don’t want an identifier for each and every step of the calculation.

Do Name – Magic Numbers

Avoid magic numbers through naming. Please ignore whether result is a good name 🙂

# Bad
if result == 126 { ... }

# Good
NOT_EXECUTABLE = 126; # Or better, part of an Enum

if result == NOT_EXECUTABLE { ... }

Do Name – Repetitive Code

If you notice code that repeats, with rare exceptions, you should refactor your code extracting that code to a function or a method with a name.

Several Identifiers

Sometimes a function, a method, or a class do several things. In this case, you might struggle to name it. In a perfect world, the solution to this is refactoring to appropriate pieces.

Test Your Naming

You just named something: a function, a method or a class. Is there a change around the code that would make the name wrong? What if you copy+paste the named piece of code to another project? Would you need to change the name?

# Bad
function start_yellow_cars(cars) { ... } # The function doesn't know or care about the color
yellow_cars = ...
start_yellow_cars(yellow_cars)

# The change that would highlight the wrong naming
# while keeping the code completely functional
function start_yellow_cars(cars) { ... }
my_cars = ...
start_yellow_cars(my_cars)


# Good
function start_cars(cars) { ... }
yellow_cars = ...
start_cars(yellow_cars)

Common Naming Mistakes Observed

  1. Naming a data structure with “JSON” in name.
  2. Argument vs Parameter

Tooling

I highly recommend using IDEs that “understand” the code enough to be able to refactor/rename (classes, methods, functions, parameters) as opposed to text editors which can not assist with renaming to the same extent.

Hope this helps. Happy naming!

gRPC + REST API on AWS

Ilya SherLeave a comment

Showing a setup of gRPC service which is also exposed as a REST API. It’s a setup that happens to work for us. No alternatives will be discussed in this post.

This is a concise blog post.

Architecture

  1. ALB with HTTPS listener (trivially configured, out of scope of this post)
  2. ECS running a task with 3 containers:
    • API Gateway. Implemented by Envoy. does:
      • requests authorization using the service in next container
      • proxies gRPC requests
      • proxies REST requests (converting them to upstream gRPC requests).
    • authorization service implemented with OPA
    • Our gRPC application

Notes

Health checks are not in very good shape yet

ECS Configuration (Simplified Excerpt)

In case the reader is not familiar, it CloudFormation below.

  TaskDefinition:
    Type: AWS::ECS::TaskDefinition
    Properties:
      ContainerDefinitions:
        - Name: apigw
          Image: !Ref ApiGwImage
          PortMappings:
            - ContainerPort: !Ref ContainerPort
        - Name: opa
          Image: !Ref OpaImage
          PortMappings:
            - ContainerPort: 9191
        - Name: app
          Image: !Ref AppImage
          PortMappings:
            - ContainerPort: 4000

  Service:
    DependsOn:
      - GrpcListenerRule
      - RestListenerRule
      - GrpcTargetGroup
      - RestTargetGroup
    Type: AWS::ECS::Service
    Properties:
      ServiceName: !Ref ServiceName
      Cluster: !Ref Cluster
      TaskDefinition: !Ref TaskDefinition
      LoadBalancers:
        - ContainerName: apigw
          ContainerPort: !Ref ContainerPort
          TargetGroupArn: !Ref GrpcTargetGroup
        - ContainerName: apigw
          ContainerPort: !Ref ContainerPort
          TargetGroupArn: !Ref RestTargetGroup

  GrpcTargetGroup:
    Type: AWS::ElasticLoadBalancingV2::TargetGroup
    Properties:
      HealthCheckIntervalSeconds: 10
      HealthCheckPath: /
      HealthCheckTimeoutSeconds: 5
      Matcher:
        GrpcCode: "0-99"
      UnhealthyThresholdCount: 2
      HealthyThresholdCount: 2
      Port: !Ref ContainerPort
      Protocol: HTTP
      ProtocolVersion: GRPC
      TargetGroupAttributes:
        - Key: deregistration_delay.timeout_seconds
          Value: 60 # default is 300
      TargetType: ip
      VpcId: !ImportValue VpcId

  RestTargetGroup:
    Type: AWS::ElasticLoadBalancingV2::TargetGroup
    Properties:
      HealthCheckIntervalSeconds: 10
      HealthCheckPath: /rest/not-found
      HealthCheckTimeoutSeconds: 5
      Matcher:
        HttpCode: 404
      UnhealthyThresholdCount: 2
      HealthyThresholdCount: 2
      Port: !Ref ContainerPort
      Protocol: HTTP
      ProtocolVersion: HTTP1
      TargetGroupAttributes:
        - Key: deregistration_delay.timeout_seconds
          Value: 60 # default is 300
      TargetType: ip
      VpcId: !ImportValue VpcId

  GrpcListenerRule:
    Type: AWS::ElasticLoadBalancingV2::ListenerRule
    Properties:
      Actions:
        - Type: forward
          TargetGroupArn: !Ref GrpcTargetGroup
      Conditions:
        - Field: path-pattern
          PathPatternConfig:
            Values:
              - '/censored.v1.CensoredService/*'
              - '/censored.v1.CensoredAdminService/*'
              - '/censored.v1.CensoredSystemService/*'
      ListenerArn: ...
      Priority: 1000

  RestListenerRule:
    Type: AWS::ElasticLoadBalancingV2::ListenerRule
    Properties:
      Actions:
        - Type: forward
          TargetGroupArn: !Ref RestTargetGroup
      Conditions:
        - Field: path-pattern
          PathPatternConfig:
            Values:
              - '/rest/v1/*'
      ListenerArn: ...
      Priority: 1001

Envoy Configuration (Simplified Excerpt)

static_resources:
  listeners:
    - address:
        socket_address:
          address: 0.0.0.0
          port_value: 8000
      filter_chains:
        - filters:
            - name: Connection Manager
              typed_config:
                "@type": type.googleapis.com/envoy.extensions.filters.network.http_connection_manager.v3.HttpConnectionManager
                via: CensoredGW
                route_config:
                  name: Static response for tests
                  virtual_hosts:
                    - name: backend
                      domains:
                        - "*"
                      routes:
                        - match:
                            prefix: "/test/static"
                          direct_response:
                            status: 200
                            body:
                              inline_string: "Static response for tests"
                        # Reference: https://envoyproxy.io/docs/envoy/latest/configuration/http/http_filters/grpc_json_transcoder_filter#route-configs-for-transcoded-requests
                        - match:
                            prefix: "/"
                          route:
                            cluster: upstream
                            timeout: 60s
                http_filters:
                  - name: envoy.filters.http.grpc_json_transcoder
                    typed_config:
                      "@type": type.googleapis.com/envoy.extensions.filters.http.grpc_json_transcoder.v3.GrpcJsonTranscoder
                      # maybe disable later:
                      auto_mapping: true
                      proto_descriptor: "../path/to/proto_descriptor.bin" ### See next heading in this post
                      services:
                        - censored.v1.CensoredService
                        - censored.v1.CensoredAdminService
                        - censored.v1.CensoredSystemService
                      print_options:
                        add_whitespace: true
                        always_print_primitive_fields: true
                      request_validation_options:
                        reject_unknown_method: true
                        reject_unknown_query_parameters: true
                  - name: envoy.filters.http.cors
                    typed_config:
                      "@type": type.googleapis.com/envoy.extensions.filters.http.cors.v3.Cors
                  - name: envoy.ext_authz
                    typed_config:
                      "@type": type.googleapis.com/envoy.extensions.filters.http.ext_authz.v3.ExtAuthz
                      failure_mode_allow: false
                      with_request_body:
                        max_request_bytes: 10485760 # 10M
                        allow_partial_message: false
                        pack_as_bytes: true
                      transport_api_version: V3
                      grpc_service:
                        envoy_grpc:
                          cluster_name: opa-agent
                        timeout: 10s
                  - name: envoy.filters.http.router
                    # https://github.com/envoyproxy/envoy/issues/21464
                    typed_config:
                      "@type": type.googleapis.com/envoy.extensions.filters.http.router.v3.Router
                always_set_request_id_in_response: true
                access_log:
                  - typed_config:
                      "@type": type.googleapis.com/envoy.extensions.access_loggers.stream.v3.StdoutAccessLog
                      # https://www.envoyproxy.io/docs/envoy/latest/configuration/observability/access_log/usage#config-access-log-default-format

  # Based on https://www.envoyproxy.io/docs/envoy/latest/configuration/http/http_filters/grpc_json_transcoder_filter
  clusters:
    - name: opa-agent
      connect_timeout: 0.25s
      type: STRICT_DNS
      typed_extension_protocol_options:
        envoy.extensions.upstreams.http.v3.HttpProtocolOptions:
          "@type": type.googleapis.com/envoy.extensions.upstreams.http.v3.HttpProtocolOptions
          explicit_http_config:
            http2_protocol_options: { }
      lb_policy: ROUND_ROBIN
      load_assignment:
        cluster_name: service
        endpoints:
          - lb_endpoints:
              - endpoint:
                  address:
                    socket_address:
                      address: 127.0.0.1
                      port_value: 9191
    - name: upstream
      type: STRICT_DNS
      typed_extension_protocol_options:
        envoy.extensions.upstreams.http.v3.HttpProtocolOptions:
          "@type": type.googleapis.com/envoy.extensions.upstreams.http.v3.HttpProtocolOptions
          explicit_http_config:
            http2_protocol_options: {}
      load_assignment:
        cluster_name: grpc
        endpoints:
          - lb_endpoints:
              - endpoint:
                  address:
                    socket_address:
                      address: 127.0.0.1
                      port_value: 4000

proto_descriptor.bin

GrpcJsonTranscoder must have the proto descriptor file in order to know how to transcode. The file contains:

  1. proto definitions of your services, including extension that describes how to expose the services as REST
  2. dependencies of the above proto definitions

The descriptor file is generated using a command similar to the following:

buf build -o proto_descriptor.bin --as-file-descriptor-set --path path/to/my.proto

buf is a way to manage .proto files and their dependencies (very imprecise definition, sorry)

If I remember correctly, you can generate the descriptor with protoc (without buf) but I don’t remember how.

grpcurl

Same descriptor file is used with grpcurl when you later test your service from the command line:

grpcurl -H "Authorization: Bearer ..." -protoset proto_descriptor.bin "example.com:443" censored.service.name/MyFunc

my.proto

This is how a protobuf definition with REST extension looks like (excerpt):

import "google/api/annotations.proto";

service Censored {
  rpc MyCreate(CreateRequest) returns (CreateResponse){
    option (google.api.http) = { post: "/rest/v1/my-objs" };
  }
  rpc MyGet(GetRequest) returns (GetResponse) {
    option (google.api.http) = { get: "/rest/v1/my-objs/{id}" };
  }
}

Excerpt from buf.yaml corresponding to the import above:

version: v1

deps:
  - buf.build/googleapis/googleapis

Hope this helps.

Sorry, I was in a rush to get this out. If anything is unclear or missing, please let me know.

The Case for Concise Posts

Ilya SherLeave a comment

According to DiSC, about a quarter of all people should be communicating like me. We want information, not fluff or stories. We are here to get the answer to our question: “what’s X?” (a technology, a format, a piece of software, etc). Yet, the number of blog posts which answer “What’s X?” concisely is roughly zero. I am going to fix this with my future posts as time allows. Stay tuned.

Everything below is implementation detail. You can stop reading here and save a few minutes.

Here is my plan. Feel free to use it as a guideline for your blog posts too.

Discretion

We are looking for the author’s discretion about what’s important (hint: typically concepts and architecture), not a dump of everything that the author knows about the topic. We are here for “I would have written a shorter letter, but I did not have the time“. Yes, that 5 minutes read should take hours if not days to write. Otherwise, what’s the value?

Can’t answer the question concisely? We doubt your understanding of the topic.

Context

“Context is important, the blog post must provide context, blah blah …”.

The context was already established by searching “what’s X” or following a link to the post. It’s annoying when the text starts with fluff, keeping us wondering when and whether my question will be answered.

If there is some *really* important context, that’s not 5 paragraphs. Sorry, storytellers.

Show why the Topic is Important

“You need to show why X is important and where it’s used”.

This information is available in every other blog post and/or on Wikipedia and/or is one search away.

Underlying Concepts

Don’t explain the underlying concepts, link to them (like DiSC above). Don’t waste our time if we already know that.

Stay tuned.

Event Loop for Beginners

Ilya SherLeave a comment

The aim of the post is to give a simple, concise, and high level description of the event loop. I’m intentionally leaving out many details and being somewhat imprecise.

If you need detailed picture, follow the links in this post. In this case, I recommend reading this short post first.

Why Event Loop?

To deal with concurrency (multiple “things” need to be happening at what looks like the same time), there are few models. To discuss the models, we need to know what a thread is.

Roughly, a thread is a sequence of computing instructions that runs on a single CPU core.

Roughly, Event Loop manages on which tasks the thread works and in which order.

Queue

The queue contains what’s called in different sources messages, events, and tasks.

Message/event/task is a reference to a piece of code that needs to be scheduled to run. Example: “the code responsible for handling the click of button B + full details of the click event to pass to the code”.

Event Loop

  1. The queue is checked for new tasks. If there is none, we wait for one to appear.
  2. The first task in the queue is scheduled and starts running. The code runs till completion. In many languages, await keyword in the code counts as completion and everything after await is scheduled to run later – new task in the queue.
  3. Repeat from number 1. That’s the loop. It’s called Event Loop because it processes events from the queue in a loop.

Adding Events to the Queue

Tasks are added to the queue for two reasons:

  1. Something happened (user clicked on a button, network packet arrived, etc).
  2. The code that was running in step 2 of the event loop scheduled something to run later.

See Also

  1. Event Loop documentation at MDN.
  2. What is the difference between concurrency and parallelism? at StackOverflow

Hope this helps with high level understanding of Event Loop. Have a nice day!

AWS CDK Opinionated Pipeline – Where is What?

Ilya SherLeave a comment

Background

You use AWS CDK. It’s great. It does a lot for you. Then one day something goes wrong. OK, it didn’t happen yet. But you want to be prepared for that (at least to some extent). The following information is what I have found when I was preparing. Sharing to hopefully save the reader some time.

Basics

Before we dive in, let’s just make sure we’ve got the basics covered

cdk ls

cdk ls lists all the stacks in the app, including the pipeline.

Example from my test project:

$ cdk ls
Proj1Stack
Proj1Stack/Deploy1/LambdaStack1
Proj1Stack/Deploy2/LambdaStack1
  • Proj1Stack is the pipeline.
  • Deploy1 and Deploy2 are “stages”

cdk synth

cdk synth $STACK_NAME >1.yaml is your friend, a debugging tool. It shows the generated CloudFormation.

cdk.out directory

cdk.out is the directory where cdk synth outputs everything that’s need for deploying (CloudFormation templates, related assets, metadata). They call it Cloud Assembly.

All assets are named based on the hash of their content so they are unique and immutable.

How the Generated Pipeline Looks Like?

When you use an opinionated pipeline, you can see the following generated CodePipeline actions:

  • Source (with long hash as output artifact name)
  • Build with name Synth (a CodeBuild project that runs cdk synth)
  • Build with name SelfMutate (a CodeBuild project that runs cdk deploy to update the pipeline)
  • Build with name FileAsset1 (a CodeBuild project that runs cdk-assets publish). From reading sources: there might be several cdk-assets publish commands configured in the CodeBuild project.
  • Then two CloudFormation deploy actions per each “stage” you want to deploy to (usage of change sets is the default but can be disabled as per documentation, see useChangeSets):
    • CHANGE_SET_REPLACE
    • CHANGE_SET_EXECUTE

cdk-assets

“It will take the assets listed in the manifest, prepare them as required and upload them to the locations indicated in the manifest.”

Note that cdk-assets is not making any decisions; metadata in the cdk.out directory has the information about assets, how to build/transform them and where they go.

cdk-assets can only handle two types of assets:

  • files (including directories). cdk-assets knows how to zip directories and how to upload files and directories to S3.

    (From reading source code) Didn’t see in use but apparently cdk-assets can also run an executable to package a file (or directory?). In this case the content-type of the output is assumed to be application/zip. 🤷‍♂️
  • Docker images. cdk-assets knows how to build Docker images and push them into registry.

Sample command to see the list of assets: npx cdk-assets ls -p cdk.out/Proj1Stack.assets.json

What is Built When?

Files – unprocessed

If the files/directories don’t need any processing, they are just copied over to cdk.out during cdk synth and given a name which is a hash of the contents.

Example: Lambda function code

Files – processed

The processing happens during the cdk synth so that cdk.out contains already processed assets.

Example: Node.JS Lambda function code (processed by tsc (optionally) and esbuild)

Docker Images

cdk-assets builds a docker image and pushes it into the specified repository. The input for the build of the image is a directory in cdk.out which has the Dockerfile and related files.

Deploy

After everything was built and uploaded during cdk synth and cdk-assets, the deploy uses CloudFormation template (templates?) from the cdk.out directory. At this point the assets (which the template references) are in ECR and S3.

  • I tried to condense the information that deemed important.
  • Let me know if something is missing or if you see mistakes.
  • The plan is to update this post as I discover new information.
  • My mistakes so far
    • Started taking notes quite a few hours into the process instead of from the start. Especially it would save me the jumping between the pipeline and the build projects to re-check what each action does.
    • Editing this post tired
  • Last edit: 2023-01-20

AWS CDK – Proposed Slogans

Ilya SherLeave a comment

Below, despite the humor, is my honest praise to the AWS CDK team and the product.

  1. Finally bringing code into “infrastructure as code”
    (sorry Puppet, Ansible, CloudFormation, SAM, Terraform)
  2. The only team at AWS that actually cares about your experience
  3. Suffer much less
  4. No more dealing with IAM policies anymore*
    * almost
  5. Did you know that CodePipeline actually requires an S3 bucket to work?
  6. CloudFormation? Ye, nice intermediate representation, you know, like assembler with macros.
  7. Making interaction with AWS bearable
    (I would say “again” but it never was)
  8. So right on so many levels
  9. Cloud – it doesn’t have to be ugly
  10. CDK – Cool Developers Know
  11. Isolating you from the ugly
  12. We ate the shit so you wouldn’t have to*
    * mostly
  13. Don’t Look Up^W at the generated CloudFormation

Have a nice day!