Estimated reading time: 4 minutes

• Có sẵn từ C# 15 / .NET 11 Preview 2.

• Docs: https://learn.microsoft.com/en-us/dotnet/csharp/language-reference/builtin-types/union#union-implementation

• Proposal: https://github.com/dotnet/csharplang/blob/main/proposals/unions.md

⚠️ Disclaimer — Preview feature

• Yêu cầu C# 15 / .NET 11 Preview 2 trở lên.
• Tính đến .NET 11 Preview 2, UnionAttribute và IUnion chưa được include trong runtime. Muốn dùng phải tự khai báo trong project (xem mục Union implementation trong docs).
• Đây là preview — API và behavior có thể thay đổi trước khi ship chính thức.

💠 1. Bản chất

• Union types trong C# là union of types thông qua một wrapper type.

• Nó là type union — KHÔNG phải tagged union hay discriminated union theo nghĩa truyền thống. Trích trực tiếp từ proposal:

  "The proposed unions in C# are unions of types and not 'discriminated' or 'tagged'."

  Sự khác biệt:

  • Discriminated union (F#, Haskell): dùng một trường discriminator/tag riêng biệt để phân biệt case.
  • Type union trong C#: dùng chính runtime type của Value làm discriminator — không có trường tag riêng.
  • Về hành vi, nó tương tự discriminated union ở chỗ pattern matching có thể biết chính xác đang ở case nào, nhưng về cơ chế lưu trữ thì khác.

• Nó vẫn đại diện cho ngữ nghĩa "HOẶC" giữa các type, nhưng bản chất của nó là một cái hộp chứa type cần "hoặc" ở bên trong.

Ví dụ, ta dùng Union declaration syntax:

// Union of existing types
public union Pet(Cat, Dog);

Được lowered thành:

[Union] public struct Pet : IUnion
{
    public Pet(Cat value) => Value = value;
    public Pet(Dog value) => Value = value;
    public object? Value { get; }
    ... // original body
}

Ta thấy rõ:

• Pet chỉ là một cái hộp, hoặc chứa Cat, hoặc chứa Dog
• Pet được gọi là union type
• Cat và Dog được gọi là case types

Compiler sẽ đảm bảo exhaustiveness khi dùng Union type với pattern matching.

💠 2. Hành vi (union behaviors)

💠 2.1. Union conversions

Có implicit conversion từ mỗi case type sang union type:

Pet pet = dog;
// becomes
Pet pet = new Pet(dog);

💠 2.2. Union matching

💠 2.2.1. Apply vào Value bên trong

• Khi kiểu dữ liệu của một value là union type tại compile time, thì pattern matching sẽ được áp dụng lên Value bên trong union type một cách ngầm định.

  Nghĩa là nó sẽ bị unwrap ngầm định thông qua .Value, rồi apply pattern lên Value đó (ngoại trừ trường hợp dùng var hoặc _).

Ví dụ:

Pet GetPet() => new Dog(...);

var description = GetPet() switch
{
    Dog dog => $"A dog: {dog.name}",
    Cat cat => $"A cat: {cat.name}",
    // No warning about non-exhaustive switch
};

Được lowered thành:

GetPet().Value switch {
    ...
}

Vì compiler biết Pet là một union type, nên nó sẽ biết switch expression ở trên đã được exhaustive rồi.

💠 2.2.2. Ngoại lệ var / _

Ngoại lệ là var hoặc _ pattern. Khi đó, pattern sẽ được apply vào chính Pet value, chứ không phải Value của Pet.

if (GetPet() is var pet) { ... } // 'pet' is the union value returned from `GetPet`

💠 2.2.3. Check null

Khi check 1 biến kiểu nullable union type là null hay không, thì việc check null không chỉ apply cho union type value, mà cả Value bên trong union type. (Điều này vẫn tuân thủ Union behavior ở trên - khi compile-time type là union type)

Pet? pet = ...;
pet is null

Được lowered thành:

Pet? pet = ...;

// Nếu Pet là class union type
pet == null || pet.Value == null

// Nếu Pet là struct union type
pet.HasValue == false || pet.GetValueOrDefault().Value == null

💠 2.2.4. Cạm bẫy

Pet pet = ...;
pet is Pet

Nó gần như luôn eval thành false, vì nó bị lowered thành:

pet.Value is Pet

Trong khi Value luôn là Dog hoặc Cat 😂.

💠 3. Một chỗ rất dễ gây nhầm lẫn: compile-time type đổi thì meaning cũng đổi

Nếu GetPet() trả về kiểu object, thì câu chuyện đổi hẳn.

object GetPet() => new Dog(...);

GetPet() is Pet;

• Khi đó, GetPet() is Pet sẽ eval thành true nếu GetPet() trả về một instance của Pet.

  • Lúc này, union behavior sẽ không được áp dụng, vì compile-time type của giá trị đầu vào là object, không phải Pet.
  • Do đó, GetPet() is Pet sẽ là true theo nghĩa check type bình thường ở runtime.

• Lý do là thiết kế hiện tại chỉ bật union matching khi compile-time type của giá trị đầu vào đã là union type. Ngoài trường hợp đó, union chỉ là một type bình thường / value bình thường, không có unwrap .Value ngầm.

• Đây là giải thích trực tiếp từ thảo luận của proposal: https://github.com/dotnet/csharplang/discussions/10040

💠 4. Mental model

Pet GetPet()      ->  GetPet() is Pet   // union semantics
object GetPet()   ->  GetPet() is Pet   // normal runtime type check

Tức là cùng một cú pháp is Pet, nhưng chỉ cần đổi compile-time type của biểu thức bên trái là meaning sẽ đổi theo.

Đây chính là lý do nhiều người chê proposal này "không idempotent" và dễ gây lú. Trong discussion https://github.com/dotnet/csharplang/discussions/10040 cũng nêu khá rõ rằng union pattern matching chỉ hoạt động khi compile-time type là union type.

💠 5. Tổng hợp — snippet dễ nhớ

// ✅ Union declaration syntax (C# 15 / .NET 11 Preview 2+)
public union Result<T>(T, Exception);

// ✅ Implicit conversion từ case type → union type
Result<int> ok    = 42;
Result<int> fail  = new Exception("oops");

// ✅ Pattern matching — exhaustive, không cần fallback
string msg = ok switch
{
    int value    => $"Success: {value}",
    Exception ex => $"Error: {ex.Message}",
    // No warning — compiler biết đã exhaustive
};

// ✅ null check unwrap cả hai tầng

// (union declaration → struct → Result<int>? is Nullable<Result<int>>)
Result<int>? maybe = ...;

// lowered: maybe.HasValue == false || maybe.GetValueOrDefault().Value == null
if (maybe is null) { }

// ⚠️ Cạm bẫy: luôn false vì bị unwrap ngầm
Result<int> r = ...;
r is Result<int>                                // → r.Value is Result<int> → false!

// ⚠️ Compile-time type quyết định behavior
Result<int>  r2 = ...;  r2 is int               // union semantics ✅
object       r3 = ...;  r3 is Result<int>       // runtime type check thường ⚠️

Estimated reading time: 4 minutes

• Available from C# 15 / .NET 11 Preview 2.

• Docs: https://learn.microsoft.com/en-us/dotnet/csharp/language-reference/builtin-types/union#union-implementation

• Proposal: https://github.com/dotnet/csharplang/blob/main/proposals/unions.md

⚠️ Disclaimer — Preview feature

• Requires C# 15 / .NET 11 Preview 2 or later.
• As of .NET 11 Preview 2, UnionAttribute and IUnion are not yet included in the runtime. You must declare them manually in your project (see Union implementation in the docs).
• This is a preview — APIs and behaviors may change before the final release.

💠 1. What is a Union Type?

• A union type in C# is a union of types via a wrapper type.

• It is a type union — NOT a tagged union or discriminated union in the traditional sense. Quoted directly from the proposal:

  "The proposed unions in C# are unions of types and not 'discriminated' or 'tagged'."

  The distinction:

  • Discriminated union (F#, Haskell): uses a dedicated discriminator/tag field to tell cases apart.
  • Type union in C#: uses the runtime type of Value itself as the discriminator — no separate tag field.
  • In terms of behavior, it resembles a discriminated union in that pattern matching can identify the exact case, but the storage mechanism is different.

• It still expresses the "OR" semantics between types, but its underlying form is a box that holds one of the possible types.

For example, using the Union declaration syntax:

// Union of existing types
public union Pet(Cat, Dog);

Is lowered to:

[Union] public struct Pet : IUnion
{
    public Pet(Cat value) => Value = value;
    public Pet(Dog value) => Value = value;
    public object? Value { get; }
    ... // original body
}

Clearly:

• Pet is just a box that holds either a Cat or a Dog
• Pet is called the union type
• Cat and Dog are called case types

The compiler guarantees exhaustiveness when using a union type with pattern matching.

💠 2. Union Behaviors

💠 2.1. Union Conversions

There is an implicit conversion from each case type to the union type:

Pet pet = dog;
// becomes
Pet pet = new Pet(dog);

💠 2.2. Union Matching

💠 2.2.1. Applied to the Inner Value

• When the compile-time type of a value is a union type, pattern matching is implicitly applied to the Value inside the union type.

  In other words, the union is implicitly unwrapped via .Value, and the pattern is applied to that Value (except when using var or _).

Example:

Pet GetPet() => new Dog(...);

var description = GetPet() switch
{
    Dog dog => $"A dog: {dog.name}",
    Cat cat => $"A cat: {cat.name}",
    // No warning about non-exhaustive switch
};

Is lowered to:

GetPet().Value switch {
    ...
}

Because the compiler knows Pet is a union type, it knows the switch expression above is already exhaustive.

💠 2.2.2. Exception: var / _

The var or _ patterns are exceptions. In these cases, the pattern is applied to the Pet value itself, not its Value.

if (GetPet() is var pet) { ... } // 'pet' is the union value returned from `GetPet`

💠 2.2.3. Null Checking

When checking whether a nullable union type variable is null, the null check applies not only to the union value itself but also to the Value inside it. (This still follows the Union behavior above — when the compile-time type is a union type.)

Pet? pet = ...;
pet is null

Is lowered to:

Pet? pet = ...;

// If Pet is a class union type
pet == null || pet.Value == null

// If Pet is a struct union type
pet.HasValue == false || pet.GetValueOrDefault().Value == null

💠 2.2.4. The Trap

Pet pet = ...;
pet is Pet

This almost always evaluates to false, because it is lowered to:

pet.Value is Pet

While Value is always Dog or Cat 😂.

💠 3. A Common Source of Confusion: Changing the Compile-Time Type Changes the Meaning

If GetPet() returns object, the story changes entirely.

object GetPet() => new Dog(...);

GetPet() is Pet;

• Here, GetPet() is Pet evaluates to true if GetPet() returns an instance of Pet.

  • Union behavior is not applied, because the compile-time type of the input is object, not Pet.
  • Therefore, GetPet() is Pet is true in the sense of a normal runtime type check.

• The reason is that the current design only activates union matching when the compile-time type of the input is already a union type. Outside of that case, a union is just a regular type / regular value — no implicit .Value unwrapping.

• This is explained directly in the proposal discussion: https://github.com/dotnet/csharplang/discussions/10040

💠 4. Mental Model

Pet GetPet()      ->  GetPet() is Pet   // union semantics
object GetPet()   ->  GetPet() is Pet   // normal runtime type check

The same syntax is Pet, but simply changing the compile-time type of the left-hand expression changes the meaning entirely.

This is exactly why many people criticize this proposal as "not idempotent" and easy to get confused by. The discussion at https://github.com/dotnet/csharplang/discussions/10040 also makes it clear that union pattern matching only activates when the compile-time type is a union type.

💠 5. Summary — Quick Reference Snippet

// ✅ Union declaration syntax (C# 15 / .NET 11 Preview 2+)
public union Result<T>(T, Exception);

// ✅ Implicit conversion from case type → union type
Result<int> ok    = 42;
Result<int> fail  = new Exception("oops");

// ✅ Pattern matching — exhaustive, no fallback needed
string msg = ok switch
{
    int value    => $"Success: {value}",
    Exception ex => $"Error: {ex.Message}",
    // No warning — compiler knows all cases are covered
};

// ✅ Null check unwraps both layers
// (union declaration → struct → Result<int>? is Nullable<Result<int>>)
Result<int>? maybe = ...;
// lowered: maybe.HasValue == false || maybe.GetValueOrDefault().Value == null
if (maybe is null) { }

// ⚠️ Trap: always false due to implicit unwrapping
Result<int> r = ...;
r is Result<int>                            // → r.Value is Result<int> → false!

// ⚠️ Compile-time type determines behavior
Result<int>  r2 = ...;  r2 is int           // union semantics ✅
object       r3 = ...;  r3 is Result<int>   // normal runtime type check ⚠️

Author: Petrus Nguyễn Thái Học

• Tags: #kotlin, #grouping, #groupingBy, #groupBy, #reduce, #lazy-evaluation, #functional-programming, #hoc081098, #rx_mobile_team, #kotlindev #androiddev
• Source code: https://github.com/hoc081098/hoc081098/blob/master/notes/grouping_in_kotlin_vi_VN.kt

Đặt vấn đề

Giả sử chúng ta có một bài toán nhỏ như sau:

• Input: cho danh sách các sinh viên, mỗi sinh viên có các thuộc tính như sau

  • id: mã sinh viên.
  • name: tên sinh viên.
  • classId: mã lớp.
  • avgScore: điểm trung bình.

• Output: cho biết sinh viên có điểm trung bình cao nhất của mỗi lớp, kết quả được sắp xếp theo thứ tự tăng dần của mã lớp.

// Input: A list of Students, each Student has id, name, class_id, avg_score.
// Output: Map of class_id to the student with the highest avg_score in that class.
//         Keys should be sorted in ascending order.
// Example:
// Input: [
//   Student("1", "A", 1, 8.0),
//   Student("2", "B", 1, 9.0),
//   Student("3", "A", 2, 7.0),
// ]
// Output: {
//   1: Student("2", "B", 1, 9.0),
//   2: Student("3", "A", 2, 7.0),
// }

data class Student(
  val id: String,
  val name: String,
  val classId: Int,
  val avgScore: Double
)

@JvmField
val compareByAvgScore = compareBy<Student> { it.avgScore }

// (TreeMap take O(log n) time in the worst case to get/put).
typealias Output = SortedMap<Int, Student>

fun solution(students: List<Student>): Output = TODO()

fun main() {
  val students = listOf(
    Student("1", "A", 1, 8.0),
    Student("2", "B", 1, 9.0),
    Student("3", "A", 2, 7.0),
  )
  val output = mapOf(
    1 to Student("2", "B", 1, 9.0),
    2 to Student("3", "A", 2, 7.0),
  )
  check(solution(students) == output)
}

Solution 1: Sử dụng vòng lặp

Cách này ổn về mặt thời gian và không gian, nhưng cách viết khá dài dòng và khó đọc, và theo imperactive style (for loop + if statement).

// Time complexity (worst case) = n * (O(log n) + O(log n)) = O(2 * n * log n).
// Space: 1 TreeMap.
// ----
// Pros: good in terms of time complexity and space complexity.
// Cons: imperative style.
fun solution1(students: List<Student>): Output {
  val result = sortedMapOf<Int, Student>()
  for (student in students) {
    val current = result[student.classId]
    if (current == null || student.avgScore > current.avgScore) {
      result[student.classId] = student
    }
  }
  return result
}

Solution 2: Sử dụng groupBy và mapValues

Cách này sử dụng functional style, nhưng không tốt về mặt thời gian và không gian. Nó phải tạo ra 1 HashMap trung gian, và một TreeMap (SortedMap) để lưu kết quả. Ngoài ra, nó cũng phải duyệt 3 lần, 1 lần để groupBy, 1 lần để mapValues, trong mỗi lần mapValues lại phải duyệt để tìm max.

// Time complexity (worst case)
//     - groupByTo: O(n * ( O(1) + O(n) )) = O(n^2)
//     - mapValuesTo: O(n * ( O(log n) + O(n) )) = O(n^2 * log n)
//     - total: O(n^2 * log n)
// Space: 1 HashMap + 1 TreeMap
// ----
// Pros: functional style.
// Cons: bad in terms of time complexity and space complexity.
fun solution2(students: List<Student>): SortedMap<Int, Student> = students
  .groupByTo(hashMapOf()) { it.classId }
  .mapValuesTo(sortedMapOf()) { (_, v) -> v.maxBy { it.avgScore } }

Solution 3: Sử dụng groupingBy và reduce

// Time complexity (worst case)
//     - groupingBy: O(1) (just returns a Grouping object)
//     - reduceTo: O(n * ( O(log n) + O(log n) )) = O(n * log n)
//     - total: O(2 * n * log n)
// Space: 1 TreeMap (Grouping object is small).
// ----
// Pros: BEST. Functional style, good in terms of time complexity and space complexity.
// Cons: NO.
fun solution3(students: List<Student>): SortedMap<Int, Student> = students
  .groupingBy { it.classId }
  .reduceTo(sortedMapOf()) { _, accumulator, element -> maxOf(accumulator, element, compareByAvgScore) }

Cách này là tốt nhất cho đến hiện tại :), nó sử dụng functional style, và tốt về mặt thời gian và không gian.

• Bản chất, groupingBy sẽ tạo và return 1 object Grouping để lưu trữ Iterator và Key Selector để thực hiện việc reduce/aggregate sau đó.

  @SinceKotlin("1.1") public interface Grouping<T, out K> {
      fun sourceIterator(): Iterator<T>
      fun keyOf(element: T): K
  }
  

  Grouping không thực hiện việc duyệt, reduce/aggregate ngay lập tức, mà nó chỉ lữu trữ những cái cần thiết để thực hiện việc aggregate sau này. Đó là cơ chế LAZY, tương tự như Sequence của Koltin, Stream của Java, Observable của RxJava, Flow của Kotlin Coroutines, ...

• Sau đó, reduceTo sẽ duyệt qua Grouping object, và thực hiện việc reduce/aggregate trên từng Group xác định bởi Key Selector. Hàm reduceTo trên Grouping có cơ chế khá giống trên Iterable, nhưng nó không thực thi operation trên toàn bộ Iterable, mà nó thực thi operation trên từng Group xác định bởi Key Selector. Bản chất như sau (không giống source của stdlib 100%, vì lược bỏ những thứ không cần thiết):

inline fun <S, T : S, K, M : MutableMap<in K, S>> Grouping<T, K>.reduceTo(
  destination: M,
  operation: (key: K, accumulator: S, element: T) -> S
): M {
  for (element in sourceIterator()) {
    val key = keyOf(element)
    val accumulator = destination[key]
    destination[key] = if (accumulator == null && !destination.containsKey(key)) {
      element
    } else {
      operation(key, accumulator as S, element)
    }
  }
  return destination
}

Follow tôi, chúng tôi https://rx-mobile-team.github.io/profile/ để có thêm nhiều kiến thức về lập trình, không chỉ giới hạn ở Mobile (Android/iOS/Flutter) mà có cả Functional Programming, Reactive Programming, Data Structures, Algorithms, ... Những kiến thức chia sẻ ở đây, rất ít các Senior Dev và vân..vân.. chia sẻ cho các bạn đâu.

Why do @Composable functions in Jetpack Compose usually use Dp.Unspecified as default value? Why not use null? The optimization of Jetpack Compose under the hood

• Author: Petrus Nguyễn Thái Học
• Published on Sep 16, 2023
• 5 minutes read so far
• Tags: #hoc081098, #rx_mobile_team, #kotlindev #androiddev, #rxandroid, #jetpack_compose, #value_class

When using Jetpack Compose, we use Dp type to represent a dimension value representing device-independent pixels (dp). It is used many times and everywhere in Jetpack Compose.

Do you have the same question as me 😇, when looking Jetpack Compose source code: Why do @Composable functions in Jetpack Compose usually use Dp.Unspecified as default value? Why not use null?

Dp.Unspecified is usually used as default value in Jetpack Compose source code

I. Dp class

I.1. Dp class declaration

At the moment, Dp class is defined as follows:

@Immutable
@kotlin.jvm.JvmInline
value class Dp(val value: Float) : Comparable<Dp> {
    @Stable
    inline operator fun plus(other: Dp): Dp = ...

    @Stable
    inline operator fun minus(other: Dp): Dp = ...

    // [...]
    // Other operators ...
    // [...]

    @Stable
    override /* TODO: inline */ operator fun compareTo(other: Dp) = value.compareTo(other.value)

    @Stable
    override fun toString() = if (isUnspecified) "Dp.Unspecified" else "$value.dp"

    companion object {
        @Stable
        val Hairline = Dp(value = 0f)

        @Stable
        val Infinity = Dp(value = Float.POSITIVE_INFINITY)

        /**
         * Constant that means unspecified Dp
         */
        @Stable
        val Unspecified = Dp(value = Float.NaN)
    }
}

Dp class is declared as inline value class wrapping a Float value. When compiling, the compiler will try to replace all Dp types with Float types (float in Java) as much as possible. This reduces memory usage and improves performance since heap allocation is eliminated, and Float type, a primitive type, is usually heavily optimized by the runtime. That is the optimization of Jetpack Compose.

The inline class spec is here.

I.2. Example ✍️

Let's create a simple example to see how the compiler optimizes Dp class, I create a @Composable fun MyComposable1 accepting a Dp as the first parameter.

MyComposable1 accepts a Dp as the first parameter

After compiling Kotlin and decompiling Java bytecode to Java code, we can see that the compiler has replaced Dp types with Float types.

Dp types are replaced with Float types

You may notice that the method name MyComposable1 has been changed, that is called mangling.

Mangling: since inline classes are compiled to their underlying type, it may lead to various obscure errors, for example unexpected platform signature clashes. To mitigate such issues, functions using inline classes are mangled by adding some stable hashcode to the function name.

II. Why do @Composable functions in Jetpack Compose usually use Dp.Unspecified as default value? Why not use null?

II.1. Why not use null?

After looking at the Dp class, we can understand why Dp is declared as inline value class, and the optimization of Jetpack Compose under the hood. Let's get back to the question at the beginning of this article.

Dp.Unspecified is usually used as default value in Jetpack Compose source code

Inline value class and Auto Boxing are keywords here.

"Boxing" refers to converting a primitive value into a corresponding wrapper object. Because this can happen automatically, it's known as autoboxing. Similarly, when a wrapper object is unwrapped into a primitive value then this is known as unboxing. (https://www.baeldung.com/java-wrapper-classes#autoboxing-and-unboxing)

If we use null as default value, we must declare the type as Dp? (nullable type). Since Dp? is a nullable type, compiler cannot use Float (aka float in Java) type to replace Dp? type. Instead, Dp? must be used!!!

nullable inline class types over primitive types are mapped to the boxed reference type (wrapper of an inline class)

Dp? is a reference type, not a primitive type, it requires heap allocation. Imagine we use Dp? types in many places (the worst case is in a loop or is in List/Row/Column/... UI), it will cause a lot of heap allocation, affect the application performance ⚠️, especially a UI application, its performance is very important to the user experience.

II.2. Demonstration example ✍️

Let's create a simple example using Dp? type, we create a @Composable fun MyComposable2 accepting a Dp? as the first parameter.

MyComposable2 accepts a Dp? as the first parameter

After decompiling, we can see that Dp type is not replaced with Float type, it is preserved. Inside UseMyComposable2, Dp.box-impl(Dp.constructor-impl((float)$this$dp$iv)) is used to box a Float value to a Dp. It is a heap allocation ⚠️.

Dp type is not replaced with Float type and heap allocation is used

That is the reason why we must not use null as default value. Dp.Unspecified is a better choice ✅, it wraps a Float.NaN value. Sometimes, we can use Dp.Hairline (aka 0.dp) as default value, depending on your use case.

II.3. Bonus ✅

• How about elvis operator ?:?
• How about == null?

Jetpack Compose has replacements, they are Dp.takeOrElse(block: () -> Dp): Dp and Dp.isUnspecified: Boolean. takeOrElse is an inline function, no lambda allocation, no heap allocation here 🥰.

Dp.takeOrElse and Dp.isUnspecified

Thanks for reading 🤗.

Follow me (@hoc081098) and us (https://rx-mobile-team.github.io/profile/) to have more knowledge about programming, not only limited to Mobile (Android/iOS/Flutter) but also Functional Programming, Reactive Programming, Data Structures, Algorithms, ...

Estimated reading time: 7 minutes

Rate limiting không nên được đặt ở một tầng duy nhất. Trong một hệ thống backend có phân tầng rõ ràng, rate limiting thường xuất hiện ở ba vị trí: Nginx (edge), API Gateway và từng service cụ thể. Mỗi tầng có mục tiêu khác nhau, và nếu phân định đúng, chúng bổ trợ cho nhau thay vì chồng chéo.

Internet
   ↓
Nginx (IP flood protection)
   ↓
YARP (user / tenant policy limit)
   ↓
Service (domain limit / concurrency limit)

1. Nginx - tầng hạ tầng (edge / infra level)

• Config các basic rate limiting nhằm mục đích chống spam/DDoS, chống flood thô. Đây là lớp phòng thủ đầu tiên trước khi request chạm tới business logic. Nó không hiểu JWT là gì, không biết UserId hay TenantId nào đang gọi. Nó chỉ nhìn thấy network-level metadata.
• Ví dụ: limit theo IP address, Geo block (theo quốc gia/vùng), hoặc giới hạn request rate và connection ở mức IP
• Mục tiêu: network-level protection - chặn rác ở tầng infra/network, trước khi đi sâu vào business logic

http {
    # ... other http settings ...
    limit_req_zone $binary_remote_addr zone=mylimit:10m rate=5r/s;
}

server {
    # ... other server settings ...

    limit_req_status 429; # Return "429 Too Many Requests" error
    location /login/ {
        limit_req zone=mylimit burst=10 nodelay;
        # ... other location settings, e.g., proxy_pass ...
    }
}

• Sử dụng limit_req_zone directive trong http block với

  • $binary_remote_addr: sử dụng IP address của client trong dạng nhị phân để làm KEY.
  • zone=mylimit:10m: tạo 1 zone tên là "mylimit" có size 10MB memory (có thể lưu trữ trạng thái của khoảng 160,000 địa chỉ IP)
  • rate=5r/s: giới hạn tốc độ là 5 requests/giây cho mỗi IP address.

• Sử dụng limit_req directive trong location block để áp dụng limit đã định nghĩa ở trên.

  • zone=mylimit: chỉ định zone đã tạo ở trên
  • burst=10: Thiết lập một "hàng đợi" dự phòng cho phép tối đa 10 request vượt định mức. Thay vì bị từ chối ngay lập tức khi vượt quá rate, các request này sẽ được tạm giữ lại trong bộ nhớ của Nginx.
  • Mặc định (không có nodelay): Nginx sẽ "điều tiết" lưu lượng bằng cách áp đặt độ trễ (delay). Các request trong hàng đợi burst sẽ bị ép phải xếp hàng và đi qua cửa kiểm soát từng cái một theo đúng nhịp độ của rate. Kết quả là người dùng sẽ thấy ứng dụng bị chậm lại (latency cao) nhưng không bị lỗi. nodelay: Khi kích hoạt, Nginx sẽ ưu tiên trải nghiệm người dùng bằng cách cho phép các request trong hàng đợi được xử lý ngay lập tức mà không cần chờ đợi. Tuy nhiên, mỗi request "đi tắt" này vẫn sẽ chiếm dụng một slot trong hàng đợi burst và chỉ được giải phóng (hồi slot) theo đúng tốc độ của rate.
  • Lưu ý: Chỉ khi hàng đợi dự phòng này bị lấp đầy hoàn toàn (vượt quá cả rate lẫn burst), Nginx mới bắt đầu từ chối bằng status code đã cấu hình (ví dụ: 429).

2. API Gateway (ví dụ YARP)

• Config rate limiting chung cho các services phía sau. Tầng này có thể parse và hiểu JWT, UserId, TenantId, API key, API version. Khác với Nginx, gateway hiểu "ai đang gọi", không chỉ "IP nào đang gọi". Vì vậy, nó phù hợp để enforce các chính sách truy cập và quota mang tính hệ thống.
• Ví dụ: limit theo UserId, TenantId, apply quota theo API key, API version, Quota theo app.
• Mục tiêu: policy-level control - bảo vệ tài nguyên theo các rules/policies chung cho nhiều services.

3. Service: tầng business logic cụ thể

• Khi request đi tới service, rate limiting không còn đơn thuần là bảo vệ hạ tầng hay thực thi policy chung nữa, mà gắn trực tiếp với domain. Ở đây, ta config rate limiting riêng cho service đó, dựa trên business logic đặc thù của service.
• Ví dụ: một user chỉ được tạo 5 order/phút, một tenant chỉ được gửi 1,000 webhook/phút, chỉ cho phép 10 concurrent job xử lý
• Mục tiêu: business-level control - bảo vệ tài nguyên dựa trên logic cụ thể.

4. Rate Limiting Algorithms trong ASP.NET Core (có thể dùng cho YARP và Services)

• Fixed Window: Đơn giản, giới hạn số requests trong 1 window cố định. Nhưng dễ bị spike ở window boundary.
• Sliding Window: Cải tiến hơn Fixed Window. Giới hạn N request/X giây gần nhất bằng cách chia Window thành nhiều segment cố định, mỗi khi check sẽ đếm số request của segment hiện tại với các segment trước đó. Giảm spike tại window boundary. Nhưng tốn kém hơn về mặt memory vì phải lưu nhiều segment. Đọc thêm tại bài viết trên Facebook
• Token Bucket: Mỗi request sẽ "rút" token từ bucket. Bucket được refill theo thời gian. Cho phép burst trong 1 thời gian ngắn & giữ tốc độ trung bình trong thời gian dài. Phù hợp với các hệ thống cần cho phép burst nhưng vẫn kiểm soát lưu lượng trung bình. Đọc thêm tại bài viết trên Facebook
• Concurrency: Giới hạn số requests đang được xử lý đồng thời tại 1 thời điểm. Không giới hạn số request theo thời gian, mà giới hạn số request đang xử lý đồng thời. Phù hợp với các hệ thống có tài nguyên hạn chế hoặc cần đảm bảo hiệu suất ổn định.

Một đoạn code ví dụ về cách cấu hình Rate Limiting trong YARP:

File Program.cs

// 1. Add Rate Limiter.
services.AddRateLimiter(options =>
{
    options.AddFixedWindowLimiter("customPolicy", opt =>
    {
        opt.PermitLimit = 4;
        opt.Window = TimeSpan.FromSeconds(12);
        opt.QueueProcessingOrder = QueueProcessingOrder.OldestFirst;
        opt.QueueLimit = 2;
    });
});

// 2. add the RateLimiter middleware.
app.UseRateLimiter();

app.MapReverseProxy();

File appsettings.json - Apply customPolicy rate limit policy cho route1:

{
  "ReverseProxy": {
    "Routes": {
      "route1" : {
        "ClusterId": "cluster1",
        "RateLimiterPolicy": "customPolicy",
        "Match": {"Hosts": [ "localhost" ]}
      }
    },
    "Clusters": {
      "cluster1": {
        "Destinations": {
          "cluster1/destination1": {
            "Address": "https://localhost:10001/"
          }
        }
      }
    }
  }
}

Đọc thêm Microsoft docs: Rate Limiting in YARP

Khi phân tầng đúng, chúng bổ trợ nhau

• Edge (Nginx): stateless & IP-based -> chống rác ở network level
• Gateway (YARP): identity-aware -> enforce policy theo identity
• Service: stateful & domain-aware -> enforce invariant theo domain

Chúng chỉ overlap khi ranh giới không rõ ràng. Ví dụ, nếu Nginx limit quá chặt, request hợp lệ có thể bị chặn trước khi tới gateway hoặc service, khiến các tầng phía dưới không còn ý nghĩa thực tế. Hoặc nếu cùng một logic rate limiting bị định nghĩa trùng nhau ở cả Nginx và Gateway, hệ thống sẽ trở nên rối rắm và khó kiểm soát. Rate limiting, nếu nhìn đúng bản chất, không phải một cấu hình duy nhất. Nó là một chiến lược phân tầng. Và sự rõ ràng trong phân tầng mới là thứ quyết định hệ thống có gọn gàng hay trở thành spaghetti policy.

Author: Petrus Nguyễn Thi Học

• Tags: #functional-programming, #hoc081098, #rx_mobile_team, #kotlindev #androiddev, #iosdev, #rxswift, #rxjava, #rxkotlin #functional_reactive_programming, #reactive_programming, #reactive_extensions, #reactive_programming, #reactive_extensions, #rxjava2, #rxjava3, #rxswift, #rxkotlin, #rxandroid, #rxmobile

I. Serially rule 😇

Observable trong ReactiveX phải thuân thủ quy tắc Serially, tức là phải đảm bảo các sự kiện phát ra không được overlap lên nhau. Quy tắc này không bắt buộc các event (signal) phải được delivered đến các subscriber ở cùng một thread. Nó vẫn có thể được delivered đến các subscriber ở các thread khác nhau, nhưng nó phải đảm bảo các event không được overlap lên nhau (tức phải đồng bộ thông qua các cơ chế như lock, atomic, ...).

Ví dụ: một Observable phát ra onNext(1), onNext(2), onNext(3) thì 1 subscriber có thể nhận onNext(1) ở thread A, onNext(2) ở thread B, onNext(3) ở thread A, nhưng nó không được phép nhận onNext(2) trong khi onNext(1) đang được delivered.

Hãy xem Reactive Streams Specification for the JVM để thấy rõ hơn.

II. Subjects are not thread-safe on the Observer side 🥺

Subject không phải là thread-safe ở phía Observer. Nếu chúng ta invoke onNext, onError, onCompleted trên Subject từ nhiều thread khác nhau thì có thể dẫn đến các event bị overlap lên nhau, và điều này sẽ làm Subject không đảm bảo quy tắc Serially nữa.

Trong RxJava, tất cả Subject đều không thread-safe, ngoại trừ SerializedSubject. Chỉ cần gọi toSerialized() trên 1 Subject bất kì là chúng ta đã có được một SerializedSubject. SerializedSubject sẽ serialize các lời gọi tới method của Observer side, điều này được đảm bảo bằng 1 queue có type AppendOnlyLinkedArrayList được synchronized bởi chính SerializedSubject đó, queue này sẽ giữ các event (signal/notification) bị missed, để sau đó sẽ loop và deliver chúng đến các Observer một cách synchronized.

1. ⚠️ Synchronization anomaly was detected

Trong RxSwift, 4 loại Subject PublishSubject, BehaviorSubject, ReplaySubject, AsyncSubject đều không thread-safe.

✍️ Hãy lấy ví dụ với PublishSubject, gọi onNext trên PublishSubject từ nhiều thread khác nhau cùng lúc.

❌ Lỗi này xảy ra khi event thứ nhất onNext(1) được send từ thread của queue-1, onNext(2) event sau lại được send từ thread của queue-2 trong khi event 1 đang được delivered,tức vẫn chưa hoàn thành việc delivery event 1.

🧐 RxSwift detect được chúng ta đang gọi từ nhiều thread khác nhau, sẽ log ra lỗi ⚠️ Synchronization anomaly was detected. Nếu chúng ta enable flag FATAL_SYNCHRONIZATION, thì RxSwift sẽ crash app thông qua fatalError.

✅ Cách fix đơn giản nhất là tạo một Serial DispatchQueue, và đưa các lời gọi tới PublishSubject vào trong DispatchQueue đó. Hoặc sử dụng một NsRecursiveLock để đảm bảo các lời gọi tới Observer side của PublishSubject được synchronized.

Serial DispatchQueue

NsRecursiveLock

2. ⚠️ Reentrancy anomaly was detected

Nếu chúng ta đảm bảo các lời gọi tới Observer side một Subject luôn trên cùng một Thread, nhưng vẫn có thể gặp lỗi ⚠️ Reentrancy anomaly was detected. Lỗi này hay gặp khi chúng ta gọi các Observer side của một Subject, bên trong chính Observer của Subject.

✍️ Hãy lấy ví dụ gọi onCompleted bên trong onNext closure.

❌ Lỗi này xảu ra khi onNext(2) đang được delivered, và onCompleted được gọi trong khi đang trong quá trình delivery event 2.

🧐 Tương tự như Synchronization anomaly, RxSwift sẽ detect được chúng ta đang gọi 1 method của Observer side bên trong chính Observer của Subject, và sẽ log ra lỗi ⚠️ Reentrancy anomaly was detected (hoặc crash nếu chúng ta enable flag FATAL_REENTRANCY thông qua fatalError).

✅ Cách fix đơn giản nhất là tránh gọi các method của Observer side bên trong chính Observer của Subject. Hãy sử dụng các filtering operators như filter, take, skip, distinctUntilChanged, takeWhile, takeUntil, ... để filter các event không mong muốn. Hãy reactive thay vì imperative.

They [Subjects] are the "mutable variables" of the Rx world and in most cases you do not need them. Typically a solution with Create or the other operators allows you to just wire up continuations without adding extra state. Stated slightly differently, it is good practice to minimize the number of objects that hold on to subscribers, you just want to pass them through. (Erik Meijer - Rx.Net inventor).

3. Tìm hiểu cách RxSwift detect các lỗi trên

Đầu tiên, hãy xem source của PublishSubject.swift. PublishSubject conforms ObserverType protocol, ObserverType có một số extension onNext, onError, onCompleted forward tới on(_ event: Event<Int>).

Hãy xem implementation của on(_ event: Event<Int>) trong PublishSubject.swift. Khi flag DEBUG được enable, RxSwift sẽ dùng SynchronizationTracker để track lúc bắt đầu việc dispatch event (dòng code self.synchronizationTracker.register(synchronizationErrorMessage: .default)) và track lúc kết thúc (dòng code defer { self.synchronizationTracker.unregister() }).

SynchronizationTracker chứa một Dictionary var threads = [UnsafeMutableRawPointer: Int]() với key là con trỏ tới Thread, value là số lượng lời gọi on(_ event: Event<Int>) đang được thực thi (in-progress) trên Thread tương ứng.

Bên trong register, chúng ta sẽ tăng value lên 1 cho key là con trỏ tới Thread hiện tại. Nếu count > 1, tức là có nhiều hơn 1 lời gọi on(_ event: Event<Int>) đang được thực thi (in-progress) trên Thread hiện tại, và đang bị overlap lên nhau (Reentrancy anomaly). Lúc đó, RxSwift sẽ log ra lỗi ⚠️ Reentrancy anomaly was detected hoặc crash.

Sau đó, check số lượng Threads đang trong trạng thái delivering. Nếu số lượng threads đang thực thi việc delivery event lớn hơn một, tức là có nhiều hơn 1 Thread đang delivery event đồng thời (Synchronization anomaly). Lúc đó, RxSwift sẽ log ra lỗi ⚠️ Synchronization anomaly was detected hoặc crash.

Cuối cùng, sau khi delivery event, hàm unregister được gọi để giảm số lượng value đi 1 cho key là con trỏ tới Thread hiện tại. Nếu value về 0, tức là không còn lời gọi on(_ event: Event<Int>) nào đang được thực thi trên Thread hiện tại, chúng ta sẽ remove key đó ra khỏi Dictionary threads.

Logic đơn giản như vậy thôi 🥰🥰. Các bạn có thể tìm hiểu thêm trong source code của RxSwift Rx.swift và PublishSubject.swift.

Follow tôi, chúng tôi https://rx-mobile-team.github.io/profile/ để có thêm nhiều kiến thức về lập trình, không chỉ giới hạn ở Mobile (Android/iOS/Flutter) mà có cả Functional Programming, Reactive Programming, Data Structures, Algorithms, ... Những kiến thức chia sẻ ở đây, rất ít các Senior Dev và vân..vân.. chia sẻ cho các bạn đâu.