개발하는 북극곰

Dead Letter Queue (DLQ) 패턴

북극곰은콜라 — Thu, 13 Feb 2025 17:31:48 +0900

개요

카프카는 Queue를 베이스로 하여 데이터의 발행/소비를 인프라 적으로 격리시킨 시스템으로 볼 수 있다. 이런 격리된 프로세스는 확장성과 가용성을 제공하지만 운영 상 복잡성이 늘어나게 된다.
Queue의 데이터를 임의로 핸들링 하기 힘들다는 점을 집중적으로 분석하고 해결방안 또는 대처방안에 대해 정리하고자 한다.

Dead Letter Queue (DLQ) 패턴이란?

DLQ는 Consumer가 정상적으로 처리하지 못한 메시지를 따로 저장하는 Kafka의 보조적인 토픽
즉, 오류가 발생한 메시지를 다른 곳에 보관하여 이후 다시 처리할 수 있도록 하는 전략

DLQ 핵심 전략

- Consumer가 메시지를 처리하는 도중 오류 발생
- 오류가 발생한 메시지를 DLQ 토픽에 저장
- DLQ에 저장된 메시지를 모니터링 및 분석
- DLQ에 저장된 메시지를 별도의 프로세스로 재처리

DLQ 패턴의 의미

DLQ 패턴은 처리하지 못한 데이터를 적극적으로 핸들링하기 위한 방법입니다.
따라서 DLQ 모니터링과 분석이 필수적이라 여겨집니다.
궁극적으로 모니터링 도구와 연동으로 개발자가 에러의 원인을 빠르게 파악하고 재처리하여 전체 시스템의 신뢰도를 높일 수 있는 방법이란 의미가 있습니다.

장점

1. 데이터 유실 방지 & 보존 가능 + 메시지 재처리/복구

Kafka에서 Consumer가 메시지를 정상적으로 처리하지 못하면 기본적으로 재시도 없이 메시지가 손실될 가능성이 있다 DLQ를 사용하면 실패한 메시지를 안전하게 저장하고 나중에 재처리 가능, 데이터 유실을 방지할 수 있다
DLQ에 저장된 메시지를 특정 시점 이후에 다시 정상 토픽으로 재전송하여 재처리 가능재처리 로직을 통해 일괄적으로 복구하거나 특정 메시지만 선택적으로 복구 가능

2. 모니터링 이점 및 장애 발생 시 신속한 대응 가능

실시간으로 Kafka Consumer가 처리하지 못한 메시지를 DLQ에 쌓이도록 설정하면 장애 감지 및 대응이 쉬워 짐 DLQ에 특정 유형의 메시지가 급격히 증가하면 Consumer의 코드 오류 또는 다운타임 발생 가능성을 빠르게 인지할 수 있다.
이는 에러로그 사후분석에 비해 효율적이며, 상황에 따른 트리거링도 가능하다.

3. 비즈니스 로직에 따른 맞춤형 처리 가능

특정 비즈니스 요구사항에 따라 DLQ에 쌓인 메시지를 다양한 방식으로 처리 가능
실패한 메시지를 즉시 재처리할지, 특정 시간 이후에 다시 시도할지, 별도 데이터베이스에 저장할지 등을 설정 가능

단점

1. 시스템 복잡도 증가

DLQ를 도입하면 기존 Kafka Consumer와 함께 추가적인 DLQ Topic, DLQ Consumer, 재처리 로직 등이 필요 이러한 복잡성 증가로 인해 운영 부담이 커지고 유지보수가 어려워질 수 있음 또한 DLQ로 전송하는 로직도 구현해야 하며, 모니터링 시스템까지 구축해야 높은 효율을 보인다.
이러한 복잡도는 운영 요소의 증가로 이어진다.

2. DLQ 메시지가 쌓이면 운영 부담 증가

DLQ 메시지를 재처리하지 않으면 계속해서 쌓이고, 결국 스토리지 비용 증가한다.
또한 너무 쌓인 데이터는 분석 및 핸들링에 어려움을 가져와 DLQ 패턴의 도입 이점이 희석될 수 있다.

3. 메시지 재처리 시 데이터 순서 유지 어려움

Kafka의 메시지는 Partition 단위로 순서를 보장하지만, DLQ에 저장된 메시지를 다시 처리할 때는 순서가 깨질 가능성이 높음
이를 해결하려면 일부 메시지를 특정 시점에만 재처리하도록 조정하거나 다른 timestamp를 기준으로 재정렬하는 로직이 필요하다.
하지만 운영이 복잡해짐

DLQ 도입 고려 요소

도입이 적절한 경우	도입이 불필요한 경우
- 데이터 유실을 절대 허용할 수 없는 시스템 (예: 금융 거래, 주문 시스템) - Consumer가 일시적으로 장애가 발생할 가능성이 있는 경우 - 메시지 처리 오류가 발생할 수 있는 복잡한 비즈니스 로직을 운영하는 경우 - Kafka Consumer의 안정성을 높이고, 운영 효율성을 개선하고 싶은 경우	- 메시지 처리 속도가 가장 중요한 실시간 시스템 (DLQ에서 재처리하는 시간이 부담이 될 수 있음) - Consumer 코드가 안정적이고, 장애가 거의 발생하지 않는 경우 - Kafka의 기본적인 재시도 및 에러 핸들링 기능만으로 충분한 경우

False Data 유입 상황

무중단 Producer/consumer 배포 시 record 호환성 문제

scale-out 구조에서 흔하게 발생하는 문제로 무중단 배포 시 일부 데이터가 처리되지 못해 유실되는 상황이다.따라서 무중단 배포 시 다음과 같은 상황 별 대처 방안이 필요하다.
- 데이터 누락이 허용되는 경우
- 데이터 누락이 허용되지 않는 경우

Human Error가 포함된 배포

Producer나 Consumer의 record 발행/소비의 유지보수 과정에서 예상하지 못한 error가 발생할 수 있다.
리뷰나 스테이징 운영을 통해 최대한 줄일 수 는 있지만 원천 차단은 불가할 것이다.

해결 방안

1. 데이터 누락 허용의 경우

데이터 누락이 허용되는 경우 consumer의 예외 및 skip처리를 구현해 놓으면 된다.
이후 효율성을 위해 producer → consumer 순으로 배포하면 된다.

2. 데이터 누락 허용 불가의 경우

2-1) Topic 분리 (version or temp 토픽)

호환 불가능한 record를 임시로 수용할 temp 토픽 또는 v2 토픽을 통해 무중단 배포하는 방식이다.

2-2) DLQ 패턴 적용

DLQ 패턴은 시스템 신뢰도를 높일 수 있는 방법으로 패턴 특성 상 무중단 배포에서 발생하는 이슈를 커버해 줄 수 있다.

Conclusion

- Kafka 무 중단 배포, 휴먼 에러 등 여러 이유로 처리되지 못하는 record가 발생할 수 있다.
- Topic 분리를 통해 처리되지 못한 record를 발생시키지 않을 수 있다.
- DLQ 패턴을 도입하여 처리되지 못한 record를 전반적으로 관리할 수 있다.
- DLQ는 Kafka 운영 환경 시스템의 신뢰도를 높일 수 있는 좋은 방법 중 하나이다.
- DLQ는 추가적인 개발 및 운영 비용이 들어간다.

REFERENCE

https://rudaks.tistory.com/entry/신뢰성-오류-복구-패턴-데드-레터-큐Dead-Letter-Queue-패턴

https://devidea.tistory.com/111

https://sjoongh.tistory.com/entry/DLQ-적용기

VoltDB란

북극곰은콜라 — Mon, 3 Jun 2024 21:37:27 +0900

개요

VoltDB 조사 및 사용성 검토
어떤 목적 및 사상을 가지고 있는지, 해결한 문제, 한계점 등을 파악

VoltDB란?

VoltDB는 기존 Database 대비 throughtput을 향상 시키기 위해 개발된 ACID를 준수하는 transactional database이다.
기존 DB는 범용성을 위해서 최적화 범위를 제한하였는데, voltDB는 이를 개선하고자 했다.
디자인 아이디어
- ACID 및 SQL 스펙을 만족하여 러닝커브를 줄임
- in-memory 방식을 통한 Disk-IO를 줄임
- data access를 serializing하여 locking, latching, transaction log 관리에 대한 오버헤드를 최소화
- clustering, replication을 통한 고가용성 및 안정성 확보

VoltDB 목적

Focus on handling fast data

VoltDB는 금융, SNS, IoT등 빠른 데이터 Store에 대한 문제를 해결합니다.
이는 scalability, reliability, high availability, high throughput을 지원함을 의미합니다.

SQL Support

SQL을 지원하기 때문에 상대적으로 낮은 러닝커브를 갖고 있습니다.

Inefficient for Large & complicated Data Structure

VoltDB는 히스토리성 데이터 같이 큰 데이터를 handling하기에는 부적합합니다.
또한 여러 테이블을 join하는 복잡한 데이터의 handling을 최적으로 지원하고 있지 않습니다.

Architecture Complicated

최적의 성능을 위해서는 설계의 복잡성이 증가합니다.
Stored Procedure 기반, partition 개념 등 설계 및 운용 시 고려해야 할 사항이 늘어납니다.

VoltDB Idea

1. In-memory processing

VoltDB는 DiskIO를 없에고, memory로 data store를 구성하여, performance를 향상시켰다.

2. Stored Procedure Interface

기존 Data Query는 네트워크 패킷의 overhead 및 Query 해석, 목적을 위한 다중 쿼리 전송 등 작업이 performance를 낮춥니다.
VoltDB는 Stored Procedure만을 호출하여 위 overhead를 one round trip으로 수행할 수 있도록 합니다.
또한 VoltDB는 하나의 procedure는 하나의 transaction을 의미하며, success 또는 rollback을 한 동작에서 가능하도록 합니다.

3. Serialized Processing

VoltDB는 1 DataAccess == 1 transaction 이다. 이 요청들은 serial하게 execution engine에서 실행된다.
Execution Engine은 VoltDB의 Partition 당 하나씩 생성되는데 이는 CPU cores와 cluster에 따라서 결정된다.
결론적으로 voltDB는 모든 요청을 serial하게 처리하여, lock 및 latch 없이 transactional한 처리를 지원한다.

VoltDB 동작원리

1. Partitioning

VoltDB는 모든 Stored Procedure를 Analyze하고 precompile하여 access data logic을 정리한다.
이 과정을 통해, voltDB는 실행환경(CPU Core등)을 고려하여 execute engine을 포함한 partition을 initialize한다.
각 partition은 기본적으로 유니크한 data의 집합을 가지고 있다.

2. Serialized Processing

VoltDB는 모든 쿼리가 Stored Procedure로 동작한다. 또한 Stored Procedure는 하나의 transaction을 의미한다.
이는 하나의 쿼리 당 하나의 transaction을 의미한다.
모든 요청을 serial하게 처리하면 transaction을 고려한 lock 및 latch를 사용할 필요가 없어진다.

Stored procedure는 Analyze 단계에서 Single-partitioned 또는 Multiple-partitioned 2종류로 나누어진다.
Single-partitioned procedure는 다른 partition과 상관없는 procedure로 execute engine에서 parallel하게 동작한다.
Multiple-partitioned procedure는 연관 있는 특정 partition의 execute engine에서 다른 partition의 결과를 collect하는 방식으로 동작한다.
당연하게도 Multiple-partitioned procedure는 성능이 떨어진다.

3. Replication

VoltDB는 Single-partitioned procedure가 최적의 성능을 제공한다.
이에 join을 위한 largely read-only table을 각 partition에 replication하는 기능을 제공한다.
위 그림의 D테이블은 read가 압도적으로 많으며, A,B,C간의 관계를 나타내는 테이블이다.
D테이블이 없는 partition은 항상 Multiple-partitioned procedure로 동작하면 불합리하기에, D 테이블을 파티션에 복제하여, 모두 Single-partitioned procedure처럼 동작할 수 있도록 할 수 있다.

VoltDB vs RDBMS(MariaDB) vs MongoDB vs Redis

Name	MariaDB	MongoDB	Redis	VoltDB
Primary database model	Relational DBMS	Document store	Key-value store	Relational DBMS
Secondary database models	Document store Graph DBMS Spatial DBMS	Spatial DBMS Search engine Time Series DBMS Vector DBMS	Document store Graph DBMS Spatial DBMS Search engine Time Series DBMS Vector DBMS
DB-Engines Ranking	Score: 93.81	Score: 423.96	Score: 156.44	Score: 1.46
Initial release	2009	2009	2009	2010
Current release	11.3.2, February 2024	6.0.7, June 2023	7.2.4, January 2024	11.3, April 2022
License	Open Source	Open Source	Open Source	Open Source
Implementation language	C and C++	C++	C	Java, C++
Data scheme	yes	schema-free	schema-free	yes
Typing (predefined dataType)	yes	yes	partial	yes
Secondary indexes	yes	yes	yes	yes
SQL	yes	Read-only SQL queries via the MongoDB Atlas SQL Interface	with RediSQL module	yes
APIs and other access methods	ADO.NET JDBC ODBC Proprietary native API	GraphQL HTTP REST Prisma proprietary protocol using JSON	proprietary protocol	Java API JDBC RESTful HTTP/JSON API
Triggers	yes	yes	publish/subscribe channels provide some trigger functionality; RedisGears	no
Partitioning methods	several options for horizontal partitioning and Sharding	Sharding	Sharding	Sharding
Replication methods	Multi-source replication Source-replica replication	Multi-Source deployments with MongoDB Atlas Global Clusters Source-replica replication	Multi-source replication Source-replica replication	Multi-source replication Source-replica replication
Foreign keys	yes	no	no	no
Transaction concepts	ACID	Multi-document ACID Transactions with snapshot isolation	Atomic execution of command blocks and scripts and optimistic locking	ACID
Concurrency	yes	yes	yes	yes
Durability	yes	yes	yes	yes
In-memory capabilities	yes	yes	yes

VoltDB는 일부 세부적인 항목을 제외하면, 전통적인 RDBMS와 상당히 비슷한 기능을 제공한다.
이는 RDB의 핵심 컨셉인 ACID transaction를 지원하기 때문이다.

VoltDB vs MongoDB (performance)

분산 환경에서 ACID transaction를 지원하는 두 DB의 성능을 비교 (MongoDB는 개념적인 ACID를 지원한다)

Test Env

CPUs: 2
RAM: 4GB
HDD: 8GB
OS: Windows Server 2016

Test Data

RDB 기준 Data 구조

Connection 개수를 변경하면서 테스트를 진행한다.

총 5 종류의 데이터 셋을 준비했으며, 개념적으로 같은 데이터를 각 DB에 맞게 구성했다.
Size로 보았을 때 MongoDB의 data overhead가 더 큰 것을 볼 수 있다.

CPU Usage

전체적으로 CPU 사용량은 VoltDB가 MongoDB보다 성능 상 이점이 있는 것을 볼 수 있다.
이는 VoltDB의 Stored Procedure의 execute가 보다 효율적인 것이라 예상해 볼 수 있다.
하지만, connection만 늘어나는 상황에서는 voltDB는 각 request를 serial하게 처리하기 때문에 상대적으로 좋지 못한 performance를 보인다.

Insert Test

Insert는 MonogoDB가 안정적인 성능을 보장하는 것을 볼 수 있다.
이는 insert 되는 Data의 partition 선정 등 작업에서 버든이 있을 것으로 추정된다.

Update / Delete Test

Update는 전반적으로 voltDB가 안정적으로 좋은 퍼포먼스를 보여준다.
이는 update를 위해서 전체 컬랙션을 full-scan하는 경우가 있기 때문에 MongoDB는 transaction처리를 위한 비효율이 발생하는 것으로 예상된다.
물론 index를 통해 성능 보정이 가능할 것이다.
반면 VoltDB는 RDB의 특성으로 인하여 transaction 처리에 이점을 가지며, 성능의 차이를 보인다.

VoltDB vs MongoDB 결론

기본적인 CPU 사용량은 VoltDB가 더 효율적이며, transaction 처리 성능에 큰 이점을 가진다.
하지만 대량 / 고부하 insert는 MongoDB가 더 좋은 결과를 보였다.
이에 VoltDB는 Schema가 정해져 있으며, update가 빈번하게 일어나며, transaction처리가 필요한 요구사항에서 최적의 성능을 낼 수 있음을 확인할 수 있다.

Conclusion

전통적인 RDBMS를 대체하는 상황

update가 빈번하게 일어나며, insert가 상대적으로 적은 상황
schema가 과도하게 복잡하지 않으며, single partition execute로 대부분의 쿼리가 가능한 상황
scale-out이 필요할 정도의 부하가 일어나는 상황

NoSQL을 대신할 수 있는 상황

ACID Transaction이 필요한 상황

총평

VoltDB는 ACID를 지원하는 Database이다.
전통적인 RDBMS의 빈번한 locking, latching의 비효율성을 개선하며, scale-out을 통한 수평적 확장을 효율적으로 보장한다.
기본적으로 update / delete에 큰 이점을 가지고 있으며, insert / select 또한 전통 RDBMS보다 좋은 성능을 낼 수 있다.
하지만 tradeoff 사항으로 복잡한 구조의 데이터를 쿼리하거나 큰 record를 쿼리하는 성능에 불이익을 가진다.
또한 DB의 특성을 고려하여 설계가 필요하며, 이는 stored procedure 기반 아키텍처, partition을 고려한 data 구조 등을 말한다.

결론적으로 RDB를 대체하거나 NoSQL을 대체하기에는 범용성이 부족하며
application에서 상당한 책임을 가져가는 요즘 추세에서 사용할 가치가 있는지는 의문이 있다.

REFERENCE

https://docs.voltdb.com/UsingVoltDB/

https://www.odbms.org/wp-content/uploads/2013/11/VoltDBTechnicalOverview.pdf

https://www.researchgate.net/publication/371731207_A_Performance_Comparison_between_Modern_Relational_Database_VoltDB_and_Graph_NoSQL_Database_Neo4j

https://db-engines.com/en/system/MariaDB%3BMongoDB%3BRedis%3BVoltDB

ksqlDB 란

북극곰은콜라 — Mon, 27 May 2024 21:48:31 +0900

ksqlDB란?

2017년 Confluent에서 오픈소스로 공개한 이벤트 스트리밍 데이터베이스이다.
Kafka Streams + Kafka Connect로 구성되며, SQL을 인터페이스로 채용했다.
이는 스트림처리 및 데이터 통합을 단순화시키는 효과를 가진다.

특징

대화형 작업환경을 제공
SQL로 토폴로지를 표현하여 유지보수성 향상
SQL 인터페이스로 인한 “상대적”으로 낮은 진입 장벽
connect와 streams를 한번에 관리하여 아키텍처를 단순화
Streams를 활용한 기능적 확장성을 제공
간편한 설치 및 클라우드 지원
데이터 탐색에 최적화

License

ksqlDB is licensed under the Confluent Community License.

Confluent Community License: https://www.confluent.io/ko-kr/confluent-community-license/

ksqlDB는 Confluent Community이며, 요약하자면 다음과 같다
1. 무단 변경 금지
2. 라이센스의 변경 금지
3. sublicensing 금지
기본적으로 무료 라이선스에 가깝다고 볼 수 있다.

배경 및 Idea

1. Kafka Streams + SQL

최초 ksqlDB는 Kafka Streams DSL의 가능성을 보고 시작되었으며 KSQL로 명명하여 시작된 프로젝트 었다.
핵심 아이디어는 전통적인 SQL 언어의 이점으로 Streams를 통해 data handling을 구성하는 것이다.
이는 Kafka에서 stream 되는 data를 무한 데이터로 볼 수 있다는 배경이 있다.
SQL을 차용한 배경에는 data handling에 최적화된 언어로, 오랜 기간 사용되며 우수성을 증명한 언어이기 때문이라는 이유가 있다.

최초 개발 당시 KSQL은 무한 데이터를 쿼리 하는 것에 초점이 맞추어져 있었다.
이에 SQL 문법에 방언(dialect)을 적용하는 방식으로 해결하고자 했다.
DDL 및 DML에 추가적인 키워드를 정의했으며, 이를 통해 data stream을 구성하고, 데이터를 쿼리 할 수 있도록 했다.

# DDL EX)
CREATE STREAM XXX (id bigint, date varchar, ...);
DROP STREAM IF EXISTS XXX;

# DML EX)
SELECT id FROM XXX;
INSERT INTO XXX (id, date) VALUES (1, '20240101');

2. ksqlDB로 발전

Kafka Streams가 발전하면서, KSQL로 구성할 수 있는 기능이 더 많아지게 되었다.
이에 따라 KSQL에 많은 기능이 추가되었으며 ksqlDB로 명칭을 변경했다.
그중 핵심이 되는 기능으로, Streams의 StateStore 기능이다.
Streams는 메모리 또는 RocksDB로 topic에 대한 Key-Value Store를 구성할 수 있게 되었다.

ksqlDB는 stateStore를 통해 data의 현재 상태를 쿼리 할 수 있는 기능이 추가되었고 query에 대한 type을 정의했다.
- push query: 무한 데이터를 조회하는 방식으로 업데이트되는 데이터를 지속적으로 푸시해 준다.
- pull query: 현재 상태를 조회하는 방식으로 키 기반으로 데이터를 조회할 수 있다.

# PULL QUERY EX)
CREATE TABLE YYY AS SELECT id, COUNT(id) AS FROM XXX GROUP BY date;
SELECT * FROM YYY;

3. Kafka Connect 통합

많은 비즈니스 요구사항은 data Streaming 뿐 아니라, sink와 source도 필요했다.
ksqlDB는 Kafka Connect와 병행되어 사용되었고, 이에 connect에 대한 통합을 요구하는 피드백이 많아졌다.
ksqlDB의 핵심 사상은 고수준 인터페이스를 통해 사용성의 향상이다.
따라서 Kafka Connect의 통합은 자연스럽게 개발되었다.
kafka connect의 sink, source connector를 구성하는 기능이 추가되었으며, 이를 ksqlDB ETL기능으로 명명되었다.

# Connect EX)
CREATE SOURCE CONNECTOR `jdbc-connector` WITH ("connector.class"="io.confluent.connect.jdbc.JdbcSourceConnector", ...);

ksqlDB vs RDBMS

유사점

Name	Desc
SQL Interface	ksqlDB는 SQL 문법, 파서, 실행 엔진을 포함하고 있다.
DDL, DML	ksqlDB의 SQL은 기존 SQL처럼 DDL과 DML로 나누어진다. DDL은 table 및 streams를 정의하고, DML은 Data handling을 할 수 있다.
Schema	name, type으로 정의되는 schema를 갖는다
내장함수 & 연산자	ksqlDB 또한 연산자 및 함수를 제공한다.

차별점

Name	Desc
Pull, Push Query	DDL, DML 외 ksqlDB는 쿼리를 PULL QUERY, PUSH QUERY로 나누어진다. 무한데이터를 쿼리하는 것인지, 상태를 쿼리하는 것인지로 나누어진다.
Not Simple Query	일반적이 RDBMS 처럼 쿼리를 위한 쿼리 기능은 지양한다. 쿼리는 하나의 stream이며, 목적성을 가진 쿼리만 작성한다.
Schema Management	ksqlDB는 Kafka 생태계의 Schema Registry를 활용하여, schema의 진화를 관리할 수 있다.
High-Availability & Fault-Tolerant	Kafka에서 보장하는 고가용성 및 장애 복구가 적용된다.
Eventually Consistency	Data Model은 결과적인 일관성을 베이스로 한다. event-driven architecture를 베이스로 설계되었기 때문

동작 원리

ksqlDB는 Kafka 생태계 메인제품인 Kafka Streams와 Kafka Connect를 활용하여 만들었다.
따라서 동작은 해당 제품의 원리를 따른다.
ksqlDB의 메인 동작은 SQL을 파싱 하여 각 제품의 기능을 사용해 사용자가 원하는 결과를 만드는 것이다.

구성요소

Name	Desc
ksqlDB Server	SQL Engine, Kafka Streams 등을 포함하며, 사용자의 요청을 수행하는 단위이다. 간단하게 ksqlDB Server 하나는 Kafka Streams Application 하나로 생각해도 무방하다. ksql.service.id로 각 인스턴스는 아이디를 설정할 수 있는데, 같은 아이디끼리 하나로 묶여서 동작하며, 이를 클러스터라고 부른다. ksql id는 consumerId와 같은 동작을 한다. 클러스터 내의 각 인스턴스는 Streams처럼 파티션을 나눠 갖고, 실행된다.
SQL Engine	SQL parser를 포함하고 있으며, 주요 기능은 SQL을 분석하고, Streams 토폴로지로 변환하는 것이다.
REST Service (Interface)	SQL Engine의 인터페이스이다. 사용자는 REST를 통해 SQL Engine과 상호작용 할 수 있다.
ksqlDB CLI	cli를 통해 사용자에게 SQL Engine과 상호작용 할 수 있는 Applicaiton이다.
ksqlDB UI	Confluent에서 제공하는 Web UI

ksqlDB 모드

Interactive mode (대화형)

사용자가 실시간으로 쿼리를 제출하며, ksqlDB Server가 해당 쿼리를 parsing 및 execute 한다.
모든 쿼리는 command topic이라는 internal-topic으로 publish 되며, 이는 클러스터 내 한번 실행됨을 의미한다.
정리하면, 모든 ksqlDB는 command topic을 subscribe 하고 있으며, 각각의 consumer설정과 partition설정을 통해 가져가서 SQL Engine에게 넘겨준다.

Headless mode (사전정의형)

REST API 등 실시간 입력을 차단하고, 사전정의 된 Query만 실행하는 모드이다.
기동 시 properties로 실행할 sql의 위치를 지정해줘야 한다.
속성은 queries.file로 정의한다.

KSQL Language

keywords

참고: https://docs.ksqldb.io/en/latest/reference/sql/appendix/#keywords

Name	Desc	Example
CREATE	create an object	CREATE STREAM rock_songs (artist VARCHAR, title VARCHAR) …
DROP	delete an object	DROP CONNECTOR <connector-name>;
ADD	add column	ADD (COLUMN)? identifier type;
SELECT FROM	query a stream or table	SELECT * FROM metrics EMIT CHANGES;
WHERE	filter records by a condition	SELECT * FROM pageviews WHERE pageid < 'Page_20'
INSERT INTO	insert new records in a stream/table	INSERT INTO <stream-name> ...
DELETE	remove a Kafka topic	DROP TABLE <table-name> DELETE TOPIC;
GROUP BY	group rows with the same values	SELECT regionid, COUNT(*) FROM pageviews GROUP BY regionid
HAVING	condition expression	GROUP BY card_number HAVING COUNT(*) > 3
JOIN	match records in streams/tables	CREATE TABLE t AS SELECT * FROM l INNER JOIN r ON l.ID = r.ID;
KEY	specify key column	CREATE TABLE users (userId INT PRIMARY KEY, …
EXPLAIN	show execution plan	EXPLAIN <query-name>; or EXPLAIN <expression>;
AS	alias a column, expression, or type
CASE, WHEN, THEN, ELSE, END	select a condition from expressions	SELECT CASE WHEN condition THEN result [ WHEN … THEN … ] … END
IF EXIST	test whether object exists	DROP STREAM IF EXISTS <stream-name>;
PRINT	output records in a topic	PRINT <topic-name> FROM BEGINNING;
PROPERTIES	list all properties	LIST PROPERTIES; or SHOW PROPERTIES;
QUERIES	list all queries	LIST QUERIES; or SHOW QUERIES;
TOPIC	specify a Kafka topic	DROP TABLE <table-name> DELETE TOPIC;
TOPICS	list all topics	LIST TOPICS; or SHOW TOPICS;
PARTITION BY	repartition a stream	PARTITION BY <key-field>
PARTITIONS	partitions to distribute keys over	CREATE STREAM users_rekeyed WITH (PARTITIONS=6) AS …
CONNECTOR	manage a connector	CREATE SOURCE CONNECTOR 'jdbc-connector' WITH( …
CONNECTORS	list all connectors	SHOW CONNECTORS;

Data Types

참고: https://docs.ksqldb.io/en/latest/reference/sql/data-types/

Type	Name	Storage size	range	Desc	Backing Java Type
Boolean	boolean			value representing true or false	java.lang.Boolean
Character	varchar, string			variable-length string	java.lang.String
Numeric	bytes			variable-length byte array	byte []
	int	4 bytes	-231 to 231-1	typical choice for integer	Integer
	bigint	8 bytes	-263 to 263-1	large-range integer	Long
	double	8 bytes	2-1074† to (2-2-52)·21023	variable-precision, inexact	Double
	decimal	value dependent	n/a	user-specified precision, exact	BigDecimal
Time	time			value representing a time of day in millisecond precision.	java.sql.Time
	date			value representing a calendar date independent of time zone.	java.sql.Date
	timestamp			value representing a point in time in millisecond precision without timezone information	java.sql.Timestamp
Compound	array			sequence of values of a single type	Java native array
	struct			a strongly typed structured data type	org.apache.kafka.connect.data.Struct
	map			a mapping of keys to values	java.util.map

ksqlDB 활용

INSTALL

// ksqlDB-server 설치
docker run -d  -p 127.0.0.1:8088:8088  -e KSQL_BOOTSTRAP_SERVERS=xxx.xxx.xxx.xxx:9092  -e KSQL_LISTENERS=http://0.0.0.0:8088/  -e KSQL_KSQL_SERVICE_ID=ksql_service_x confluentinc/ksqldb-server:0.29.0

// ksqlCli 설치 및 실행
docker run -it --net host confluentinc/ksqldb-cli ksql http://127.0.0.1:8088

ksqlDB는 Kafka의 consumer/producer와 같은 레이어이며 로컬에서 테스트 가능하다.
도커로 간편하게 설치 가능하며 내부 포트, bootstrap server, serviceid 정도 세팅했다.

ksqlDB Stream Test

1. topic 확인

ksql> show topics;
 Kafka Topic                                            | Partitions | Partition Replicas 
 ...                
 quickstart-avro-config                                 | 1          | 1                  
 quickstart-avro-offsets                                | 25         | 1                  
 quickstart-avro-status                                 | 5          | 1                  
 schema-changes.mysql                                   | 1          | 1                  
 schema-changes.mysql.event_history                     | 1          | 1                  
 survey.debezium                                        | 1          | 1                  
 survey.debezium.survey.event_history                   | 1          | 1                  
 test.ksql.1                                            | 1          | 1

test.ksql.1 토픽으로 Stream을 생성할 것이다.
해당 토픽은 사전 생성했다.

2. Create Stream

ksql> CREATE STREAM TEST_STREAM_1 (id VARCHAR KEY, desc STRING) WITH (KAFKA_TOPIC='test.ksql.1', VALUE_FORMAT='json');
CREATE STREAM TEST_STREAM_1 (id VARCHAR KEY, desc STRING) WITH (KAFKA_TOPIC='test.ksql.1', VALUE_FORMAT='json')
 Message        
 Stream created

심플한 stream을 생성했다.
stream 이름은 TEST_STREAM_1이며 schema는 id와 desc가 문자열이다.

3. INSERT DATA

ksql> INSERT INTO TEST_STREAM_1 VALUES ('a', 'test a');
INSERT INTO TEST_STREAM_1 VALUES ('a', 'test a')
ksql> INSERT INTO TEST_STREAM_1 VALUES ('b', 'test b');
INSERT INTO TEST_STREAM_1 VALUES ('b', 'test b')
ksql> INSERT INTO TEST_STREAM_1 VALUES ('c', 'test c');
INSERT INTO TEST_STREAM_1 VALUES ('c', 'test c')
ksql> INSERT INTO TEST_STREAM_1 VALUES ('a', 'test a');
INSERT INTO TEST_STREAM_1 VALUES ('a', 'test a')
ksql> INSERT INTO TEST_STREAM_1 VALUES ('a', 'test a');
INSERT INTO TEST_STREAM_1 VALUES ('a', 'test a')

간단하게 Data를 insert 할 수 있다.

4. PUSH Query

# no data (cause by offset properties)
ksql> SELECT * FROM TEST_STREAM_1 EMIT CHANGES;
+----------------------------------------+----------------------------------------+
|ID                                      |DESC                                    |
+----------------------------------------+----------------------------------------+
# set offset reset
ksql> set 'auto.offset.reset' = 'earliest';
Successfully changed local property 'auto.offset.reset' to 'earliest'. Use the UNSET command to revert your change.
# SELECT data
ksql> SELECT * FROM TEST_STREAM_1 EMIT CHANGES;
+----------------------------------------+----------------------------------------+
|ID                                      |DESC                                    |
+----------------------------------------+----------------------------------------+
|a                                       |test a                                  |
|b                                       |test b                                  |
|c                                       |test c                                  |
|a                                       |test a                                  |
|a                                       |test a                                  |

ksqlDB가 Streams를 사용하기 때문에, reset 정책도 당연하게 가져간다.
offset 정책을 earliest로 해서 모든 데이터를 초기 offset부터 읽을 수 있도록 설정할 수 있다.
결과 table이 기존 rdbms랑 다르게 밑줄이 없는 것은, data 가 streaming 되기 때문이다.

5. Query with GROUP BY

ksql> SELECT id, COUNT(*) AS CNT FROM TEST_STREAM_1 GROUP BY id EMIT CHANGES;
+-----------------------------------------+-----------------------------------------+
|ID                                       |CNT                                      |
+-----------------------------------------+-----------------------------------------+
|b                                        |1                                        |
|c                                        |1                                        |
|a                                        |3                                        |

STREAM에서 id를 기준으로 group by 하여 count 결과를 select 했다.
이는 PUSH Query로 조회했으며, 실시간으로 CNT가 반영되는 것을 볼 수 있다.

6. drop stream

ksql> drop stream TEST_STREAM_1;
 Message
----------------------------------------------------------
 Source `TEST_STREAM_1` (topic: test.ksql.1) was dropped.
----------------------------------------------------------
ksql> SHOW STREAMS;
 Stream Name | Kafka Topic | Key Format | Value Format | Windowed
------------------------------------------------------------------
------------------------------------------------------------------

간단하게 STREAM을 삭제할 수 있다.

ksqlDB Table Test

1. CREATE Table

ksql> CREATE TABLE TEST_TABLE_1 (id VARCHAR PRIMARY KEY, desc STRING) WITH (KAFKA_TOPI
C='test.ksql.1', VALUE_FORMAT='json');
 Message
---------------
 Table created
---------------
ksql> SHOW TABLES;
 Table Name   | Kafka Topic | Key Format | Value Format | Windowed
-------------------------------------------------------------------
 TEST_TABLE_1 | test.ksql.1 | KAFKA      | JSON         | false
-------------------------------------------------------------------

Simple하게 테이블을 생성했다.

2. SELECT Data

ksql> set 'auto.offset.reset' = 'earliest';
Successfully changed local property 'auto.offset.reset' to 'earliest'. Use the UNSET command to revert your change.
ksql> SELECT * FROM TEST_TABLE_1 EMIT CHANGES;
+-----------------------------------------+-----------------------------------------+
|ID                                       |DESC                                     |
+-----------------------------------------+-----------------------------------------+
|b                                        |test b                                   |
|c                                        |test c                                   |
|a                                        |test a                                   |

STREAM과 다르게 pk로 데이터가 override 된 것을 확인할 수 있다.

Extend KSQL Guide

SubQuery

아쉽게도 ksql은 서브쿼리를 지원하지 않으며, 현재 이에 관련된 개발 로드맵은 없다.
ksqlDB는 subQuery를 통한 복잡도는 프로젝트 성격 상 맞지 않다고 판단했으며
SubQuery가 아닌 여러 Query를 Kafka로 통합하는 방향을 지향하고 있다.

Join

KSQL의 join은 기존 Join과 다른 양상을 보인다.
이는 Source가 되는 Record의 structure가 Stream 또는 Table로 나누어지기 때문이다.
ksqlDB 진영에서 JOIN의 의미는 UPSTREAM의 데이터를 특정 기준으로 합쳐서 DOWNSTREAM을 생성하는 것이다.
따라서 PULL Query로는 JOIN 할 수 없다.
// Pull queries don't support JOIN clauses.

종류

JOIN은 3종류가 있다.
INNER JOIN: 양쪽 Record의 키가 같을 때 사용할 수 있는 JOIN
LEFT JOIN: LEFT Record를 기준으로 downStream을 형성한다. 즉 FROM 절의 record가 들어올 때 downStream record를 생성하며, join 할 대상이 없는 경우 null이 된다.
FULL JOIN: 양쪽 모두의 Record Stream을 받아서 downStream을 형성한다. 또한 JOIN 할 대상이 없다면 null이 된다.

Full Flow Example 참고: https://docs.ksqldb.io/en/latest/developer-guide/joins/join-streams-and-tables/

제약사항

Support Combination	Support JOIN Function	Etc
Stream - Stream	INNER JOIN LEFT JOIN FULL JOIN	Stream간의 JOIN은 Window 설정을 해야한다. 이는 Stream은 무한하기 때문에, JOIN 시점에 전체 데이터를 알 수 있는 기준이 없기 때문
Stream - Table	INNER JOIN LEFT JOIN	Table은 PK 컬럼만 JOIN에 사용할 수 있다. 이는 KTable이 repartition이 불가하기 때문이다. 또한 최근 지원되는 Multi-PK의 경우 그 중 하나만 선택해서 JOIN이 가능하다. 즉 JOIN … ON … AND는 불가하다.
Table - Table	INNER JOIN LEFT JOIN FULL JOIN

JOIN의 큰 조건은 두 대상의 파티션 수가 같아야 하며, 동일 파티션 어싸이너를 가져야 한다.
이는 key를 통한 JOIN을 할 때 파티션 매칭을 위한 것이다.
또한 JOIN KEY는 모두 동일 데이터 타입이어야 한다.

N-Way Joins

CREATE STREAM joined AS 
  SELECT * 
  FROM A
    JOIN B ON A.id = B.product_id
    JOIN C ON A.id = C.purchased_id;

최신 버전 ksqlDB는 여러 Stream / Table의 JOIN을 지원한다.
제약사항으로 JOIN 구성 중 STREAM, TABLE 모두 있다면 FULL JOIN은 지원하지 못한다.

ksqlDB Java Client

참고: https://docs.ksqldb.io/en/latest/developer-guide/ksqldb-clients/java-client/

ksqlDB를 Java Applicaiton에서 사용할 수 있도록, Confluent에서 Java Client Library를 제공한다.

Gradle

implementation 'io.confluent.ksql:ksqldb-api-client:7.5.3'

Client init

ClientOptions options = ClientOptions.create()
    .setHost(KSQLDB_SERVER_HOST)
    .setPort(KSQLDB_SERVER_HOST_PORT);
Client client = Client.create(options);
// Send requests with the client by following the other examples
// Terminate any open connections and close the client
client.close();

Client는 host, port로 간단하게 생성할 수 있다.

Client

public interface Client {
  /**
   * Executes a query (push or pull) and returns the results one row at a time.
   * 
   * <p>This method may be used to issue both push and pull queries, but the usage 
   * pattern is better for push queries. For pull queries, consider using the 
   * {@link Client#executeQuery(String)} method instead.
   *
   * <p>If a non-200 response is received from the server, the {@code CompletableFuture} will be
   * failed.
   *
   * @param sql statement of query to execute
   * @return a future that completes once the server response is received, and contains the query
   *         result if successful
   */
  CompletableFuture<StreamedQueryResult> streamQuery(String sql);
  ...
  /**
   * Executes a query (push or pull) and returns all result rows in a single batch, once the query
   * has completed.
   * 
   * <p>This method is suitable for both pull queries and for terminating push queries,
   * for example, queries that have a {@code LIMIT} clause. For non-terminating push queries,
   * use the {@link Client#streamQuery(String)} method instead.
   *
   * @param sql statement of query to execute
   * @return query result
   */
  BatchedQueryResult executeQuery(String sql);
  ...
}

여러 method를 지원한다.
그중 streamQuery()는 CompletableFuture로 실행결과에 대한 future를 받는 형태이며, PUSH Query에 권장되는 메서드이다.
executeQuery는 PULL Query에 적합하다. 또한 PUSH Query 중 LIMIT 등으로 끝이 있는 쿼리에도 사용할 수 있다.
그 외 INSERT 등 여러 메서드를 지원한다.
// 아쉽게도 Spring 진영에서 integration을 지원하고 있진 않다.

Conclusion

ksqlDB는 Kafka를 통한 Event-Driven System에서 고수준 인터페이스를 통해 Stream처리 및 source, sink를 구성할 수 있는 product이다.
기본적으로 SQL을 확장하여 인터페이스를 구성했으며, 상호작용을 위한 대화형 CLI, REST API를 제공한다.

Confluent에서 관리되고 있으며, kafka update에 맞춰 적극적인 업데이트가 이루어지고 있다.

활용방안

스팟 성 요구사항 대응

일시적으로 기존 비즈니스와 다른 요구사항이 발생했을 때 적은 비용으로 대응이 가능하다.
이는 Kafka의 장점을 손쉽게 활용할 수 있다.

Develop 환경에서 활용

개발 중 임시로 활용할 데이터 생성이나 기존 데이터를 복제하는 등 일시적인 stream 구성을 할 때 활용할 수 있다.
이는 개발 생산성을 올릴 수 있는 방안으로 생각된다.

잦은 변경이 예상되는 비즈니스

SQL 대화형 인터페이스 또는 UI로 Data Processing 로직 변경이 가능하기 때문에
잦은 변경이 예상되는 부분을 ksqlDB로 구성하여, 즉각적인 반영이 가능하다.

Data ETL

복잡한 비즈니스 없는 ETL 요구사항에 활용될 수 있다.
ksqlDB는 단순한 비즈니스를 구성하는데 큰 생산성 향상을 가져오며, 유지관리에도 용이한 장점이 있다.
이는 Kafka Connect + Schema Registry + Streams를 통합하여 제공하기 때문이며
데이터의 source + processing + sink를 한 번에 관리할 수 있기 때문이다.

REFERENCE

도서 - OREILLY의 Mastering Kafka Streams and ksqlDB

https://docs.ksqldb.io/en/latest/reference/sql/syntax/lexical-structure/

https://docs.ksqldb.io/en/latest/operate-and-deploy/installation/install-ksqldb-with-docker/

Java Reactive Streams Publisher / Subscriber 분석 (projectreactor)

북극곰은콜라 — Tue, 26 Mar 2024 20:24:14 +0900

개요

ReactibeStreams의 사상 및 목적 조사 및 Publisher / Subscriber의 실제 동작 확인
Java의 Reactive Programing의 구현 사항 및 동작 원리 분석

Reactive Programing 이란

정의

데이터 스트림의 구성 및 변화의 전파에 대한 선언적 프로그래밍 패러다임
이 패러다임을 도입하면 배열 또는 이벤트 스트림을 쉽게 표현할 수 있다.

목적

1. (비동기적인) 이벤트 처리를 표현 및 구현하기 위해
2. 데이터 스트림을 표현 및 구현하기 위해
3. 반응형 시스템을 구현하기 위해
즉 실시간 데이터의 변화를 효율적으로 반영하여 제공하기 위해 탄생했다.

원칙

1. Responsive: 시스템은 요청/호출에 대해 즉각 응답할 수 있어야 한다.
2. Resilient: 장애에 대한 탄력성이 요구됩니다. (복제, 봉쇄, 격리, 위임 등 기법 활용)
3. Elastic: 변화에 유연함이 요구 됩니다. 환경 및 작업량에 대응할 수 있어야 합니다.
4. Message Driven: 메시지에 기반한 시스템을 구성해야 합니다.

ReactiveStreams

개념

official page: https://www.reactive-streams.org/

- Reactive programing의 stream을 구성하기 위한 API를 정의한 단체, java 외 javascript, swift 등 여러 언어에 대한 API 및 Rule을 정의했다.
- 기본적으로 Reactive Programing을 표현하기 위해서 데이터 제공자(Publisher), 데이터 소비자(Subscriber)를 분리해 정의했다.
- Java의 reactive code API는 java9의 concurrent.Flow를 이용하여 정의되었다.
- 총 4개의 interface를 정의했으며, 각 구현에 Rule을 정의했으며 각각 publisher, Subscriber, Subscription, Processor이다.

Core IDEA

Data의 발행 주체와 소비 주체를 분리하는 것이 핵심 아이디어이다. Publisher는 Data 발행에 집중하고,. Subscriber는 데이터의 소비에 집중하는 구조를 지향했다.

실시간 Data 전파 구성 방식 (reactiveStreams 이전)

- PUSH 방식: Publisher가 Data를 발행할 수 있을 때 Subscriber에게 제공(호출)한다.
- POLL 방식: Subscriber가 소비할 준비가 되었을 때 Data를 요청한다.

문제점

1. PUSH 방식 문제: Subscriber의 상태와 관계없이 Data를 PUSH 하기 때문에, Subscriber의 문제를 대응하기 쉽지 않은 상황이 발생한다. 가령 subscriber의 지연이 발생했을 때 publisher는 이를 기다리거나, subscriber에게 buffer(or queue)를 두어서 해결해야 한다.
2. POLL 방식 문제: Publisher의 Data를 지속적으로 체크하기 위한 요청 오버헤드가 발생한다. 이는 시스템이 복잡하고 커질수록 트래픽이 증가하는 결과를 가져오며 비용이 증가하고, 안정성이 떨어진다.

해결

ReactiveStreams에서는 Publisher는 Data 제공만 관심을 가지고, Subscriber는 소비만 관심을 가진다. 이외 Data 전달에 대해서는 중간 계층인 Subscription을 두고 해결한다.
Publisher는 Data가 준비되면 각 Subscription에게 Data를 제공하고 Subscriber는 소비할 수 있을 만큼만 Subscription에게 제공받는다.
여기서 Backpressure라는 핵심 개념이 들어가는데, Subscriber는 소비할 수 있는 만큼 Subscription에게 request 하며, 데이터를 request 한 만큼 push 받는 개념이다. 이 개념을 통해서 Subscriber는 buffer 없이 Data를 안정적으로 제공받을 수 있다.

1. Publisher

public interface Publisher<T> {
    public void subscribe(Subscriber<? super T> s);
}

id	Rule
1	(Publisher->Subscriber의 onNext).count <= Subscriber.(subscription.request).totalcount onNext의 호출은 request된 element보다 작아야 한다.
2	Publisher는 onNext도중 subscription을 종료하고 onComplete, onError signal로 변경할 수 있다.
3	publisher가 제공하는 모든 signal은 seial(sync)해야 한다.
4	publisher의 오류 발생 시 onError signal을 주어야 한다.
5	publisher의 정상 종료 시 onComplete signal을 주어야 한다.
6	onError, onComplete signal 발생 시 subscription은 cancel로 간주한다.
7	terminate 상태일 시 더 이상 signal을 발생 시키면 안된다.
8	subscription이 cancel되면 subsciber에게 signal을 주면 안된다.
9	publisher의 subscribe 메서드는 아래 사항을 구현해야 한다. ● Subscription을 생성해야 한다. ● subscriber.onSubscribe(Subscription)를 호출해야 한다. ● throw 없이 종료 되어야 한다. (parameter가 null인 경우 제외) ● 에러 발생 시 onError를 호출 해야한다. (onSubscribe 호출 이후)
10	다른 Subscriber에 대해서 여러번 호출 될 수 있어야 한다.
11	여러 subscriber를 지원하는 것이 권장된다.

Publisher는 Subscription 및 Data의 생성을 담당한다.
Subscription은 subscribe 호출 시 생성하며, 호출 당 하나의 subscription을 만든다.
Data는 자체적으로 생성하거나 상위 스트림에서 받을 수 있어야 한다.

2. Subscriber

public interface Subscriber<T> {
    public void onSubscribe(Subscription s);
    public void onNext(T t);
    public void onError(Throwable t);
    public void onComplete();
}

id	Rule
1	onSubscribe(Subscription)에서 Subscription.request(long n)로 onNext signal을 받아야 한다.
2	Publisher의 responsivity를 저해할 수 있다면 async하게 signaling을 권장
3	onComplete() 및 onError() 메서드에서 subscription또는 publisher를 호출하면 안된다.
4	onComplete 및onError는 subscription이 cancel되었다고 간주한다.
5	subscription이 진행된 후 onSubscribe() 요청의 subscription은 cancel()한다.
6	subscription이 필요 없어지는 경우 cancel()해야 한다.
7	publisher가 제공하는 모든 signal의 serial(sync) 여부를 확인해야 한다.
8	pending된 element가 있을 수 있으니 cancel() 호출 이후 onNext()를 받을 수 있어야 한다.
9	Subscription.request() 호출 전에 onComplete 신호를 받을 수 있어야 한다.
10	Subscription.request() 호출 전에 onError 신호를 받을 수 있어야 한다.
11	signal 처리는 각각 수행되어야 합니다.
12	onSubscribe()는 최대 한번 호출 됩니다.
13	모든 메서드는 thrown 없이 정상 종료 되어야 합니다. 하지만 parameter가 null인 경우 nullPointException을 발생 시킵니다.

Subscriber는 Data 소비에 대한 기능을 담당한다.
publisher에게 subscribe(Subscriber)로 전달되면, onSubscribe가 한번 무조건 호출되며, 이때 Subscription에게 element를 request(n) 해야 한다.
이후 각 signal이 호출될 수 도 안 될 수 도 있다.

3. Subscription

public interface Subscription {
    public void request(long n);
    public void cancel();
}

id	Rule
1	request()와 cancel()은 Subscriber만 호출된다.
2	request()는 subscriber의 onNext, onSubscribe에서 호출된다.
3	request() 호출의 재귀 현상에 대한 제한을 두어야 한다.
4	request()는 최대한 지연 없이 구현되어야 합니다.
5	cancel()은 최대한 지연 없이 구현되어야 합니다.
6	cancel() 이후 호출되는 request()는 동작하면 안된다.
7	cancel() 이후 호출되는 cancel()은 동작하면 안된다.
8	cancel 되지 않은 상황에서 request()는 반복 호출 될 수 있다.
9	request(long n)에서 parameter <= 0 인 경우 onError를 IllegalArgumentException과 함께 발생 시킨다.
10	request()는 subscriber의 onNext를 sync하게 호출 한다 (cancel 되지 않았다면)
11	request()는 subscriber의 onComplete, onError를 sync하게 호출 한다 (cancel 되지 않았다면)
12	첫 cancel() 호출 시 publisher에게 signal 중단을 notify 해야 한다.
13	첫 cancel() 호출 시 publisher에게 subscriber에 대한 reference를 끊도록 notify 해야 한다.
14	cancel()이 호출되어 모든 subscription이 취소되면 publisher는 shutdown을 할 것이다.
15	cancel() 호출은 throw 없이 종료 되어야 한다.
16	request() 호출은 throw 없이 종료 되어야 한다.
17	request(n)의 n 개수는 Long.MAX_VALUE까지 지원해야 하며, Long.MAX_VALUE는 무한으로 인식

Subscription은 publisher와 Subscriber 사이에서 data flow(signaling)를 표현한다.
Publisher에 의해 subscribe() 될 때마다 하나씩 생성되며, 하나의 Subscriber와 연관된다.

4. Processor

public interface Processor<T, R> extends Subscriber<T>, Publisher<R> {
}

id	Rule
1	Subscriber와 Publisher의 Rule 모두 만족해야 합니다.
2	onError signal을 자체적으로 handling할 수 있지만, subscription을 cancel 해야 합니다.

Publisher + Subscriber

ProjectReactor에서 해당 인터페이스의 구현체들은 deprecated 되었다. (will be removed in 3.5)
https://github.com/reactor/reactor-core/issues/2431

ReactiveStreams Example

위 Rule을 바탕으로 간단한 예시 코드를 작성했다.
예시를 통해 Pub → Sub에 대한 전체적인 흐름을 파악하고, 각 요소들의 역할에 대해 설명하고자 한다.
(projectreactor가 구현한 Pub/Sub의 구현체인 Mono, Flux가 복잡하여 핵심 요약이 힘들다.)

구현 사항:
- publisher: random 한 int값을 max 개수만큼 생성한다.
- subscriber: n개 구독하여 element를 받을 때마다 더하는 구독자
- subscription: n개만큼 request 해서 내려주고, 많으면 cancel 하고 완료되면 complete, error는 error처리
- processor: 지정된 int 함수를 실행하면서 pub / sub 연결
명확한 flow 파악을 위해 전체적으로 sync 하게 구현했다.
Mono/Flux는 이를 비동기, 논블로킹, backpressure 등 개념을 적용해서 구현되어 있다.

Sample Implementation

SimplePublisher

public class SimplePublisher implements Publisher<Integer> {
  private final List<Integer> dataSources;
  private final Map<String, Subscription> subscriptions = new HashMap<>();

  private SimplePublisher(final List<Integer> dataSources) {
    this.dataSources = dataSources;
  }

  public static SimplePublisher create(final int maxCount) {
    return new SimplePublisher(
        IntStream.generate(() -> (int) (Math.random() * 100))
            .limit(maxCount)
            .boxed()
            .toList());
  }

  @Override
  public synchronized void subscribe(final Subscriber<? super Integer> subscriber) {
    System.out.println("[SimplePublisher] subscribe by: " + subscriber.getClass().getSimpleName());
    String id = UUID.randomUUID().toString();
    SimpleSubscription subscription = new SimpleSubscription(id, subscriber, this.dataSources, this);
    this.subscriptions.put(id, subscription);
    subscriber.onSubscribe(subscription);
  }

  public void cancelSignal(final String subscriptionId) {
    System.out.println("[SimplePublisher] cancelSignal");
    this.subscriptions.get(subscriptionId).cancel();
    this.deleteSubscription(subscriptionId);
  }

  public void deleteSubscription(final String subscriptionId) {
    System.out.println("[SimplePublisher] subscription removed");
    this.subscriptions.remove(subscriptionId);
  }
}

Publisher의 메인 역할
1. 구독자에 따른 Subscription 관리 (create, remove)
2. provide element
예시는 subscribe시마다 subscription을 생성하여 map으로 관리한다.
Publisher의 dataSource는 생성 시 결정 (like Mono.just())

SimpleSubscriber

@RequiredArgsConstructor
public class SimpleSubscriber implements Subscriber<Integer> {
  private final int subscribeCount;
  private int current = 0;

  @Override
  public void onSubscribe(final Subscription subscription) {
    System.out.println("[SimpleSubscriber] onSubscribe, subscription: " + subscription.getClass().getSimpleName());
    subscription.request(subscribeCount);
  }

  @Override
  public void onNext(final Integer t) {
    current += t;
    System.out.println("[SimpleSubscriber] next: " + t + ", current: " + this.current);
  }

  @Override
  public void onError(final Throwable throwable) {
    System.out.println("[SimpleSubscriber] error: " + throwable.getMessage());
  }

  @Override
  public void onComplete() {
    System.out.println("[SimpleSubscriber] complete, final: " + this.current);
  }
}

Subscriber의 역할
1. subscribe시 subscription을 통해 publisher로 element를 요청 (with count)
2. element가 올 때마다 처리
3. error 처리
4. complete 처리
예시는 생성자로 받은 maxCount만큼 subscription에게 요청한다.
element가 올 때 마다 값을 더하여 유지한다.
완료 시 지금까지 더한 값을 표시한다.

SimpleSubscription

@RequiredArgsConstructor
public class SimpleSubscription implements Subscription {
  private final String subscriptionId;
  private final Subscriber<? super Integer> subscriber;
  private final List<Integer> source;
  private final SimplePublisher parent;

  @Override
  public void request(final long n) {
    System.out.println("[SimpleSubscription] request n: " + n);
    try {
      this.source.stream().limit(n).forEach(subscriber::onNext);
      if (source.size() > n) {
        this.parent.cancelSignal(this.subscriptionId);
        return;
      }
      this.subscriber.onComplete();
      this.parent.deleteSubscription(this.subscriptionId);
    } catch (Exception e) {
      this.subscriber.onError(e);
    }
  }

  @Override
  public void cancel() {
    System.out.println("[SimpleSubscription] cancel");
  }
}

Subscription의 역할
1. request 받은 개수만큼 subscriber에게 제공 (onNext)
2. subscriber에게 complete signal 생성
3. subscriber에게 error signal 생성
4. publisher에게 cancel signal 생성
5. cancel처리
예시에서는 request시 publisher에게 제공받은 source를 subscriber에게 순차적으로 제공한다.
subscriber의 request에 따라서 자동으로 cancel을 publisher로 호출한다. (requestCount < elementCount)
완료 및 에러 발생 시 subscriber에게 signal 생성(호출)

SimpleProcessor

@RequiredArgsConstructor
public class SimpleProcessor implements Processor<Integer, Integer> {
  private final Function<Integer, Integer> addOne = i -> i + 1;
  private final Function<Integer, Integer> subOne = i -> i - 1;

  private final Publisher<Integer> delegatePublisher;
  private Subscriber<? super Integer> delegateSubscriber;
  private final String functionName;

  public static SimpleProcessor from(final Publisher<Integer> from, final String functionName) {
    return new SimpleProcessor(from, functionName);
  }

  @Override
  public void subscribe(final Subscriber<? super Integer> subscriber) {
    System.out.println("[SimpleProcessor] subscribe by: " + subscriber.getClass().getSimpleName());
    this.delegateSubscriber = subscriber;
    this.delegatePublisher.subscribe(this);
  }

  @Override
  public void onSubscribe(final Subscription subscription) {
    System.out.println("[SimpleProcessor] onSubscribe, subscription: " + subscription.getClass().getSimpleName());
    this.delegateSubscriber.onSubscribe(subscription);
  }

  @Override
  public void onNext(final Integer t) {
    System.out.println("[SimpleProcessor] next: " + t);
    this.delegateSubscriber.onNext(apply(t));
  }

  @Override
  public void onError(final Throwable throwable) {
    System.out.println("[SimpleProcessor] error: " + throwable.getMessage());
    this.delegateSubscriber.onError(throwable);
  }

  @Override
  public void onComplete() {
    System.out.println("[SimpleProcessor] complete");
    this.delegateSubscriber.onComplete();
  }

  private Integer apply(final int origin) {
    return switch (this.functionName) {
      case "addOne" -> this.addOne.apply(origin);
      case "subOne" -> this.subOne.apply(origin);
      default -> origin;
    };
  }
}

Processor는 publisher와 subscriber의 책임을 모두 가진다.
예시에서는 pub/sub을 delegation 하며, onNext 시 지정된 함수를 적용하여 내려주고 있다.
// Subscription 생성은 생략했다.

Sample Flow 분석

1. Publish → Subscribe Flow

// init Pub / Sub
SimplePublisher simplePublisher = SimplePublisher.create(5);
SimpleSubscriber simpleSubscriber = new SimpleSubscriber(5);

// use Pub / Sub
simplePublisher.subscribe(simpleSubscriber);

// log
[SimplePublisher] subscribe by: SimpleSubscriber
[SimpleSubscriber] onSubscribe, subscription: SimpleSubscription
[SimpleSubscription] request n: 5
[SimpleSubscriber] next: 11, current: 11
[SimpleSubscriber] next: 35, current: 46
[SimpleSubscriber] next: 32, current: 78
[SimpleSubscriber] next: 29, current: 107
[SimpleSubscriber] next: 94, current: 201
[SimpleSubscriber] complete, final: 201
[SimplePublisher] subscription removed

생성 및 구독 단계
- 시작 전 Element 5개를 제공하는 Publisher와 5개를 구독하여 처리할 Subscruber 인스턴스를 생성했다.
- publisher는 subscribe(Subscriber) 호출을 통해 전체적인 Flow를 관장할 Subscription을 생성한다.
- publisher는 Subscription 생성 후 subscriber에게 onSubscribe를 생성하며, 아직 데이터를 전달하진 않았다.
- subscriber는 onSubscribe() 호출받았으며 Subscription에게 onRequest()로 Element(Data) 발행을 요청한다.
- Subscription은 Subscriber의 각 signal handler를 호출한다.

Data processing 단계
- Subscription은 상황에 맞게 Subscriber의 onNext(), onError(), onComplete() 호출한다.
- Subscriber는 각 signal에 대한 처리를 한다.

2. with Cancel Flow

SimplePublisher simplePublisher = SimplePublisher.create(5);
simplePublisher.subscribe(new SimpleSubscriber(3));

[SimplePublisher] subscribe by: SimpleSubscriber
[SimpleSubscriber] onSubscribe, subscription: SimpleSubscription
[SimpleSubscription] request n: 3
[SimpleSubscriber] next: 44, current: 44
[SimpleSubscriber] next: 70, current: 114
[SimpleSubscriber] next: 60, current: 174
[SimplePublisher] cancelSignal
[SimpleSubscription] cancel
[SimplePublisher] subscription removed

Request보다 Element가 많을 시 cancel 요청을 보내서 subscription을 cancel 처리하는 예시이다.

3. Publish → Processor → Subscriber Flow

예시 프로세스:
1. 사용자는 processor객체를 parent publisher를 가지고 생성한다.
2. processor를 통해 subscribe()하면, processor는 자신을 publisher에게 subscriber로 넘긴다.
3. publisher는 processor를 subscriber로 간주하고 Subscription을 생성한다.
4. onSubscribe는 publisher → processor → subscriber 순으로 진행
5. subscriber는 subscription에게 request 한다.
6. onNext 등 signal은 Subscription → processor → subscriber로 진행
Processor는 Pub + Sub이며, 중간 비즈니스를 담당한다.
예시 Processor는 delegate 할 pub / sub을 받아서 onNext에만 개입하여 function을 execute 하는 역할을 가진다.

Sample Conclusion

전반적인 reactibestreams의 rule에 따른 구현은 위와 같이 구성할 수 있다.
이 구조는 Publisher나 Subscriber가 유연하게 확장될 수 있으며, backpressure 개념이 들어가 있다.
기존 push / poll 구조의 단점인 subscriber buffer 또는 periodic call 문제가 없이, data stream을 구성할 수 있다.
위 구성에 비동기적 동작 및 디테일을 붙이면 실시간 data처리가 가능한 backpressure 기반 stream이 구현된다.

ProjectReactor

reactivestreams의 구현한 프로젝트이다.
주요 구현으로는 Publisher, Subscriber, Subscription, processor(will be removed in 3.5)가 있다.
구현체 몇 가지를 살펴보며 설명을 진행하고자 한다.

projectreactor는 추가적으로 비동기처리를 지원하기 위한 scheduler를 정의하고 구현했다.
(scheduler 참고: https://p-bear.tistory.com/68)

MonoJust

Create형 Publisher

final class MonoJust<T> extends Mono<T> implements Fuseable.ScalarCallable<T>, Fuseable, SourceProducer<T>  {
	final T value;

	MonoJust(T value) {
		this.value = Objects.requireNonNull(value, "value");
	}
	...

	@Override
	public void subscribe(CoreSubscriber<? super T> actual) {
		actual.onSubscribe(Operators.scalarSubscription(actual, value));
	}
	...
}

Publisher를 “create” 할 수 있는 대표적인 구현체이다. (Mono.just(…))
생성자에서 단일 값을 받아 유지하며, Subscribe 시 해당 값으로 subscription을 생성하여 onSubscribe를 호출하는 것을 볼 수 있다.

MonoDefer

Deleagete형 Publisher

final class MonoDefer<T> extends Mono<T> implements SourceProducer<T> {
	final Supplier<? extends Mono<? extends T>> supplier;

	MonoDefer(Supplier<? extends Mono<? extends T>> supplier) {
		this.supplier = Objects.requireNonNull(supplier, "supplier");
	}

	@SuppressWarnings("unchecked")
	@Override
	public void subscribe(CoreSubscriber<? super T> actual) {
		Mono<? extends T> p;

		try {
			p = Objects.requireNonNull(supplier.get(), "The Mono returned by the supplier is null");
		}
		catch (Throwable e) {
			Operators.error(actual, Operators.onOperatorError(e, actual.currentContext()));
			return;
		}

		fromDirect(p).subscribe(actual);
	}
	...
}

상위 Publisher(Mono)를 생성자로 받아서 유지하며, subscribe 시 해당 publisher에게 subscribe를 위임한다. (위임 앞뒤로 추가 로직들을 수행한다.)
just와 달리 onSubscribe에 관여하지 않으며, 상위 스트림에 subscribe()를 연결하는 역할만 한다.

LamdaSubscriber

Execute UserFunction Subscriber

final class LambdaSubscriber<T> implements InnerConsumer<T>, Disposable {
	final Consumer<? super T>            consumer;
	final Consumer<? super Throwable>    errorConsumer;
	final Runnable                       completeConsumer;
	final Consumer<? super Subscription> subscriptionConsumer;
	final Context                        initialContext;
	volatile Subscription subscription;

    LambdaSubscriber(
			@Nullable Consumer<? super T> consumer,
			@Nullable Consumer<? super Throwable> errorConsumer,
			@Nullable Runnable completeConsumer,
			@Nullable Consumer<? super Subscription> subscriptionConsumer,
			@Nullable Context initialContext) {
		this.consumer = consumer;
		this.errorConsumer = errorConsumer;
		this.completeConsumer = completeConsumer;
		this.subscriptionConsumer = subscriptionConsumer;
		this.initialContext = initialContext == null ? Context.empty() : initialContext;
	}
    ...

	@Override
	public final void onSubscribe(Subscription s) {
		if (Operators.validate(subscription, s)) {
			this.subscription = s;
			if (subscriptionConsumer != null) {
				try {
					subscriptionConsumer.accept(s);
				}
				catch (Throwable t) {
					Exceptions.throwIfFatal(t);
					s.cancel();
					onError(t);
				}
			}
			else {
				s.request(Long.MAX_VALUE);
			}
		}
	}

	@Override
	public final void onComplete() {
		Subscription s = S.getAndSet(this, Operators.cancelledSubscription());
		if (s == Operators.cancelledSubscription()) {
			return;
		}
		if (completeConsumer != null) {
			try {
				completeConsumer.run();
			}
			catch (Throwable t) {
				Exceptions.throwIfFatal(t);
				onError(t);
			}
		}
	}

	@Override
	public final void onError(Throwable t) {
		Subscription s = S.getAndSet(this, Operators.cancelledSubscription());
		if (s == Operators.cancelledSubscription()) {
			Operators.onErrorDropped(t, this.initialContext);
			return;
		}
		if (errorConsumer != null) {
			errorConsumer.accept(t);
		}
		else {
			Operators.onErrorDropped(Exceptions.errorCallbackNotImplemented(t), this.initialContext);
		}
	}

	@Override
	public final void onNext(T x) {
		try {
			if (consumer != null) {
				consumer.accept(x);
			}
		}
		catch (Throwable t) {
			Exceptions.throwIfFatal(t);
			this.subscription.cancel();
			onError(t);
		}
	}
	...
}

일반적으로 Mono…subscribe(…) 로 method chain을 구성하면 생성되는 subscriber 구현체이다.
생성자로 각 signal 처리를 담당하는 consumer 또는 Runnable 받는다.
각 signal에 대응하는 로직이 있으면 실행 및 실행 결과에 대한 에러처리

ScalarSubscription

publish single element once syncronously

static final class ScalarSubscription<T> implements Fuseable.SynchronousSubscription<T>, InnerProducer<T> {
	final CoreSubscriber<? super T> actual;
	final T value;
	@Nullable
	final String stepName;
	volatile int once;

	ScalarSubscription(CoreSubscriber<? super T> actual, T value, String stepName) {
		this.value = Objects.requireNonNull(value, "value");
		this.actual = Objects.requireNonNull(actual, "actual");
		this.stepName = stepName;
	}

	@Override
	public void cancel() {
		if (once == 0) {
			Operators.onDiscard(value, actual.currentContext());
		}
		ONCE.lazySet(this, 2);
	}
	...

	@Override
	public void request(long n) {
		if (validate(n)) {
			if (ONCE.compareAndSet(this, 0, 1)) {
				Subscriber<? super T> a = actual;
				a.onNext(value);
				if(once != 2) {
					a.onComplete();
				}
			}
		}
	}
	...
}

Mono.just 등으로 생성되는 Subscription 중 하나이다.
하나의 element를 subscriber에게 전달하는 구독으로, 생성 시점에 element하나와 subscriber를 받는다.
request 호출 시 가지고 있는 element를 onNext로 내려주고, complete signal을 보낸다.

Conclusion

ReactiveStreams

기존 PUSH / POLL 방식의 한계인 subscriber buffer 또는 perodic call 이슈를 Backpressure를 통해 해결할 수 있도록 정의한 Interface 및 Rule

- Publisher: Data 발행에 관심을 가지고 있으며, Subscription을 생성 및 관리한다.
- Subscriber: Data 소비에 관심을 가지고 있으며, BackPressure 개념을 도입했다. 소비할 element 개수를 Subscription에게 request 하고, onNext, onComplete 등 signal handling function을 Subscription이 호출한다.
- Subscription: Pub / Sub의 Flow를 control 하는 역할을 가지고 있으며, publisher에게 data를 받을 수 있고, subscriber에게 request 개수대로 onNext 호출을 하는 등 작업을 한다.
- Processor: Publisher + Subscriber

ProjectReactor

ReactiveStreams의 Interface를 구현한 프로젝트
Method Chain으로 Data Pipeline(Stream)을 구성할 수 있도록 구현했다. 실제 동작은 ReactiveStreams의 사상을 따르며, Function들은 비동기(ExecutorService) 위에서 동작한다.
Webflux, RSocket 등 Data Pipeline을 비동기로 구성하는 lib/framework에서 Base로 사용된다.

REFERENCE

https://github.com/reactive-streams/reactive-streams-jvm

https://www.reactive-streams.org/

https://github.com/reactor/reactor-core

Spring Webflux with EventListener

북극곰은콜라 — Wed, 20 Mar 2024 20:33:10 +0900

개요

Spring framework에서 제공하는 eventListener 기능 설명 (4.2 이상 기준)
Webflux 환경에서 EventListener에 대한 Sample Code 제시

동작원리

Spring @EventListener

@Target({ElementType.METHOD, ElementType.ANNOTATION_TYPE})
@Retention(RetentionPolicy.RUNTIME)
@Documented
@Reflective
public @interface EventListener {
  @AliasFor("classes")
  Class<?>[] value() default {};

  @AliasFor("value")
  Class<?>[] classes() default {};

  String condition() default "";

  String id() default "";
}

Method를 target을 하는 Spring Annotation이다.
classes: handle Class 지정
condition: SqEL로 표현되는 조건 String
id: id부여
value == classes

ApplicationEventPublisher

@FunctionalInterface
public interface ApplicationEventPublisher {
  default void publishEvent(ApplicationEvent event) {
    this.publishEvent((Object)event);
  }

  void publishEvent(Object event);
}

Functional Interface로 event 발행을 위한 기능을 정의했다.
Spring은 해당 interface의 구현체를 Bean으로 관리하며, 내부 spring event publish 용으로 사용한다.
내부적으로 ApplicationEvent 객체를 통해 전파한다.

ApplicationContext

Spring Application이 기동 할 때 생성되는 Context는 기본적으로 ApplicationEventPublisher를 상속받는다.
그 외 EnvironmentCapable, ListableBeanFactory, HierarchicalBeanFactory, MessageSource, ResourcePatternResolver 등 interface도 상속받는다.

AbstractApplicationContext

@Override
public void publishEvent(ApplicationEvent event) {
	publishEvent(event, null);
}

protected void publishEvent(Object event, @Nullable ResolvableType eventType) {
	Assert.notNull(event, "Event must not be null");

	// Decorate event as an ApplicationEvent if necessary
	ApplicationEvent applicationEvent;
	if (event instanceof ApplicationEvent) {
		applicationEvent = (ApplicationEvent) event;
	}
	else {
		applicationEvent = new PayloadApplicationEvent<>(this, event);
		if (eventType == null) {
			eventType = ((PayloadApplicationEvent<?>) applicationEvent).getResolvableType();
		}
	}

	// Multicast right now if possible - or lazily once the multicaster is initialized
	if (this.earlyApplicationEvents != null) {
		this.earlyApplicationEvents.add(applicationEvent);
	}
	else {
		getApplicationEventMulticaster().multicastEvent(applicationEvent, eventType);
	}

	// Publish event via parent context as well...
	if (this.parent != null) {
		if (this.parent instanceof AbstractApplicationContext) {
			((AbstractApplicationContext) this.parent).publishEvent(event, eventType);
		}
		else {
			this.parent.publishEvent(event);
		}
	}
}

EventPublisher의 publishEvent(…)를 구현한 abstract class이다.
4.2부터 ApplicationEvent를 상속받지 않아도 event를 publish 할 수 있다.
이는 object를 PayloadApplicationEvent로 event(Object)를 한번 감싸기 때문이다.
사용자가 publish한 이벤트는 보통 PayloadApplicationEvent로 multicater의 multicastEvent(…)에 호출된다.

ApplicationEventMulticaster

Application에서 구현된 Listener들을 execute 하는 Interface
일반적으로 SimpleApplicationEventMulticaster 구현체가 사용된다.

SimpleApplicationEventMulticaster

@Override
public void multicastEvent(final ApplicationEvent event, @Nullable ResolvableType eventType) {
	ResolvableType type = (eventType != null ? eventType : resolveDefaultEventType(event));
	Executor executor = getTaskExecutor();
	for (ApplicationListener<?> listener : getApplicationListeners(event, type)) {
		if (executor != null) {
			executor.execute(() -> invokeListener(listener, event));
		}
		else {
			invokeListener(listener, event);
		}
	}
}

multicastEvent는 event에 맞는 ApplicationListener를 모두 순회하며 invoke 시킨다.
executor가 있으면 executor를 통해, 없으면 sync하게 invoke 된다.
executor는 AsyncConfigurer + @EnableAsync로 생성할 수 있다.
Listener는 Event class 및 resolver에 따라서 retrive 및 caching 된다.

Webflux Event Sample

문제상황

userService
  .getUser(req)
  .flatMap(userService::changePassword)
  .doOnNext(user -> 
    produceManager
      .send(user)
      .subscribeOn(Schedulers.boundedElastic())
      .subscribe()
  )
  ...

일반적으로 Webflux(Projectreactor)에서 별도의 Scheduler로 비동기처리를 위해서는
위와 같이 subscribeOn으로 scheduler를 지정하고 subscribe 별도로 호출한다.
하지만 business logic에 subscribe()를 호출하는 코드는 문제점을 가진다.
1. 가독성도 떨어진다.
2. 비동기로 실행되어, 의도되지 않은 코드에 대해 인지를 못할 수 있다.
3. 코드가 비대 해질수록 subscribe가 증가한다. 그에 따라 debug point가 증가하게 된다.

솔루션 제안

Spring Context의 EventListener를 Async 하게 사용한다.
이는 Event에 대한 Subscriber, Subscribe logic, Scheduler 등 비즈니스와 분리할 수 있다.
결론적으로 Event처리 비즈니스의 응집도를 높일 수 있다.

Event할당 처리를 위한 Async Executor 설정

@Configuration
@EnableAsync
public class Config implements AsyncConfigurer {
  @Override
  public Executor getAsyncExecutor() {
    return Executors.newFixedThreadPool(
        Math.max(1, Runtime.getRuntime().availableProcessors()),
        new DefaultThreadFactory("async-event"));
  }

  @Override
  public AsyncUncaughtExceptionHandler getAsyncUncaughtExceptionHandler() {
    return new SimpleAsyncUncaughtExceptionHandler();
  }
}

일반적인 processor 기반 fixed thread pool을 만든다.
해당 Executor는 listener를 통한 event의 invoke를 담당한다.

Event Handler 작성

@Component
public class EventHandler {
  private final WebClient webClient = WebClient.builder().build();

  @Async
  @EventListener
  public void handleEvent(final Event event) throws InterruptedException {
    // 비동기 처리 확인을 위한 임시 sleep
    Thread.sleep(1000);
    Mono.just(event.getPath())
        .doOnNext(path -> log.info("publish path: {}", path))
        .flatMap(path -> webClient
            .get()
            .uri("http://localhost:12345" + path)
            .retrieve()
            .bodyToMono(HashMap.class))
        .subscribe();
  }
}

Bean에 @Async, @EventListener를 통해 handler method를 작성한다.
Annotation 기반이기 때문에, 상대적으로 자연스럽게 handler method를 관리할 수 있다.

Business Example

@Service
@RequiredArgsConstructor
@Slf4j
public class BusinessService {
  private final ApplicationEventPublisher applicationEventPublisher;

  public void doSomething() {
    Mono.just(new Event("/1"))
        .doOnNext(applicationEventPublisher::publishEvent)
        .map(ev -> new Event("/2"))
        .doOnNext(applicationEventPublisher::publishEvent)
        .map(ev -> new Event("/3"))
        .doOnNext(applicationEventPublisher::publishEvent)
        .map(ev -> new Event("/4"))
        .doOnNext(applicationEventPublisher::publishEvent)
        .doOnNext(ev -> log.info("doSomething end"))
        .subscribe();
  }
}

Log

[           main] o.e.eventwebflux.send.BusinessService    : doSomething end
[async-event-3-3] o.e.eventwebflux.send.EventHandler       : publish path: /3
[async-event-3-1] o.e.eventwebflux.send.EventHandler       : publish path: /1
[async-event-3-2] o.e.eventwebflux.send.EventHandler       : publish path: /2
[async-event-3-4] o.e.eventwebflux.send.EventHandler       : publish path: /4

상대적으로 깔끔하게 비동기 Event 처리를 구현할 수 있다.
async executor에서 처리됨을 확인할 수 있다.

REFERENCE

https://github.com/spring-projects/spring-framework/issues/21025

https://github.com/spring-projects/spring-framework/issues/21831

[Kafka] Parallel Consumer

북극곰은콜라 — Tue, 19 Mar 2024 18:06:34 +0900

Parallel Consumer란?

Confulent.inc에서 개발한 Open Source로 consumer의 consume이 parallel 하게 동작하도록 구현했다.
주요 목적은 분산 Consume을 위해 partition이 과도하게 늘아나는 비합리성을 해결하기 위함이다.

Before

기존 Consumer의 구조는 Consume의 주체는 Single Thread로 동작한다.
1. Consumer는 설정된 size 만큼 message를 읽는다(consume).
2. 설정된 offset 전략에 따라서 모든 message 처리가 완료될 때 까지 blocking 한다.
위 그림은 consume 프로세스 중 delay 될 수 있는 상황을 도식화했다.
4번 message가 web request 이슈로 delay 되면 전체 consume 퍼포먼스가 낮아진다.

After

Parallel Consumer는 위 상황을 해소하기 위해 개발되었다.
목표는 consume을 parallel 하게 동작하여 하나의 파티션에 여러 consumer가 동작하는 효과를 보는 것이다.

Overview

- consumer가 consume을 병렬로 처리할 수 있도록 Thread Pool을 관리한다.
- offset 관리를 위해 Offset Storage에 완료된 offset이 update 된다.
- Offset Commiter가 비동기로 완료된 offset을 선정하여 commit 한다.

ParallelConsumerOptions

Order

public enum ProcessingOrder {
    UNORDERED,
    PARTITION,
    KEY
}

ParallelConsumer는 순서보장 관련하여 3가지 옵션을 지원한다.
- UNORDERED: 순서보장 없이 모든 Key에 대해서 shard를 생성
- PARTITION: 파티션 단위로 shard를 생성, 파티션단위로 순서보장
- KEY: KEY 단위로 shard를 생성하여 key별 순서를 보장
// default order: KEY

Shard란?
Local에서 생성되는 Queue로 worker에게 할당할 work를 큐잉 한다.
자세한 사항은 후술

CommitMode

public enum CommitMode {
    PERIODIC_TRANSACTIONAL_PRODUCER,
    PERIODIC_CONSUMER_SYNC,
    PERIODIC_CONSUMER_ASYNCHRONOUS
}

CommitManager가 수행할 commit 전략에 대한 설정
- PERIODIC_TRANSACTIONAL_PRODUCER: Streams 등 consume->produce에 transaction을 지원하는 commit 전략
- PERIODIC_CONSUMER_SYNC: 주기적으로 sync 하게 commit을 수행
- PERIODIC_CONSUMER_ASYNCHRONOUS: async 하게 commit 요청을 보냄, 속도가 제일 빠름
// default commitMode: PERIODIC_CONSUMER_ASYNCHRONOUS
// default auto commit interval ms: 5000ms

InvalidOffsetMetadataHandlingPolicy

public enum InvalidOffsetMetadataHandlingPolicy {
    FAIL,
    IGNORE
}

offset handling 도중 에러가 발생한 상황의 정책 설정
- FAIL: 발생 시 shutdown
- IGNORE: 발생 시 무시
// default: FAIL

기타

private final Duration sendTimeout = Duration.ofSeconds(10);
private final Duration offsetCommitTimeout = Duration.ofSeconds(10);
private final Integer batchSize = 1;
private final Duration thresholdForTimeSpendInQueueWarning = Duration.ofSeconds(10);
private final int maxFailureHistory = 10;
public final Duration shutdownTimeout = Duration.ofSeconds(10);
public final Duration drainTimeout = Duration.ofSeconds(30);
public final int messageBufferSize;

기타 적용 가능한 설정들

동작원리

전체적인 동작과정은
1. Poll Task가 executor로 pooling 되어 broker로부터 record를 poll 함
2. poll 된 record를 mailbox(BlockingQueue)로 add
3. control Task가 executor로 pooling 되어 commit 트리거 및 userFunction submit을 담당
4. OffsetCommitter가 offset처리를 담당
5. userFunction이 recordContext와 함께 처리됨 (workerThreadPool)

ParallelConsumer

라이브러리의 핵심이 되는 interface이다.
일반적으로 사용자는 ParallelStreamProcessor의 poll 메서드를 통해 interact 한다.

Setup Parallel Consumer

ParallelStreamProcessor<String, String> setupParallelConsumer() {
    Consumer<String, String> kafkaConsumer = getKafkaConsumer();
    Producer<String, String> kafkaProducer = getKafkaProducer();

    var options = ParallelConsumerOptions.<String, String>builder()
            .ordering(KEY)
            .maxConcurrency(1000)
            .consumer(kafkaConsumer)
            .producer(kafkaProducer)
            .build();

    ParallelStreamProcessor<String, String> eosStreamProcessor =
            ParallelStreamProcessor.createEosStreamProcessor(options);

    eosStreamProcessor.subscribe(of(inputTopic));

    return eosStreamProcessor;
}

공식 parallelConsumer Setup example이다.
일반적으로 ParallelEoSStreamProcessor.class를 사용하며, Reactor 환경에서는 ReactorProcessor.class를 생성하여 사용한다.
producer는 생략 가능하며, 순수 consumer로 사용할 수 있다.

ParallelEoSStreamProcessor.class → poll(…)

@Override
public void poll(Consumer<PollContext<K, V>> usersVoidConsumptionFunction) {
    Function<PollContextInternal<K, V>, List<Object>> wrappedUserFunc = (context) -> {
        log.trace("asyncPoll - Consumed a consumerRecord ({}), executing void function...", context);

        carefullyRun(usersVoidConsumptionFunction, context.getPollContext());

        log.trace("asyncPoll - user function finished ok.");
        return UniLists.of(); // user function returns no produce records, so we satisfy our api
    };
    Consumer<Object> voidCallBack = ignore -> log.trace("Void callback applied.");
    supervisorLoop(wrappedUserFunc, voidCallBack);
}

public static <PARAM> void carefullyRun(Consumer<PARAM> wrappedFunction, PARAM userFuncParam) {
    try {
        wrappedFunction.accept(userFuncParam);
    } catch (Throwable e) {
        throw new ExceptionInUserFunctionException(MSG, e);
    }
}

기본 구현체인 ParallelEoSStreamProcessor의 poll 메서드의 코드이다.
PollContext의 consumer를 parameter로 받고 wrapping 하여 supervisorLoop() 함수로 execute 시킨다.

PollContext<K, V>

public class PollContext<K, V> implements Iterable<RecordContext<K, V>> {
  protected Map<TopicPartition, Set<RecordContextInternal<K, V>>> records = new HashMap<>();
  ...
}

PollContext는 한 번에 poll 한 record를 context와 함께 가진 클래스이다.
사용자는 poll 정책에 따라서 record 1개 또는 여러 개 받아서 처리할 수 있다.

AbstractParallelEoSStreamProcessor.class → supervisorLoop(…)

protected <R> void supervisorLoop(Function<PollContextInternal<K, V>, List<R>> userFunctionWrapped, Consumer<R> callback) {
    ...
    // broker poll subsystem
    brokerPollSubsystem.start(options.getManagedExecutorService());

    ExecutorService executorService;
    try {
        executorService = InitialContext.doLookup(options.getManagedExecutorService());
    } catch (NamingException e) {
        ...
    }


    // run main pool loop in thread
    Callable<Boolean> controlTask = () -> {
        ...
        while (state != CLOSED) {
            log.debug("Control loop start");
            try {
                controlLoop(userFunctionWrapped, callback);
            } catch (InterruptedException e) {
                ...
            }
        }
        log.info("Control loop ending clean (state:{})...", state);
        return true;
    };
    Future<Boolean> controlTaskFutureResult = executorService.submit(controlTask);
    this.controlThreadFuture = Optional.of(controlTaskFutureResult);
}

위 함수는 poll task와 handle with userFunction task를 execute 하는 기능을 가진다.
이는
1. start poll task
2. start control(userFunction) task
- executorService를 lookup 하거나 생성한다. (정책에 따라서)
- controlLoop() 함수를 호출하는 task(callable)을 만든다.
- executorService로 submit 한다.
로 요약할 수 있다.

Poll Task 관련

BrokerPollSystem.class
public void start(String managedExecutorService) {
    ...
    Future<Boolean> submit = executorService.submit(this::controlLoop);
    ...
}

private boolean controlLoop() throws TimeoutException, InterruptedException {
    ...
    try {
        while (runState != CLOSED) {
            handlePoll();
            ...
        }
        ...
}

private void handlePoll() {
    ...
    if (runState == RUNNING || runState == DRAINING) { // if draining - subs will be paused, so use this to just sleep
        var polledRecords = pollBrokerForRecords();
        ...

        if (count > 0) {
            ...
            pc.registerWork(polledRecords);
        }
    }
}

private EpochAndRecordsMap<K, V> pollBrokerForRecords() {
    ...
    ConsumerRecords<K, V> poll = consumerManager.poll(thisLongPollTimeout);

    return new EpochAndRecordsMap<>(poll, wm.getPm());
}

// private final BlockingQueue<ControllerEventMessage<K, V>> workMailBox = new LinkedBlockingQueue<>();
public void registerWork(EpochAndRecordsMap<K, V> polledRecords) {
    ...
    workMailBox.add(ControllerEventMessage.of(polledRecords));
}

poll task는 task별로 mailbox라는 Queue에 poll 한 결과(recordContext)를 add 하는 작업이다.
mailbox는 Threadsafe 한 blocking queue이며, control task에서 꺼내서 userFunction에서 사용된다.

AbstractParallelEoSStreamProcessor.class → controlLoop(...)

protected <R> void controlLoop(Function<PollContextInternal<K, V>, List<R>> userFunction,
                                   Consumer<R> callback) throws TimeoutException, ExecutionException, InterruptedException {
    ...
    if (shouldTryCommitNow) {
        // offsets will be committed when the consumer has its partitions revoked
        commitOffsetsThatAreReady();
    }

    // distribute more work
    retrieveAndDistributeNewWork(userFunction, callback);

    // run call back
    log.trace("Loop: Running {} loop end plugin(s)", controlLoopHooks.size());
    this.controlLoopHooks.forEach(Runnable::run);

    ...
}

control task는 크게 3가지 역할을 가진다.
1. offset처리가 필요한지 체크해서 OffsetCommitter(BrokerPollSystem)에게 commit 트리거
2. userFunction 실행
3. callback 처리

성능

performance measurement by Confluent

- A random processing time between 0 and 5ms
- 10,000 messages to process
- A single partition (simplifies comparison - a topic with 5 partitions is the same as 1 partition with a keyspace of 5)
- Default ParallelConsumerOptions
- maxConcurrency = 100
- numberOfThreads = 16

Ordering	Number of keys	Duration	Note
Partition	20 (not relevant)	22.221s	This is the same as a single partition with a single normal serial consumer, as we can see: 2.5ms avg processing time * 10,000 msg / 1000ms = ~25s.
Key	1	26.743s	Same as above
Key	2	13.576s
Key	5	5.916s
Key	10	3.310s
Key	20	2.242s
Key	50	2.204s
Key	100	2.178s
Key	1,000	2.056s
Key	10,000	2.128s	As key space is t he same as the number of messages, this is similar (but restricted by max concurrency settings) as having a single consumer instance and partition per key. 10,000 msgs * avg processing time 2.5ms = ~2.5s.
Unordered	20 (not relevant)	2.829s	As there is no order restriction, this is similar (but restricted by max concurrency settings) as having a single consumer instance and partition per key. 10,000 msgs * avg processing time 2.5ms = ~2.5s.

Key 1개 + order == Single Thread이다.
key의 개수가 Thread Count(16)까지 유의미한 처리 속도를 보이며, 그 이후는 큰 차이를 보이지 않는다.
사실상 Key >= Thread Count 인 경우와 unordered는 성능 향상을 보이며, 동일한 퍼포먼스를 보인다고 볼 수 있다.

performance measurement by Naver

성능 측정 시 2 consumer(parallel), 2 partition이 8 consumer(일반), 8 partition과 유사한 성능을 보였다.

Conclusion

Parallel Consumer는 기존 Consumer에 병렬 처리를 더한 구현체이다.
유의미한 성능 향상을 보이지만, 관리포인트(config)가 늘어난다.
기본적으로 partition의 key에 대한 예측 및 관리가 필요하다.

정리하자면
- 도입 시 key 예측 및 추가적인 config 등 관리포인트가 늘어난다.
- 고부하 상황이 아니라면 유의미한 성능 향상을 기대할 수 없다.
- Conumser 교체, 추가적인 key 관리 (estimation)만 하면 되기 때문에 추후 도입이 용이하다.
// 메인 비즈니스의 변경 없이 도입 가능
따라서 partition을 늘리기 부담스러운 고부하 상황에서 도입하는 것이 타당할 것으로 판단된다.

REFERENCE

https://github.com/confluentinc/parallel-consumer

https://d2.naver.com/helloworld/7181840

TURN Protocol (+ STUN Message)

북극곰은콜라 — Mon, 18 Mar 2024 19:48:32 +0900

TURN 이란?

정의

Traversal Using Relays around NAT의 약자이다.
TURN protocol은 STUN 프로토콜의 확장으로 Direct Communication이 불가 한 상황에서, relay를 통해 두 연결을 제공해주는 역할을 가진다.

배경

NAT 뒤의 HOST로 hole punching을 통해 통신이 가능하다. 하지만, 두 host 모두 NAT 뒤에 있으며, 적절한 설정이 없으면 이 또한 불가 하다.
또는 엔터프라이즈 환경에서 UDP 통신 자체가 불가 할 수 도 있다.
이를 해결하기 위해, TURN 서버에서 두 client의 통신을 relay 해주며, 통신이 가능하게 한다.

Overview

                                    Peer A
                                    Server-Reflexive    +---------+
                                    Transport Address   |         |
                                    192.0.2.150:32102   |         |
                                        |              /|         |
                      TURN              |            / ^|  Peer A |
   Client's           Server            |           /  ||         |
   Host Transport     Transport         |         //   ||         |
   Address            Address           |       //     |+---------+
198.51.100.2:49721  192.0.2.15:3478     |+-+  //     Peer A
           |            |               ||N| /       Host Transport
           |   +-+      |               ||A|/        Address
           |   | |      |               v|T|     203.0.113.2:49582
           |   | |      |               /+-+
+---------+|   | |      |+---------+   /              +---------+
|         ||   |N|      ||         | //               |         |
| TURN    |v   | |      v| TURN    |/                 |         |
| Client  |----|A|-------| Server  |------------------|  Peer B |
|         |    | |^      |         |^                ^|         |
|         |    |T||      |         ||                ||         |
+---------+    | ||      +---------+|                |+---------+
               | ||                 |                |
               | ||                 |                |
               +-+|                 |                |
                  |                 |                |
                  |                 |                |
         Client's                   |             Peer B
         Server-Reflexive     Relayed             Transport
         Transport Address    Transport Address   Address
         192.0.2.1:7000       192.0.2.15:50000    192.0.2.210:49191

위 그림은 TURN Server를 통한 Client들 간의 communication을 그린 것 이다.
TURN Client는 Peer A 또는 Peer B와 통신이 하고 싶은 상황이다.
TURN Server는 Public 망에 있다.

STUN Message

STUN Message는 STUN Protocol에서 사용되는 message이다.
TURN은 STUN Message를 확장한 프로토콜이기에, 기본적으로 STUN Message 구조를 따른다.

STUN Header

 0                   1                   2                   3
 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
|0 0|     STUN Message Type     |         Message Length        |
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
|                         Magic Cookie                          |
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
|                                                               |
|                     Transaction ID (96 bits)                  |
|                                                               |
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+

STUN Message의 Header는 20 Byte로 구성된다.
STUN Message Type: message의 class 정보이며 request, success response, failuser response, indication 등 있으며, TURN 등 확장 프로토콜에서 추가되기도 한다.
Message Length: Header를 제외한 Message의 size
Transaction ID: STUN은 request ↔︎ response간 transaction을 지원한다. 해당 ID를 올릴 수 있는 부분

STUN Message Type

 0                 1
 2  3  4 5 6 7 8 9 0 1 2 3 4 5
+--+--+-+-+-+-+-+-+-+-+-+-+-+-+
|M |M |M|M|M|C|M|M|M|C|M|M|M|M|
|11|10|9|8|7|1|6|5|4|0|3|2|1|0|
+--+--+-+-+-+-+-+-+-+-+-+-+-+-+

Stun의 MessageType은 14bit로 표현된다.
앞 두 bit는 무조건 00이며(prefix, not message Type), Class + Method로 구성되어 있다.
Class는 8, 12 번째 bit이며, 나머지는 Method이다.
Class: 0b00=request, 0b01=indication, 0b10=successResponse, 0b11=errorResponse

EX) 
TURN Protocol Create Permission
Class: request(0b00) or successResponse(0b10) or errorResponse(0b11)
Method: 0x008

request: 0000 0000 0000 1000 = 0x0008
sucessResponse: 0000 0001 0000 1000 = 0x0108
errorResponse: 0000 0001 0001 1000 = 0x0118

Protocol	Method	Bytes	Support Class
STUN	(Reserved)	0x000	-
STUN	Binding	0x001	-
STUN	(Reserved; was SharedSecret)	0x002	-
TURN	Allocate	0x003	req / res
TURN	Refresh	0x004	req / res
TURN	Send	0x006	indication
TURN	Data	0x007	indication
TURN	CreatePermission	0x008	req / res
TURN	ChannelBind	0x009	req / res

STUN Attributes

 0                   1                   2                   3
 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
|         Type                  |            Length             |
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
|                         Value (variable)                ....
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+

Type: Attribute의 구분으로 16bit이다.
Length: value의 length in bytes로 16bit 이다.
value: Attribute의 값

Protocol	Type	Bytes	Desc
STUN	MAPPED-ADDRESS	0x0001	reflexive transport address of the client
STUN	USERNAME	0x0006	identifies the username and password combination used in the message-integrity
STUN	MESSAGE-INTEGRITY	0x0008	contains an HMAC-SHA1 [RFC2104] of the STUN message
STUN	ERROR-CODE	0x0009	errorCode: 300 ~ 699 + α 300: Try Alternate 400: Bad Request 401: Unauthorized 420: Unknown Attribute 438: Stale Nonce 500: Server Error
STUN	UNKNOWN-ATTRIBUTES	0x000A	errorResponse에서만 사용되는 type으로, 서버가 이해하지 못한 attribute를 뜻함
STUN	REALM	0x0014	Attribute가 request에 있는 경우 long-term credential이 사용되고 있음을 나타내며 error response에 있다면 client에게 long-term credential이 필요함을 나타냄
STUN	NONCE	0x0015	128 character보다 적은 임의의 값
STUN	XOR-MAPPED-ADDRESS	0x0020	MAPPED-ADDRESS와 동일하며, 난독화 됨
STUN	SOFTWARE	0x8022	textual description of the software
STUN	ALTERNATE-SERVER	0x8023	alternate transport address identifying a different STUN server that the STUN client should try
STUN	FINGERPRINT	0x8028	use for identifier
TURN	CHANNEL-NUMBER	0x000C	channel을 지정하기 위한 값
TURN	LIFETIME	0x000D	duration of allocation
TURN	XOR-PEER-ADDRESS	0x0012	난독화된 상대의 address를 의미
TURN	DATA	0x0013	data
TURN	XOR-RELAYED-ADDRESS	0x0016	Allocate Response로 전달되는 allocated된 address
TURN	REQUESTED-ADDRESS-FAMILY	0x0017	IPv4: 0x01 IPv6: 0x02
TURN	EVEN-PORT	0x0018	relay port를 even으로 요청
TURN	REQUESTED-TRANSPORT	0x0019	protocol을 지정하는 attribute (https://www.iana.org/assignments/protocol-numbers/protocol-numbers.xhtml) 17 (User Datagram Protocol)로 고정
TURN	DONT-FRAGMENT	0x001A	Allocate시 보내는 attribute로 peer로 데이터 전달 시 fragment를 하지 말라는 의미 value는 없음
TURN	RESERVATION-TOKEN	0x0022	Server에서 예비로 남긴 relay address를 식별하는 토큰 allocation에서 사용될 수 있음
TURN	ADDITIONAL-ADDRESS-FAMILY	0x8000	REQUESTED-ADDRESS-FAMILY의 확장, allocate에서 사용될 수 있음
TURN	ADDRESS-ERROR-CODE	0x8001	address관련 error code
TURN	ICMP	0x8004	UDP Packets이 사라진 이유를 서버에서 알리기 위한 Attribute
STUN	(Reserved)	0x0000	-
STUN	(Reserved; was RESPONSE-ADDRESS)	0x0002	for legacy protocol
STUN	(Reserved; was CHANGE-ADDRESS)	0x0003	for legacy protocol
STUN	(Reserved; was SOURCE-ADDRESS)	0x0004	for legacy protocol
STUN	(Reserved; was CHANGED-ADDRESS)	0x0005	for legacy protocol
STUN	(Reserved; was PASSWORD)	0x0007	for legacy protocol
STUN	(Reserved; was REFLECTED-FROM)	0x000B	for legacy protocol
TURN	Reserved (was BANDWIDTH)	0x0010	for legacy protocol
TURN	Reserved (was TIMER-VAL)	0x0021	for legacy protocol

Sample TURN Sequence Diagram

Client는 TURN Server로 Allocate를 진행하는 참여자이며 Peer는 TURN 서버에서 메시지 전송이 가능한 참여자이다.
따라서 Peer는 public 망에 있거나, 이전에 Allocate 된 상태로 보면 된다.
allocate를 포함하여 대부분의 메시지에 적용되는 인증은 같은 방식으로 진행한다.

일반적인 Flow는 Allocate → (Permission) → Send data 이며 Send data는 indicate와 channel 방식이 있다.
Client는 Allocate를 통해 자신에게 udp 전송이 가능하도록 할당을 받는다.
이후 peer등 다른 참여자는 allocate된 해당 address로 data를 전송하면 TURN Server에서 allocate 된 정보를 바탕으로 Client에게 메시지를 전송한다.
indicate는 메시지마다 peer에 대한 정보를 같이 보내는 방식
channel은 사전에 channel number와 peer를 mapping하여, channel number로만 data를 전송하는 방식이다.

Appendix: UDP Hole Punching

Hole Pubching은 NAT 뒤의 client들의 peer to peer가 가능하도록 하는 방법 중 하나이다.
이는 NAT 뒤의 client끼리 p2p 통신을 시작할 수 없기 때문에 필요하다.
Hole Pubching 를 위해서는 NAT 방식이 EIM(Endpoint-Independent Mapping)일 때 이상적으로 동작한다.

Under EIM-NAT

                                 Server S
                             192.0.2.128:20001
                                     |
        +----------------------------+----------------------------+
        | ^ Registry Session(A-S) ^     ^ Registry Session(B-S) ^ |
        | | 192.0.2.128:20001     |     |  192.0.2.128:20001    | |
        | | 192.0.2.1:62000       |     |  192.0.2.254:31000    | |
        |                                                         |
        | ^ P2P Session (A-B)     ^     ^  P2P Session (B-A)    ^ |
        | | 192.0.2.254:31000     |     |  192.0.2.1:62000      | |
        | | 192.0.2.1:62000       |     |  192.0.2.254:31000    | |
        |                                                         |
      +--------------+                                 +--------------+
      | 192.0.2.1    |                                 | 192.0.2.254  |
      |              |                                 |              |
      | EIM-NAT A    |                                 | EIM-NAT B    |
      +--------------+                                 +--------------+
        |                                                         |
        | ^ Registry Session(A-S) ^     ^ Registry Session(B-S) ^ |
        | |  192.0.2.128:20001    |     |  192.0.2.128:20001    | |
        | |     10.0.0.1:1234     |     |     10.1.1.3:1234     | |
        |                                                         |
        | ^ P2P Session (A-B)     ^     ^  P2P Session (B-A)    ^ |
        | |  192.0.2.254:31000    |     |  192.0.2.1:62000      | |
        | |     10.0.0.1:1234     |     |     10.1.1.3:1234     | |
        |                                                         |
     Client A                                                 Client B
     10.0.0.1:1234                                        10.1.1.3:1234

두 Client가 서로 다른 EIM-NAT 뒤에 있다.
ClientA ↔︎ ClientB는 직접통신은 불가하며, NAT를 거쳐 통신을 하고자 한다.
1. ClientA, B 모두 Server로 Session을 등록하는 과정을 갖는다.
2. EIM-NAT는 Endpoint와 상관없이 각각 192.0.2.1:62000, 192.0.2.254:31000을 ClientA, B와 매핑한다.
3. ClientA, B 모두 Server에게 상대의 NAT public IP를 쿼리한다.
4. ClientA, B 서로 Server를 통해 만든 NAT Table의 포트로 UDP 통신을 한다.

REFERENCE

https://datatracker.ietf.org/doc/html/rfc8656

https://datatracker.ietf.org/doc/html/rfc5389

https://datatracker.ietf.org/doc/html/rfc5128#section-3.3

https://www.netmanias.com/ko/post/blog/5833/nat-network-protocol/nat-behavior-requirements-for-unicast-udp-rfc-4787-part-1-mapping-behavior

API Gateway with Passport

북극곰은콜라 — Sat, 9 Mar 2024 23:40:19 +0900

개요

이전에 토스 및 네이버(라인?) 아티클에서 API Gateway를 통해서 MSA 구조에서 API로 접근하는 인증 / 인가를 수행하고 있음을 읽었었다.
이는 각 API 서버에서 필요한 기능을 한 곳에서 수행하여 생산성을 높여 효율화를 한 작업으로 감탄했었다. 현 개인서버의 요구사항으로는 최대한 중복 개발을 줄여 생산성을 극대화하며, 귀찮음을 덜고자하는 것이 부합한다.
위 방식을 응용하여 전체적인 아키텍쳐를 설계하고자 한다.

서버 아키텍쳐 설계

현 개인서버의 전체적인 아키텍쳐이다.
- Nginx에서 SSL을 수행하고 reverse proxy를 통해 내부 통신을 연결한다.
- Gateway Server는 Nginx로 부터 모든 요청을 받아서 L7 switching의 역할을 할 생각이다.
기본적으로 Gateway와 Zookeeper를 연동하여 ServiceDiscovery를 통해 auto routing을 수행할 예정이다.
- OAuth Server는 토큰 발급 및 Passport 정보를 생성하는 주체가 될 예정이다.
- User Server는 기본적인 회원관리를 담당할 예정이다.

기본적으로 모든 Server들은 zookeeper에 자신의 정보를 올려서 discovery할 수 있도록 common library를 구성했었다.

User Server

유저는 기본적으로 main 계정이 존재하며, Social Login 등 다른 기타 유저정보가 1:N으로 구성될 수 있는 방식을 취할 예정이다.
이는 URI Path를 통해서 Restful하게 표현할 예정이다.

Package 설계

User Server는 기본적으로 Rest 및 Kafka Produce/consume을 하게 될 예정이다.
따라서 core한 서비스 및 기능을 구현하고
inbound / outbound 처리는 별도의 페키지에서 할 수 있도록 구성했다.

URI Path

@Bean
  public RouterFunction<ServerResponse> userMainRoute(final UserMainHandler userMainHandler) {
    return RouterFunctions.route()
        .GET("/main/{id}", userMainHandler::handleGetUserMainId)
        .GET("/main", userMainHandler::handleGetUserMain)
        .POST("/main", userMainHandler::handlePostUserMain)
        .POST("/main/password", userMainHandler::handlePostUserMainPassword)
        .build();
  }

/main, /main/{id} 는 설계에 큰 무리가 없었다.

기본적으로 Password의 CUD는 user server가 수행하기 때문에, password encode/decoder 또한 user server가 관리한다.
따라서 OAuth Server에서 사용자 id/password를 체크하기 위해서는 password 체크가 필요하다.
하지만, password 매칭에 대한 path 설계가 조금 어색하긴 하다...

OAuth Server

기본적으로 Spring Authorization Server 라이브러리로 구성했다.
필요한 부분만 구현했으며, 나머지는 기본 설정에 따라서 동작한다.

Authorization

@Bean
public InMemoryOAuth2AuthorizationService authorizationService() {
  return new InMemoryOAuth2AuthorizationService();
}

@Bean
public AuthorizationServerSettings authorizationServerSettings() {
  return AuthorizationServerSettings.builder().build();
}

일단 scale-out에 대한 예정이 없어서 inMemory 방식 기본 모듈을 사용했다.

@Component
@RequiredArgsConstructor
@Slf4j
public class PbearAuthenticationProvider implements AuthenticationProvider {
  ...

  @Override
  public Authentication authenticate(final Authentication authentication) throws AuthenticationException {
    ...

    if (!this.userService.checkPassword(
        String.valueOf(targetAuth.getPrincipal()),
        String.valueOf(targetAuth.getCredentials()))) {
      throw new BadCredentialsException("not match password, id: " + authentication.getPrincipal().toString());
    }

    return new UsernamePasswordAuthenticationToken(
        this.createAuthenticatedPrincipal(String.valueOf(targetAuth.getPrincipal())),
        null,
        targetAuth.getAuthorities()
    );
  }

  ...

  private String createAuthenticatedPrincipal(final String mainId) {
    UserInfo userInfo = this.userService.getUserInfo(mainId);
    try {
      return this.objectMapper.writeValueAsString(Map.of(
          "id", userInfo.id(),
          "mainId", userInfo.mainId()));
    } catch (JsonProcessingException e) {
      return mainId;
    }
  }
}

Authentication은 Custom하게 구현했다.
1. user server에 /main/password API를 호출하여 password 체크를 수행한다.
2. user server로 부터 user정보를 GET하여 principal을 jsonString으로 생성한다.

Client 관리

@Bean
  public InMemoryRegisteredClientRepository registeredClientRepository() {
    RegisteredClient registeredClient = RegisteredClient.withId(UUID.randomUUID().toString())
        .clientId("common-client")
        ...
        .build();

    return new InMemoryRegisteredClientRepository(registeredClient);
  }

Client도 일단 아직 관리할 필요성을 느끼지 못해서 하드코딩된 inMemory 방식 모듈을 사용했다.

Token 관련

@Bean
public JWKSource<SecurityContext> jwkSource(final KeyProvider keyProvider) {
  KeyPair keyPair = keyProvider.getKeyPair();
  RSAPublicKey publicKey = (RSAPublicKey) keyPair.getPublic();
  RSAPrivateKey privateKey = (RSAPrivateKey) keyPair.getPrivate();
  RSAKey rsaKey = new RSAKey.Builder(publicKey)
    .privateKey(privateKey)
    .keyID(DEFAULT_OAUTH_KEY_ID)
    .build();
  JWKSet jwkSet = new JWKSet(rsaKey);
  return (jwkSelector, securityContext) -> jwkSelector.select(jwkSet);
}

@Bean
public OAuth2TokenCustomizer<JwtEncodingContext> oAuth2TokenCustomizer() {
  return new TokenCustomizer();
}

기본적으로 classpath에서 private key를 load하여 jwk를 구성하고 이를 전체 jwt에 적용하도록 구성했다.
privage key는 기본적으로 github에 공유할 수 없기 때문에, CI 과정에서 특정 디렉토리에서 cp하도록 했다.

토큰 customizer관련 코드: https://github.com/p-bear/pbear-root/blob/master/pbear-spring/pbear-app-oauth/src/main/java/com/pbear/oauth/core/TokenCustomizer.java

Login Page 관련

@Bean
public SecurityFilterChain defaultSecurityFilterChain(final HttpSecurity http,
                                                      final RedirectService redirectService,
                                                      final PBearLoginSuccessHandler pBearLoginSuccessHandler) throws Exception {
  http
    .authorizeHttpRequests(authorize ->
        authorize
            .requestMatchers("/**.css").permitAll()
            .requestMatchers(request -> request.getRequestURI().endsWith("login-page.html")).permitAll()
            .requestMatchers(request -> request.getRequestURI().endsWith("login")).permitAll()
            .requestMatchers(request -> request.getRequestURI().endsWith("error")).permitAll()
            .anyRequest().authenticated()
    )
    .formLogin(formLogin -> formLogin
        .loginPage(redirectService.createLoginPageRedirectUrl())
        .loginProcessingUrl("/login")
        .successHandler(pBearLoginSuccessHandler)
    )
    ...

  return http.build();
}

기본적으로 static resource에서 html을 제공하도록 구성했다.

하지만, 문제는 nginx -> gateway -> oauth로 오는 구성에서 발생헀다.
일단 운영상황에서는 request path에 /gateway/{serverName}이 prefix로 붙어야 각 서비스로 routing 되지만, 로컬 개발시에는 direct로 붙게된다.
그리고 nginx를 통과한 request는 기본적으로 request host가 변경 되어 servletRequest에서 원 host를 찾을 수 없었다. (내부IP로 읽어짐)
reuqest header의 "origin"을 읽을 수 도 있지만, 이는 모든 상황에서 통용될 수 없다 판단했다.

이를 해결하기 위해, 운영서버를 판단하는 기준인 spring profile active로 redirect URL를 다시 작성하는 방법을 취했다. 기본적으로 url을 customize할 수 있는 옵션들은, 코드를 보았을 때 full url이면 해당 url로 대체되도록 구현되어있어, 이를 활용했다.

Gateway Server

Zookeeper 연동

build.gradle

...

dependencies {
    ...
    implementation 'org.springframework.cloud:spring-cloud-starter-zookeeper-discovery'
}

application.yml

spring:
  ...
  cloud:
    gateway:
      discovery:
        locator:
          enabled: true

위 옵션으로 간단하게 zookeeper와 연동할 수 있다.
이는 zookeeper-discovery 라이브러에서 DiscoveryClient를 구현해 제공해주기 때문이다.
기본적으로 discovery에 등록된 serviceName으로 routing을 해준다.

Passport Global Filter

@Component
@RequiredArgsConstructor
public class PassportGlobalFilter implements GlobalFilter {
  private static final String PASSPORT_HEADER_PREFIX = "X-PP-";
  private final PassportService passportService;

  @Override
  public Mono<Void> filter(final ServerWebExchange exchange, final GatewayFilterChain chain) {
    return Mono
        .zip(this.handleExchangeWithPassport(exchange), Mono.just(chain))
        .flatMap(tuple -> tuple.getT2().filter(tuple.getT1()));
  }

  private Mono<ServerWebExchange> handleExchangeWithPassport(final ServerWebExchange serverWebExchange) {
    HttpHeaders httpHeaders = serverWebExchange.getRequest().getHeaders();
    if (!httpHeaders.containsKey(HttpHeaders.AUTHORIZATION)) {
      return Mono.just(serverWebExchange);
    }
    return this.passportService.getPassportData(httpHeaders.getFirst(HttpHeaders.AUTHORIZATION))
        .map(passportData -> {
          ServerHttpRequest.Builder builder = serverWebExchange.getRequest().mutate();
          passportData.forEach((headerName, headerValue) ->
              builder.headers(header -> header.add(PASSPORT_HEADER_PREFIX + headerName, headerValue)));
          return serverWebExchange.mutate()
              .request(builder.build())
              .build();
        });
  }
}

1. 기본적으로 모든 request에서 Authorization이 header에 있는지 체크한다.
2. 있다면 해당 header value를 넣어서 oauth server의 resource API인 /passport로 요청한다.
3. 응답 결과를 받아서 passport data를 request header에 X-PP-를 prefix해서 추가한다.
// 현 구현으로는 X-PP-id, X-PP-mainId 2가지가 있다.

추후 인가가 필요한 서비스는 X-PP- 헤더를 읽어서 해결할 수 있을 것이다.

Conclusion

여기까지가 기본적인 서비스 개발을 위한 준비가 완료되었다고 판단된다.
이후 개발하는 서비스들은 여기까지 구현된 사항으로 보다 쾌척하게 작업할 수 있을 것으로 기대된다.
생산성의 향상으로 신규 개발의 저항감을 어느정도 해소 할 수 있기를 빌어본다...

현 계획된 서비스는 2가지가 있다.
1. 개인 자산 통합관리
2. 지하철 데이터를 활용한 hot place 시각화 서비스
올해안으로 완성할 수 있기를 기도해본다..

REFERENCE

Authorization Server

- https://datatracker.ietf.org/doc/html/rfc6749

- https://docs.spring.io/spring-authorization-server/reference/protocol-endpoints.html

- https://github.com/spring-projects/spring-authorization-server/tree/main/samples/demo-authorizationserver/src/main/java/sample

API Gateway Server

- https://docs.spring.io/spring-cloud-gateway/reference/spring-cloud-gateway/global-filters.html

- https://github.com/spring-cloud-samples/spring-cloud-gateway-sample/blob/main/src/main/java/com/example/demogateway/DemogatewayApplication.java

- https://toss.tech/article/slash23-server

ProjectReactor Case Study

북극곰은콜라 — Thu, 22 Feb 2024 18:28:05 +0900

개요

Reactive coding에서는 적절한 operation 사용이 필수 불가결이다.
이는 가독성을 높이고, Sequence를 효과적으로 구성할 수 있다.
하지만, operator는 종류가 많고, 복잡한 것들이 많기 때문에, 선택에 어려움이 있다.
이번 글은 상황 별 operator 가이드와, 예시를 제공하고자 한다.

Case 별 Operator 정리

Sequence 생성

Operator	상황
just, justOrEmpty	특정 Element 또는 Element들로 시작하는 Sequence 생성
fromArray, fromIterable, range, fromStream	iteration 할 수 있는 Element들로 Sequence(Flux) 생성
empty	empty한 Sequence 생성
defer	subscribe 시점에 실행
error	error 생성

Sequence를 생성하는 상황은 기본적으로 특정 Object 또는 여러 Object 를 기반으로 시작한다.
일반적으로 Object의 reference를 통해 생성하거나, Functional Interface를 람다로 구현한다.

Sequence에서 Transform

Operator	상황
map	Sequence에 변동 없이 Object만 바꾸고 싶을 경우
cast	Sequence에 변동 없이 Object Type만 바꾸고 싶을 경우
flatMap	다른 Sequence를 넣고 싶은 경우
startWith, concatWithValues	element를 앞,뒤로 추가하고 싶은 경우
collectList, collectSortedList, collectMap, collectMultiMap, collect, count, all, any…	flux를 aggregation하고 싶은 경우
concatWith, zip, zipWith, zipWhen	다른 Sequence와 합치고 싶은 경우
defaultIfEmpty, switchIfEmpty	empty sequence를 처리하고 싶은 경우
then, thenEmpty, thenMany	sequence와 상관없이 다음 sequence를 만들고 싶은 경우

Sequence를 변경할 수 있는 방법들이다. 일반적으로, element 변경, 다른 sequence를 태우거나 합치는 방법들
위 Operator들은 기존 sequence의 변화를 준다.

Peeking

Operator	상황
doOnNext doOnComplete, doOnSuccess, doOnError, doOnCancel doFirst doOnSubscribe, doOnRequest, doOnTerminate	sideEffect를 통한 기존 Sequence에 영향을 미치지 않는 방식 각각의 실행 시점을 choose할 수 있다.
doOnEach, materialize log	모든 signal에 대한 handling을 하고 싶을 때 사용하는 operator들

peeking은 기존 sequence에 영향을 미치지 않는 operator들로 여겨진다.
이 의미는 doOnNext를 skip하고 해석해도 기존 flow를 이해할 수 있어야 한다는 말과 같다고 볼 수 있다.

가령 doOnNext는 sideEffect를 통해 기존 sequence에 영향을 미치지 않는 로직이 들어간다고 생각할 수 있다.
따라서 doOnNext에서 객체의 속성을 변경하거나 하는 로직은 혼란을 야기할 수 있다.
자세한 사항은 후술

Filtering

Operator	상황
fliter, filterWhen	특정 로직을 통한 필터링
ignoreElements, distinct, ofType take, takeLast, next elementAt, skip, single sample	hard한 filtering으로 분류 된다. sequence의 element를 선택/filtering하는 방법

element를 필터링 하는 Operator들이다.
custom로직, 갯수, 시간, element 위치 등으로 filtering할 수 있도록 지원한다.

Error Handling

Operator	상황
error	error signal을 발생 시킬 수 있는 operator
onErrorReturn, onErrorComplete, onErrorResume, onErrorMap	error handling
doFinally, using	error consume
retry, retryWhen	retry when error

에러처리를 지원하는 operator이다.
권장사항은 에러처리를 try catch가 아닌 reactive하게 처리하는 것 이다.

Flux Split

Operator	상황
window, windowUntil
buffer

flux를 size 또는 duration으로 쪼개는 Operator들 이다.

Going Back to the Synchronous World

Operator	상황
block, blockFirst, blockLast toIterable, toStream toFuture	reactive에서 sync로 넘어가는 방법

Sync하게 Sequence 바깥으로 탈출하는 Operator들이다.
당연하게도 Sync로 넘어갈 수 없는 Scheduler에서는 사용할 수 없는 Operator들 이다.

Reactive Code Best Practice

Operator 단일 책임 원칙 (Depth 최소화)

하나의 Operator는 한가지 일을 해야한다.

주의:
Reactive code를 작성하다 보면, 뜻하지 않게 하나의 operator안에서 여러가지 비즈니스를 처리하게 된다.이는 co-worker 또는 시간이 지남에 따라, 읽기 힘들어지며, 유지보수성이 떨어지게 된다.operator의 depth가 높아지는 상황은 하나의 문장 안에 많은 내용을 집어넣는 것과 같다.

추천:
이를 해결하기 위해서 적절한 Operation 사용을 통한 로직의 분리, 라이브러리를 통한 분리하는 방법이 있다.이는 비즈니스의 문장들을 연결할 접속사를 다양하고 적절하게 사용해서, 가독성을 높이는 효과를 보이는 것이라 생각한다.아래 예시들은 depth가 늘어나는 상황을 적절한 operator를 통해 해소하는 방법들에 대한 것이다.

map(), doOnNext(), filter(), switchIfEmpty() 등 Example

흔한 비즈니스를 예제로 했다.
1. input 로깅
2. 특정 값으로 db 조회
3. 조회값 로깅
4. db 조회 된 값을 기준으로 REST 요청
5. REST 요청의 response code 200 검증
- 200이 아닐 시 custom error 생성
6. Res의 Z 값 리턴

// Before

public Mono<?> worstCase(final String id) {
  return Mono.just(id)
      .flatMap(xId -> {
        log(xId);
        return getXFromDB(xId)
            .flatMap(x -> {
              log(x);
              Req req = new Req(x.getYId());
              return getYFromRest(req)
                  .flatMap(y -> {
                    if (y.getResCode().equals("200")) {
                      return Mono.just(y.getZId());
                    } else {
                      throw new RuntimeException("rest error");
                    }
                  });
            });
      });
}

// After
public Mono<?> betterCase(final String id) {
  return Mono.just(id)
      .doOnNext(this::log)
      .flatMap(this::getXFromDB)
      .doOnNext(this::log)
      .map(x -> new Req(x.getYId()))
      .flatMap(this::getYFromRest)
      .filter(y -> y.getResCode().equals("200"))
      .switchIfEmpty(Mono.defer(() -> Mono.error(new RuntimeException("rest error"))))
      .map(Y::getZId);
}

element에 초점을 두고, 변화를 operator를 통해 표현하면 depth가 낮아지는 효과를 볼 수 있다.
비즈니스 로직을 순차적으로 호출하는 것이 아닌, element가 변화하는 방식으로 위 비즈니스를 해석하자면
1. xId를 기반으로 Sequence 생성
- (sideEffect) xId 로깅
2. DB 조회 로직을 통해 X Element로 변환
- X 로깅
3. X를 Req로 변환
4. REST 로직을 통해 Y (Res)로 변환
5. 200인 응답을 필터링
- 200이 아닌 경우 error signal 생성
6. Z 값으로 변환

depth를 낮추고 element 위주의 설계는 가독성 외 2가지 장점을 가진다.
1. 메서드를 분리하는 기준이 된다.
2. 로직의 추가/제거가 상대적으로 용이하다.

filterWhen() Example

cache에서 특정 id가 로그인 되어있는지 확인하는 필터를 추가하는 비즈니스가 추가 되는 상황을 가정했다.

public Mono<Boolean> checkLoginFromCache(final String yId) {
  ...
}

// Before
public Flux<?> filterWhenWorst() {
  return this.getXListFromDB()
      .flatMap(x -> checkLoginFromCache(x.getYId())
          .map(isLogin -> {
            if (isLogin) {
              return Mono.just(x);
            }
            return Mono.empty();
          }));
}

// After
public Flux<?> filterWhenGood() {
  return this.getXListFromDB()
      .filterWhen(x -> checkLoginFromCache(x.getYId()));
}

한정된 Operator로 인하여 depth가 늘어나게 되는 대표적인 예시이다.
filterWhen Operator를 모른다면, 하위 Sequence로 X를 필터링해서 보내기 위해 flatMap으로 다른 Sequence의 결과를 기반으로 X Element를 다시 Sequence로 만들어야 한다.
filterWhen을 사용하면, 다른 Sequence(Flow)의 결과를 기반으로 현제 Sequence를 필터링 할 수 있다.

Zip(), ZipWhen(), ZipWith() Example

X Table에서 data를 조회하고, 그 값에 기반하여 Y Table을 조회하여 새로운 객체를 만드는 상황 예시이다.
이 예시는 Rest로 조회한 값과, DB 값을 합칠 때 같이 비즈니스 구성 시 많이 발생하는 상황이다.

// Worst
public Mono<?> zipWorst(final String id) {
  return getXFromDB(id)
      .flatMap(x -> getYFromDB(x.getYId())
          .map(y -> new Req(x, y)))
      .flatMap(this::getZFromRest);
}

// Good
public Mono<?> zipGood(final String id) {
  return getXFromDB(id)
      .zipWhen(x -> getYFromDB(x.getYId()))
      .map(tuple -> new Req(tuple.getT1(), tuple.getT2()))
      .flatMap(this::getZFromRest);
}

// Best
public Mono<?> zipBest(final String id) {
  return getXFromDB(id)
    .zipWhen(x -> getYFromDB(x.getYId()), Req::new)
    .flatMap(this::getZFromRest);
}

두 Sequence를 합치는 zip 관련 operator를 사용하지 않는다면, depth가 하나 늘어날 수 밖에 없다.
zip 을 통하여 명확하게 두 sequence를 합치는 것을 알리면서, depth를 줄일 수 있다.

Flux Zip with Default

public void zipWarning() {
  Flux<String> strFlux = Flux.just("1", "2", "3", "4");
  Flux<Integer> intFlux = Flux.just(1, 2);

  strFlux
      .zipWith(intFlux)
      .doOnNext(TupleUtils.consumer((s, i) -> System.out.println(s + " / " + i)))
      .subscribe();
}

>> 1 / 1
>> 2 / 2

Flux의 Zip 사용 시 주의 점으로
zip 은 두 sequence 중 하나라도 complete signal이 오면 zip operation이 종료되며, 나머지 sequence로 cancel signal을 보낸다.
위 예제처럼 intFlux의 element가 2개이기 때문에, strFlux의 “3”, “4”는 cancel 되었다.

Flux<String> strFlux = Flux.just("1", "2", "3", "4");
Flux<Integer> intFlux = Flux.just(1, 2);

strFlux
    .zipWith(intFlux.concatWith(Flux.just(-1).repeat()))
    .doOnNext(TupleUtils.consumer((s, i) -> System.out.println(s + " / " + i)))
    .subscribe();
    
>> 1 / 1
>> 2 / 2
>> 3 / -1
>> 4 / -1

해결 방안으로 concat을 활용할 수 있다.
concat은 complete signal로 다른 publisher에 연결된다.
이를 활용하여, repeat()하는 element create publisher로 default element처럼 zip해주면
default element를 생성하는 zip operation이 가능하다.

delayUntil() Example

Z를 result로 내보내야 하지만, 중간에 내부 속성인 x와 y를 DB에 update해야하는 비즈니스가 있다고 가정했다.

// Worst
public Mono<Z> delayUntilWorst(final Req req) {
  return getZFromRest(req)
      .flatMap(z -> updateXToDB(z.getX())
          .flatMap(x -> updateYToDB(z.getY()))
          .map(y -> z));
}

// Good
public Mono<Z> delayUntilGood(final Req req) {
  return getZFromRest(req)
      .delayUntil(z -> updateXToDB(z.getX()))
      .delayUntil(z -> updateYToDB(z.getY()));
}

sequence의 element를 유지하면서 다른 Flow를 처리하는 방법이다.
flatMap을 사용한다면, 부모 element를 밑으로 다시 넘기기 위해 depth가 늘어날 수 밖에 없다.

주의:
delayUntil은 내부적으로 생성되는 sequence가 flat하다.
따라서, Flux의 경우 element가 순차적으로 생성되는 Sequence 실행되기 때문에 성능 상 손해가 발생할 수 있다.

Tuple Library 활용

Tuple의 경우 Reactive Coding에서 활용성이 좋은 DTO지만, 가독성이 문제가 될 수 있다.
이는 t1, t2 등 내부 값이 IDE의 가이드 없이 확인하기 어렵기 때문이다.
이를 도와주는 Projectreactor의 addon Library가 있다.

Gradle

implementation 'io.projectreactor.addons:reactor-extra'

Zip with Library

// Before
public Mono<?> zipGood(final String id) {
  return getXFromDB(id)
      .zipWhen(x -> getYFromDB(x.getYId()))
      .map(tuple -> new Req(tuple.getT1(), tuple.getT2()))
      .flatMap(this::getZFromRest);
}

// After
public Mono<?> zipWithLib(final String id) {
  return getXFromDB(id)
      .zipWhen(x -> getYFromDB(x.getYId()))
      .map(TupleUtils.function((x, y) -> new Req(x, y)))
      .flatMap(this::getZFromRest);
}

public Mono<?> zipWithLibGood(final String id) {
  return getXFromDB(id)
      .zipWhen(x -> getYFromDB(x.getYId()))
      .map(TupleUtils.function(Req::new))
      .flatMap(this::getZFromRest);
}

위 예제 중 zip 관련 예제이다.
코드로 보았을 때 map안의 tuple이 정확하게 어떤 객체로 이루어져 있는지 확인할 수 없다.
이를 function으로 풀어서 작성자가 보다 명확하게 표현할 수 있도록 도와둔다.

참고:
Kotlin의 경우 문법적으로 확장 함수, 구조 분해 등을 통해 가독성을 지원한다. ㅎㅎ

Use error() Operator

// 1. Success to handle Exception (Throw)
public Mono<?> handleErrorExample() {
  return Mono.just("ex")
      .flatMap(this::customError)
      .onErrorReturn("errorHandled");
}
public Mono<String> customError(final String x) {
  throw new RuntimeException();
}

>> onErrorReturn 동작


// 2. Fail to handle Exception (Throw)
public Mono<?> handleErrorExample() {
  return Mono.just("ex")
      .flatMap(s -> this.customError(s)
          .onErrorReturn("errorHandled"));
}
public Mono<String> customError(final String x) {
  throw new RuntimeException();
}

>> onErrorReturn 미동작


// 3. handle Exception with error() operator
public Mono<?> handleErrorExample() {
  return Mono.just("ex")
      .flatMap(s -> this.customError(s)
          .onErrorReturn("errorHandled"));
}
public Mono<String> customError(final String x) {
  return Mono.error(new RuntimeException());
}

>> onErrorReturn 동작

1번의 경우 flatMap에서 exception을 감지하고, error signal을 만들어 하위 flow로 넘기기 때문에 onErrorReturn이 처리된다.
하지만 2번의 경우 throw 된 Exception을 error signal로 변환하지 못한 상황에서 onErrorReturn이 호출되어서 error handling이 skip 되는 문제가 있다.
3번처럼 Exception을 error signal과 함께 생성하는 방식이, 문제 상황을 차단할 수 있다.

Conditional Flow Example

비즈니스를 구성할 때 자주 발생하는 상황으로 condition에 따른 로직 분기가 있다.
예로
1. a일 때 A 프로세스, b일 때 B 프로세스
2. c일 때 C 프로세스 추가
등이 있다.
일반적으로 분기를 통한 비즈니스 수행은 비즈니스 구성에 핵심적인 내용을 담은 경우가 많다.

1. Simple Conditional Flow

public Mono<String> conditionalFlow1(final String s) {
  return this.doSomeThing(s)
      .flatMap(condition -> {
        if ("a".equals(condition)) {
          return processA();
        }
        return process();
      });
}

심플하게 표현한 flow 설계 코드이다.
Depth가 많이 들어가서 안 좋은 코드로 보이지만, 위 방법이 잘못되지 않았다는 의견도 많다.

public Mono<String> conditionalFlow1A(final String s) {
  return this.doSomeThing(s)
      .flatMap(condition -> "a".equals(condition) ? this.processA() : this.process());
}

삼항연산자를 통해 위 if else를 한줄로 변경

public Mono<String> conditionalFlow1B(final String s) {
  return this.doSomeThing(s)
      .flatMap(this::processWithCondition);
}

public Mono<String> processWithCondition(final String condition) {
  if ("a".equals(condition)) {
    return processA();
  }
  return process();
}

위 Depth를 줄이기 위해, method를 분리했다.
분기 로직을 메서드로 분리하는 방식은 아래 장단점을 가진다.
장점: 비즈니스의 핵심인 분기 처리를 한 곳에서 관리할 수 있다.
단점: 비즈니스가 복잡해지면, 파라미터가 과도하게 많아지거나, 상위에서 defer를 통한 lazy 처리가 필요할 수 있다.

2. conditional with switchIfEmpty

public Mono<String> conditionalFlow2(final String s) {
  return this.doSomeThing(s)
      .filter("a"::equals)
      .flatMap(conditionA -> processA())
      .switchIfEmpty(Mono.defer(this::process));
}

switchIfEmpty Operator를 활용하여 분기를 처리하는 방법이다.
이 방식의 한계점은 switchIfEmpty 내부 로직이 상위 element를 받을 수 없다는 점이다.

ConnectableFlux Example

참고: https://p-bear.tistory.com/80

Manually

ConnectableFlux<String> source = sample2.sourceFromKafka()
        .delayUntil(sample2::doSomeBusiness)
        .map(sample2::mapRecordToObject)
        .publish();

source
    .publishOn(Schedulers.boundedElastic())
    .doOnNext(s -> printWithThread(" before A Server func"))
    .flatMap(sample2::restToAServer)
    .subscribe();
source
    .publishOn(Schedulers.boundedElastic())
    .doOnNext(s -> printWithThread("before B Server func"))
    .flatMap(sample2::restToBServer)
    .subscribe();

source.connect();

[boundedElastic-2] before B Server func
[boundedElastic-1]  before A Server func
[boundedElastic-2]  req B Server -> res B
[boundedElastic-1]  req B Server -> 1
[boundedElastic-2] before B Server func
[boundedElastic-1]  before A Server func
[boundedElastic-2]  req B Server -> res B
[boundedElastic-1]  req B Server -> 2

예시 비즈니스는 Kafka에서 받은 Record를 처리 후 여러 서버로 전파하는 로직이다.
ConnectableFlux를 활용하여 여러 Sequence에게 Element를 Hot하게 보내도록 구현했다.
위 예시는 특정 비즈니스는 한 stream에서 처리하고 이후 다른 구독자들에게 다른 scheduler를 적용한다.

with share()

Returns a new Flux that multicasts (shares) the original Flux. As long as there is at least one Subscriber this Flux will be subscribed and emitting data. When all subscribers have cancelled it will cancel the source Flux. This is an alias for publish().ConnectableFlux.refCount(). Returns: a Flux that upon first subscribe causes the source Flux to subscribe once, late subscribers might therefore miss items.

Sample2 sample2 = new Sample2();

Flux<String> sharedSource = sample2.sourceFromKafka()
    .map(sample2::mapRecordToObject)
    .share();

sharedSource
    .publishOn(Schedulers.boundedElastic())
    .doOnNext(s -> printWithThread(" before A Server func"))
    .flatMap(sample2::restToAServer)
    .subscribe();

sharedSource
    .publishOn(Schedulers.boundedElastic())
    .doOnNext(s -> printWithThread("before B Server func"))
    .flatMap(sample2::restToBServer)
    .subscribe();

System.out.println("next...");

sharedSource
    .subscribe(s -> System.out.println("main sub: " + s));
    
next...
main sub: 1
main sub: 2
[boundedElastic-2] before B Server func
[boundedElastic-1]  before A Server func
[boundedElastic-2]  req B Server -> res B
[boundedElastic-1]  req B Server -> 1
[boundedElastic-2] before B Server func
[boundedElastic-1]  before A Server func
[boundedElastic-2]  req B Server -> res B
[boundedElastic-1]  req B Server -> 2

깔끔하게 여러 subscriber를 Publisher에 적용하는 방법이다.
share() == publish().refCount()
이며, refCount()는 refCount(1)이며 최소 한 개의 subscriber가 있을 때 데이터를 제공하고, subscriber가 모두 cancel되면 상위flux(sharedSource)를 cancel 시킨다.

Cache Example

일부 비즈니스는 성능상의 이유로 값을 캐싱이 필요할 때가 있다.
가령 client_credential로 받은 하루짜리 토큰을 하루동안 사용해야할 때 등이 있다.
이때 cache()를 통한 mono, flux 캐싱이 유용하다.

public class TokenService {
  private final WebClient webClient;
  private final Mono<Map<String, Object>> tokenCache = this.cacheToken();

  public Mono<Map<String, Object>> getCachedToken() {
    return this.tokenCache;
  }

  public Mono<Map<String, Object>> cacheToken() {
    return this.getToken()
        .cache(
            tokenResponse -> Duration.ofSeconds(((Integer) tokenResponse.get("expires_in")).longValue()),
            throwable -> Duration.ZERO,
            () -> Duration.ZERO);
  }

  public Mono<Map<String, Object>> getToken() {
    return this.getTokenURIMono()
        .flatMap(this::requestToken);
  }

  private Mono<Map<String, Object>> requestToken(final URI uri) {
    return this.webClient
        .post()
        ...
        .retrieve()
        .bodyToMono(new ParameterizedTypeReference<>() {});
  }
  
  ...
}

// cache가 없을 때 token 요청
2024-02-02 14:06:38 INFO [reactor-http-nio-3] [65bc785efcfc05e5b31ab7066d150506,b31ab7066d150506] com.pbear.TokenService - create uri: https://...
2024-02-02 14:06:38 INFO [reactor-http-nio-3] [65bc785efcfc05e5b31ab7066d150506,b31ab7066d150506] com.pbear.WebClientConfig - Req 3rd > POST, URI=...
2024-02-02 14:06:39 INFO [reactor-http-nio-3] [65bc785efcfc05e5b31ab7066d150506,b31ab7066d150506] com.pbear.WebClientConfig - Res 3rd > 200 OK
2024-02-02 14:06:39 INFO [reactor-http-nio-3] [65bc785efcfc05e5b31ab7066d150506,b31ab7066d150506] com.pbear.TokenService - get Token: ce25ef3a-3ab5-4641-b9a5-faa91d9c603c
// 2,3번째 토큰은 cache로 부터
2024-02-02 14:06:51 INFO [reactor-http-nio-3] [65bc786bd274d9a444d2222fb7e82b8d,44d2222fb7e82b8d] com.pbear.TokenService - get Token: ce25ef3a-3ab5-4641-b9a5-faa91d9c603c
2024-02-02 14:06:53 INFO [reactor-http-nio-3] [65bc786d823d266fe3c0b70ec8d1cea6,e3c0b70ec8d1cea6] com.pbear.TokenService - get Token: ce25ef3a-3ab5-4641-b9a5-faa91d9c603c

위 구성은 최초 token 발급으로부터 expires_in 초 이후 cache가 삭제되는 로직이다.
cache()가 유지되는 동안 토큰발급 rest 요청을 하지 않는다.
이를 활용하면, 다른 library 도움 없이 기본적인 cache 로직을 구현할 수 있다.

Conclusion

java에서 Reactive 코드를 손과 머리가 닿는 방식으로 작성하면 차후에 수습불가능한 코드 덩어리가 생성된다.
최대한 다양한 Operator를 적절하게 사용하여 가독성을 높이는 작업은 생산성과 직결하는 사항이다.

특히 depth를 줄이는 것이 중요하다. 하지만, 과하게 줄이는 것도 문제가 있다.
때로는 코드의 줄이 늘어나는 것 보다는 깊이가 늘어나는게 좋을 때 도 있다.

최대한 많은 case를 살펴보고 정리해야
코드의 품질이 올라갈 수 있는 유일하고 정석적인 방법으로 생각된다.

REFERENCE

https://projectreactor.io/docs/core/release/reference/index.html#which-operator

https://d2.naver.com/helloworld/2771091

https://climbtheladder.com/10-project-reactor-best-practices/

https://tech.kakao.com/2018/05/29/reactor-programming/

Global Hooks And Context Propagation (Projectreactor Advanced Features)

북극곰은콜라 — Tue, 20 Feb 2024 19:59:34 +0900

Global Hooks란

리액터는 연산자의 콜백을 전역으로 설정할 수 잇다. 이는 Operator에 element가 흐르는 로직에 관여하는 것과 비슷하다.
Hooks 클래스로 제공되는 기능으로 3가지 종류가 있다.
1. Dropping Hooks
2. Internal Error Hook
3. Assembly Hooks

DroppingHooks

일반적으로 onError가 모든 에러를 잡을 수 있을 것으로 기대하지만, 그렇지 못한 상황이 발생한다.
가령 onComplete()를 호출 한 후 onNext()등 다른 signal를 연결했을 때 또는 handle되지 못한 에러가 있다.

Dropped By Previous Complete

// onNextDropped Example
Hooks.onNextDropped(o -> {
  System.out.println("onNextDropped called");
  System.out.println(o);
});

Mono
    .from(subscriber -> {
      subscriber.onComplete();
      subscriber.onNext("");
    })
    .doOnError(throwable -> System.out.println("doOnError Call!"))
    .subscribe();
    
>> onNextDropped called
>> inner

// onErrorDropped Example
Hooks.onErrorDropped(o -> {
  System.out.println("onErrorDropped called");
  System.out.println(o.getMessage());
});

Mono
    .from(subscriber -> {
      subscriber.onComplete();
      subscriber.onError(new RuntimeException("inner"));
    }).doOnError(throwable -> System.out.println("doOnError Call!"))
    .subscribe();
    
>> onErrorDropped called
>> inner

Publisher에서 onComplete() 이후 onNext(), onError()를 호출하면, 잘못된 reactive flow로 에러가 나고doOnError()에 잡힐 꺼 같지만
error signal은 발생하지 않으며, onNext(), onError()는 drop처리된다.
이 부분을 Hooks로 잡아내서 처리할 수 있다.

Dropped Error by not handled

Hooks.onErrorDropped(throwable -> System.out.println("error dropped: " + throwable.getMessage()));

Flux.just(1, 2, 3, 4, 0)
        .doOnNext(i -> System.out.println("element: " + i))
        .map(i -> 10 / i)
        .subscribe();

// hooks에 onErrorDropped를 설정하지 않는다면, default onErrorDropped로 처리된다.
>> [ERROR] (main) Operator called default onErrorDropped - reactor.core.Exceptions$ErrorCallbackNotImplemented: ...

처리되지 못한 Error Signal들은 결국 drop 처리된다.
이를 Hook으로 drop되기전에 처리할 수 있다.

// onErrorDropped에 등록되는 function은 append 된다.
Hooks.onErrorDropped(o -> System.out.println("onErrorDropped called"));
Hooks.onErrorDropped(o -> System.out.println("onErrorDropped2 called"));
Hooks.onErrorDropped(o -> System.out.println("onErrorDropped3 called"));

>> onErrorDropped called
>> onErrorDropped2 called
>> onErrorDropped3 called

// 1,2번은 초기화로 인하여 제거
Hooks.onErrorDropped(o -> System.out.println("onErrorDropped called"));
Hooks.onErrorDropped(o -> System.out.println("onErrorDropped2 called"));
Hooks.resetOnErrorDropped();
Hooks.onErrorDropped(o -> System.out.println("onErrorDropped3 called"));
    
>> onErrorDropped3 called

동작원리

// Operators.class
public static <T> void onNextDropped(T t, Context context) {
    ...
	Consumer<Object> hook = context.getOrDefault(Hooks.KEY_ON_NEXT_DROPPED, null);
	if (hook == null) {
		hook = Hooks.onNextDroppedHook;
	}
	if (hook != null) {
		hook.accept(t);
	}
	else if (log.isDebugEnabled()) {
		log.debug("onNextDropped: " + t);
	}
}

// MonoFlatMap
@Override
public void onNext(T t) {
	if (done) {
		Operators.onNextDropped(t, actual.currentContext());
		return;
	}
	...
}

// FluxMap.class
@Override
public void onNext(T t) {
	if (done) {
		Operators.onNextDropped(t, actual.currentContext());
		return;
	}
	...
}

Operator를 사용하면, 각 operator에 맞는 구현체들이 호출되는데 이는 Publisher → Mono or Flux를 상속 받은 클래스들이다.
이들은 onNext() 시 done이라는 boolean flag를 확인하며, done 되었을 때 Operators의 onNextDropped()를 호출한다.
Operators의 onNextDropped() 메서드는 onNextDroppedHook이 있으면, function을 accept한다.

Internal Error Hook

onOperatorError()는 예기치 못한 에러를 hook할 수 있는 방법이다.
operator에서 error가 발생하면 콜 되며, exception에 따른 처리 및 변경이 가능하다.

Hooks.onOperatorError((throwable, o) -> {
  if (((Integer) 0).equals(o)) {
    System.out.println("[onOperatorError] called");
    return new RuntimeException("[onOperatorError] changed");
  }
  return throwable;
});

Flux.just(1, 2, 3, 4, 0)
    .doOnNext(i -> System.out.println("element: " + i))
    .map(i -> 10 / i)
    .onErrorComplete()
    .subscribe();
    
>> element: 1
>> element: 2
>> element: 3
>> element: 4
>> element: 0
>> [onOperatorError] called

onOperatorError는 operator에 error signal이 전달 될 때 마다 hooking된다.
이는 모든 operator에 doOnError + onErrorMap을 거는 것과 유사하다.

동작원리

// Operators.class
public static Throwable onOperatorError(@Nullable Subscription subscription, Throwable error, @Nullable Object dataSignal, Context context) {
	...
	BiFunction<? super Throwable, Object, ? extends Throwable> hook = context.getOrDefault(Hooks.KEY_ON_OPERATOR_ERROR, null);
	if (hook == null) {
		hook = Hooks.onOperatorErrorHook;
	}
	if (hook == null) {
		...
		return t;
	}
	return hook.apply(error, dataSignal);
}

// FluxFlatMap.class
@Override
public void onNext(T t) {
	...
	try {
		...
	}
	catch (Throwable ex) {
		actual.onError(Operators.onOperatorError(s, ex, t, actual.currentContext()));
		return;
	}

	if (m instanceof Callable) {
		...
		try {
			...
		}
		catch (Throwable ex) {
			actual.onError(Operators.onOperatorError(s, ex, t, actual.currentContext()));
			return;
		}
		...
	}

	try {
		...
	}
	catch (Throwable e) {
		actual.onError(Operators.onOperatorError(this, e, t, actual.currentContext()));
	}
}

Operators에는 onOperatorError() 메서드를 통해 hooks에 세팅된 hook function을 불러와서 apply해준다
이는 Publisher의 구현체들에서 호출되는데, 대표적으로 onNext() 함수들의 catch문 안에서 호출 된다.

Assembly Hooks

Assembly Hooks는 Operator chain이 조립(초기화) 때 마다 호출된다.
대표적으로 onEachOperator가 있으며, chain이 추가될 때 마다 hooking된다.
일반적으로 reactor.core.publisher.Operators 클래스와 함께 사용 및 구현된다.

Hooks.onEachOperator(publisher -> {
  System.out.println("onEachOperator called");
  return publisher;
});

Flux.just(1, 2, 3, 4)
    .doOnNext(i -> System.out.println("doOnNext 1: " + i))
    .doOnNext(i -> System.out.println("doOnNext 2: " + i))
    .subscribe();
    
>> onEachOperator called
>> onEachOperator called
>> onEachOperator called
>> doOnNext 1: 1
>> doOnNext 2: 1
>> doOnNext 1: 2
>> doOnNext 2: 2
>> doOnNext 1: 3
>> doOnNext 2: 3
>> doOnNext 1: 4
>> doOnNext 2: 4

기본적인 onEachOperator의 실행 시점을 찍었다.
doOnNext(), doOnNext(), just(), 가 각각 호출(역순, chain, 조립) 될 때 onEachOperator가 실행되었다.

동작원리

// Flux.class
protected static <T> Flux<T> onAssembly(Flux<T> source) {
  Function<Publisher, Publisher> hook = Hooks.onEachOperatorHook;
  if (hook != null) {
    source = (Flux)hook.apply(source);
  }

  ...

  return source;
}

Flux.just(…) → onAssembly(…)
Flux.doOnNext(…) → doOnSignal(…) → onAssembly(…)
위 처럼 operator가 호출될 때 마다 onAssembly()가 호출 된다.
onAssembly()는 Hooks의 onEachOperatorHook를 참조하여, hook function을 apply 하는 형태로 동작한다.

LiftFunction

// Hooks.class
public static void onEachOperator(Function<? super Publisher<Object>, ? extends Publisher<Object>> onEachOperator) {
  onEachOperator(onEachOperator.toString(), onEachOperator);
}

// Operators$LiftFunction.class
final static class LiftFunction<I, O> implements Function<Publisher<I>, Publisher<O>> {
  ...
}

// Operators.class
public static <I, O> Function<? super Publisher<I>, ? extends Publisher<O>> lift(BiFunction<Scannable, ? super CoreSubscriber<? super O>, ? extends CoreSubscriber<? super I>> lifter) {
	return LiftFunction.liftScannable(null, lifter);
}
public static <O> Function<? super Publisher<O>, ? extends Publisher<O>> lift(
			Predicate<Scannable> filter,
			BiFunction<Scannable, ? super CoreSubscriber<? super O>, ? extends CoreSubscriber<? super O>> lifter) {
	return LiftFunction.liftScannable(filter, lifter);
}
public static <I, O> Function<? super Publisher<I>, ? extends Publisher<O>> liftPublisher(BiFunction<Publisher, ? super CoreSubscriber<? super O>, ? extends CoreSubscriber<? super I>> lifter) {
	return LiftFunction.liftPublisher(null, lifter);
}
public static <O> Function<? super Publisher<O>, ? extends Publisher<O>> liftPublisher(
			Predicate<Publisher> filter,
			BiFunction<Publisher, ? super CoreSubscriber<? super O>, ? extends CoreSubscriber<? super O>> lifter) {
	return LiftFunction.liftPublisher(filter, lifter);
}

Hooks의 onEachOperator는 publisher → publisher인 function을 매 operator가 chaining될 때 호출되도록 한다.
Publisher → Publisher인 Function의 구현체 class를 reactor에서 제공하며 이는 LiftFunction.class이다.
이를 생성할 수 있는 방법으로 Operators의 lift() 및 liftPublisher() 메서드들을 제공하고있다.
Operators의 lift(), liftPublisher()는 각각 LiftFunction의 static method인 liftScannable(), liftPublisher()을 호출하여 LiftFunction 인스턴스를 생성하고 있다.

lifter: (pub, sub) → sub 함수, publisher를 decorate할 수 있는 실질적인 로직이 들어간다.
name: 일반 name
filter: function의 수행여부를 판단하는 predicate

LiftPublisher()

// LiftFunction.class
static final <I, O> LiftFunction<I, O> liftPublisher(
				@Nullable Predicate<Publisher> filter,
				BiFunction<Publisher, ? super CoreSubscriber<? super O>, ? extends CoreSubscriber<? super I>> lifter) {
	Objects.requireNonNull(lifter, "lifter");
	return new LiftFunction<>(filter, lifter, lifter.toString());
}

liftPublisher를 통해 생성된 LiftFunction은 CoreSubscriber를 decorate할 수 있도록 도와준다.
내부적으로 (pub, sub) → sub 인 function을 통해 subscriber에 기능을 추가한다.

LiftScannable()

static final <I, O> LiftFunction<I, O> liftScannable(
				@Nullable Predicate<Scannable> filter,
				BiFunction<Scannable, ? super CoreSubscriber<? super O>, ? extends CoreSubscriber<? super I>> lifter) {
	Objects.requireNonNull(lifter, "lifter");

	Predicate<Publisher> effectiveFilter =  null;
	if (filter != null) {
		effectiveFilter = pub -> filter.test(Scannable.from(pub));
	}

	BiFunction<Publisher, ? super CoreSubscriber<? super O>, ? extends CoreSubscriber<? super I>>
			effectiveLifter = (pub, sub) -> lifter.apply(Scannable.from(pub), restoreContextOnSubscriberIfAutoCPEnabled(pub, sub));

	return new LiftFunction<>(effectiveFilter, effectiveLifter, lifter.toString());
}

위 liftPublisher와 비슷하지만, 특수한 lifter를 가진 LiftFunction을 만드는 static 메서드이다.
(scannable, sub) → sub인 Function으로 lifter를 만든다.
Scannable이 인자인 만큼 보다 디테일한 custom이 가능하다.

Scannable이란?
Projectreactor에서 제공하는 component의 state를 탐색할 수 있는 interface이다.
대부분의 publisher 및 subscriber가 Scannable interface를 구현했으며, 이를 통해 attribute 및 publisher chain을 탐색할 수 있다.
https://projectreactor.io/docs/core/release/api/reactor/core/Scannable.Attr.html

Hooks.onEachOperator(Operators.lift(
    (scannable, coreSubscriber) -> {
      if (scannable.tagsDeduplicated().containsKey("customTag")) {
        ...
      }
      return coreSubscriber;
    }
));

Hooks.onEachOperator(Operators.liftPublisher((publisher, coreSubscriber) -> {
  if (publisher instanceof Flux<?>) {
    ...
  }
  return coreSubscriber;
}));

Operators를 활용하는 기본 방법

public class MdcContextLifterConfiguration {
  public static final String MDC_CONTEXT_REACTOR_KEY = MdcContextLifterConfiguration.class.getName();

  @PostConstruct
  @SuppressWarnings("unchecked")
  public void contextOperatorHook() {
    Hooks.onEachOperator(MDC_CONTEXT_REACTOR_KEY, Operators.lift((scannable, subscriber) -> new MdcContextLifter(subscriber)));
  }

  @PreDestroy
  public void cleanupHook() {
    Hooks.resetOnEachOperator(MDC_CONTEXT_REACTOR_KEY);
  }

  /**
   * Helper that copies the state of Reactor [Context] to MDC on the #onNext function.
   */
  @RequiredArgsConstructor
  public static class MdcContextLifter<T> implements CoreSubscriber<T> {

    private final CoreSubscriber<T> coreSubscriber;

    @Override
    public void onSubscribe(Subscription subscription) {
      coreSubscriber.onSubscribe(subscription);
    }

    @Override
    public void onNext(T t) {
      copyToMdc(coreSubscriber.currentContext());
      coreSubscriber.onNext(t);
    }

    ...

    @Override
    public Context currentContext() {
      return coreSubscriber.currentContext();
    }

    /**
     * Extension function for the Reactor [Context]. Copies the current context to the MDC, if context is empty clears the MDC.
     * State of the MDC after calling this method should be same as Reactor [Context] state.
     * One thread-local access only.
     */
    void copyToMdc(Context context) {
      if (context != null && !context.isEmpty()) {
        Map<String, String> map = context.stream()
            .collect(Collectors.toMap(e -> e.getKey().toString(), e -> e.getValue().toString()));
        MDC.setContextMap(map);
      } else {
        MDC.clear();
      }
    }
  }
}

Reactive 환경에서 MDC context를 활용하기 위한 lifter example 이다.
@Configuration에서 Hooks에 onEachOperator로 MdcContextLifter라는 subscriber 교체를 진행한다.
MdcContextLifter는 기존 subscriber를 decorator/delegate한 구현체이다.
핵심 로직은 onNext()시 context(reactor)를 context(MDC)로 복사하는 것 이다.
// context(reactor)에 traceId를 넣는 것은 rest filter에서 subscribeContext()를 통해서 한다 (후술)

Context Propagation

일반적으로 명령형 프로그래밍 시 사용하는 ThreadLocal은 리액티브 프로그래밍에서는 문제를 야기한다.
리액티브 동작방식이 잦은 Thread의 전환이 있고, 개발자가 이를 인지하기 쉽지 않기 때문이다.
대표적으로 ThreadLocal을 활용한 MDC가 있다. 사실상 Logback에서의 MDC 활용은 문제를 야기한다.
이를 해결하기 위해 리액티브에서 3.1.0버전부터 제공하는 Context라는 기능이 있다.

ContextView, Context

Context는 immutable한 map과 유사하다.
of() : Map.of()와 유사하게, immutable한 context를 생성하는 메서드
put(), putAll() : Context가 immutable하기 때문에 값을 create or update 하여 새로운 context instance를 반환
delete() : delete() 후 새로운 instance를 반환

실제 구현체는 context안의 element 수 만큼 맴버 key, value를 갖고 있으며, contextN은 LinkedHashMap을 상속받았다.

deferContextual(Function<ContextView,? extends Publisher<T>> arg)

기본적으로 sequence는 defer()와 동일하며, contextView를 참조할 수 있는 Operator이다.

contextWrite(ContextView contextToAppend)

Context를 CUD할 수 있는 Operator이다.

Use of Context

Mono.just("object")
    .delayUntil(s -> Mono.deferContextual(contextView -> printWithThread(contextView.get("traceId")))) // print
    .contextWrite(Context.of("traceId", "2-" + UUID.randomUUID()))
    .flatMap(this::doRest) // print
    .delayUntil(s -> Mono.deferContextual(contextView -> printWithThread(contextView.get("traceId")))) // print
    .contextWrite(Context.of("traceId", "1-" + UUID.randomUUID()))
    .subscribe();
    
>> [main] 2-e646d101-1c0b-48dc-bc38-05ea1cfddff1
>> [boundedElastic-1] 1-5f7b0ed2-5823-464d-ad72-ca497787e8d5 request rest >> object
>> [boundedElastic-1] 1-8c27fbd4-0100-4f80-a765-338d08b20ea0

Context는 기본적으로 Subscription Chain 전역에서 사용되는 Map으로 이해할 수 있다.
context 생성의 주도권은 subscriber에게 있으며, 따라서 context의 전파는 chain의 끝에서부터 올라간다.
위 예제를 보면 Context는
- Scheduler와 상관없이 참조가 가능하다.
- context는 subscribe → publish로 전파된다.
를 알 수 있다.

// Kafka Consume with Micrometer Tracing Example
kafkaReceiver
    .receive()
    .flatMap(record -> {
      Observation receiverObservation =
          KafkaReceiverObservation.RECEIVER_OBSERVATION.start(null,
              KafkaReceiverObservation.DefaultKafkaReceiverObservationConvention.INSTANCE,
              () ->
                  new KafkaRecordReceiverContext(
                      record, "user.receiver", receiverOptions.bootstrapServers()),
              observationRegistry);

      return Mono.just(record)
          .doOnNext(r -> log.info("topic: {}, key: {}, value: {}", r.topic(), r.key(), r.value()))
          .doOnTerminate(receiverObservation::stop)
          .doOnError(receiverObservation::error)
          .contextWrite(context -> context.put(ObservationThreadLocalAccessor.KEY, receiverObservation));})
    .subscribe();

위 예제는 Micrometer에서 reactor-kafka로 receive할 때 tracing을 하는 예시이다.
전체 flow는
1. record와 topic을 기준으로 Observation 객체 생성
2. record 처리
3. terminate 또는 error 시에 observation의 stop 및 error 처리 호출
4. contextWrite로 observation 객체 context에 put
이다.
contextWrite는 subscribe 시점에 위로 적용해야 upstream으로 전달되기 때문에 contextWrite에서 receiverObservation 인스턴스를 넣었다.
Context의 기능 상, subscribe를 포함한 전체 로직을 개발자가 해야하기 때문에, Micrometer에서 contextWrite 기능을 library에서 제공할 수 없다.
따라서, 위 예제를 참고해 observation을 개발자가 직접 consume 로직 구현시 마다 넣어주어야 한다.

Conclusion

Hooks 및 Context는 reactor의 부가 기능이며, 직접적인 활용보다는, Library의 기능들을 이해하는데 필요하다.
Hooks는 Reactor Chaining 전반에 적용되는 기능으로, 신중하게 사용해야 한다.
Context는 Subscribe하는 시점에 상위 chain에서 참조할 값으로 사용할 수 있지만, 메인 sequance에 관여하기에는 제한적인 기능이다.

REFERENCE

https://projectreactor.io/docs/core/release/reference/#hooks

https://projectreactor.io/docs/core/release/reference/#context

https://projectreactor.io/docs/core/release/api/reactor/core/Scannable.Attr.html

Hot vs Cold Publisher (Projectreactor Advanced Features)

북극곰은콜라 — Mon, 19 Feb 2024 19:46:14 +0900

개요

Project Reactor 기능 중 심화 개념에 해당되는 파트들을 정리

Hot Publisher And Cold Publisher

일반적으로 Webflux 등에서 사용되는 Publisher들은 subscribe()가 되어야 Element를 생성한다.
이는 모두 Cold Publisher를 사용하기 때문이며, Hot Publisher는 구독과 상관없이 Element를 생성한다.
cold와 hot의 차이점은 데이터 발행의 주도권이 누구에게 있는가 이다.

Cold Publisher

Flux<String> source = Flux.fromIterable(Arrays.asList("blue", "green", "orange", "purple"))
                          .map(String::toUpperCase);

source.subscribe(d -> System.out.println("Subscriber 1: "+d));
source.subscribe(d -> System.out.println("Subscriber 2: "+d));

Subscriber 1: BLUE
Subscriber 1: GREEN
Subscriber 1: ORANGE
Subscriber 1: PURPLE
Subscriber 2: BLUE
Subscriber 2: GREEN
Subscriber 2: ORANGE
Subscriber 2: PURPLE

Cold Publisher는 Subscribe()에 따라서 Data 원천으로부터 데이터를 뽑아서 element를 만든다.
따라서 Subscriber들은 구독 시점의 데이터에 따라서 element 들이 결정된다.
일반적으로 DB, Resource, Other System등이 데이터의 원천이 되며, 요청이 있을 때 만 데이터를 쿼리해서 제공하는 것이 합리적이다.

Hot Publisher

// 공식 예제
DirectProcessor<String> hotSource = DirectProcessor.create();

Flux<String> hotFlux = hotSource.map(String::toUpperCase);

// 1번 구독자 인입
hotFlux.subscribe(d -> System.out.println("Subscriber 1 to Hot Source: "+d));

hotSource.onNext("blue");
hotSource.onNext("green");

// 2번 구독자 인입
hotFlux.subscribe(d -> System.out.println("Subscriber 2 to Hot Source: "+d));

hotSource.onNext("orange");
hotSource.onNext("purple");
hotSource.onComplete();

DirectProcessor는 deprecated된 개념으로 Sinks로 대체되었다.

Sinks.Many<String> hotSource = Sinks.many().multicast().onBackpressureBuffer();
Flux<String> hotFlux = hotSource.asFlux().map(String::toUpperCase);

// 1번 구독자 인입
hotFlux.subscribe(d -> System.out.println("Subscriber 1 to Hot Source: "+d));

hotSource.tryEmitNext("blue");
hotSource.tryEmitNext("green");

// 2번 구독자 인입
hotFlux.subscribe(d -> System.out.println("Subscriber 2 to Hot Source: "+d));

hotSource.tryEmitNext("orange");
hotSource.tryEmitNext("purple");
hotSource.tryEmitComplete();

Subscriber 1 to Hot Source: BLUE
Subscriber 1 to Hot Source: GREEN
Subscriber 1 to Hot Source: ORANGE
Subscriber 2 to Hot Source: ORANGE
Subscriber 1 to Hot Source: PURPLE
Subscriber 2 to Hot Source: PURPLE

Hot Publisher는 subscriber의 호출과 별도로 element를 발행하는 publisher로 볼 수 있다.
따라서 구독자가 없어도 element는 발행할 수 있으며, 발행 주도권은 publisher에게 있다.

Create Hot Publisher

just()

final class MonoJust<T> extends Mono<T> implements Fuseable.ScalarCallable<T>, Fuseable, SourceProducer<T> {
  final T value;

  MonoJust(T value) {
    this.value = Objects.requireNonNull(value, "value");
  }
  ...
}

just()로 생성하는 MonoJust, FluxArray 등 Publisher는 대표적인 Hot Publisher이다.
생성자로 value 속성을 사전에 세팅하고 이를 하위 Sequence로 전달하기 때문이다.

public void doSomeThings() {
  Mono.just(this.createString());
}
private String createString() {
  String s = "string";
  System.out.println("out: " + s);
  return s;
}

-----------------------------
out: string

실제로 아무도 subscribe하지 않았지만, createString() 메서드는 호출이 되었다.

// 명시적으로 success sink시에 실행
Mono.create(monoSink -> monoSink.success(this.createString()));

// lazy하게 실행하기 위해 defer()를 사용
Mono.defer(() -> Mono.just(this.createString()));

Cold하게 생성하면 의도되지 않은 메서드 호출을 방지할 수 있다.
하지만, cold하게 동작하기 때문에, createString은 element 마다 호출된다.

publish()

ConnectableFlux는 Flux의 publish()로 생성되는 Hot Publisher이다.
cold → hot으로 변경하는 대표적인 방법이다.
자세한 사항은 후술

cache()

public final Flux<T> cache(int history) {
  return this.replay(history).autoConnect();
}

public final ConnectableFlux<T> replay(int history) {
  return history == 0 ? onAssembly((ConnectableFlux)(new FluxPublish(this, Queues.SMALL_BUFFER_SIZE, Queues.get(Queues.SMALL_BUFFER_SIZE), false))) : onAssembly((ConnectableFlux)(new FluxReplay(this, history, 0L, (Scheduler)null)));
}

cache() 또한 hot publisher로 만들 수 있는 방법이다.
내부적으로는 ConnectableFlux를 생성하고, element 제공 방식 중 buffer를 통한 캐싱방식으로 동작한다.
자세한 사항은 후술

ConnectableFlux

// Publisher 생성
Flux<Integer> source = Flux.range(1, 3)
                           .doOnSubscribe(s -> System.out.println("subscribed to source"));

// ConnectableFlux로 변경
ConnectableFlux<Integer> co = source.publish();

// 구독자 1
co.subscribe(System.out::println, e -> {}, () -> {});
// 구독자 2
co.subscribe(System.out::println, e -> {}, () -> {});

System.out.println("done subscribing");
Thread.sleep(500);
System.out.println("will now connect");

// upstream 구독자들을 트리거
co.connect();

done subscribing
will now connect
subscribed to source
1
1
2
2
3
3

기본적인 흐름은 ConnectableFlux에 subscribe()한 구독자는 즉시 element를 전달받는 것이 아니라
ConnectableFlux가 준비되고 connect()를 호출해야 element를 전달 받는다.
이는 Publisher가 여러 subscriber들이 구독하기를 기다렸다가, 한번에 publish(broadcasting)할 수 있는 방법이다.

ConnectableFlux와 BackPressure

Projectreactor는 BackPressure가 핵심 개념 중 하나이다.
얼핏 ConnectableFlux는 BackPressure에 정면으로 위배하는 것처럼 보인다.
ConnectableFlux는 이를 해결하기 위한 두 가지 방법을 제시해준다.
1. publish()를 통한 생성: 동적으로 여러 구독자들의 demand를 모니터링 하며, 하나라도 구독자가 pending된다면, 즉시 소스로의 요청을 중단한다.
2. replay()를 통한 생성: 첫 번째 구독 데이터를 버퍼링하며, 이후 구독자에게 demand에 따라서 이 데이터를 제공한다.
위 와 같은 방식으로 ConnectableFlux는 BackPressure를 유지하는 정책을 가지고 있다.

cache with ConnectableFlux

final class FluxReplay<T> extends ConnectableFlux<T> implements Scannable, Fuseable, OptimizableOperator<T, T> {
  final CorePublisher<T> source;
  ...

  public final CoreSubscriber<? super T> subscribeOrReturn(CoreSubscriber<? super T> actual) throws Throwable {
    while(true) {
      // replay용 subscriber 생성
      ReplaySubscriber<T> c = this.connection;
      ...

      // 전달받은 subscriber와 ReplaySubscriber로 ReplayInner 생성
      ReplayInner<T> inner = new ReplayInner(actual, c);
      ...

      // 앞에 생성한 ReplaySubscriber의 buffer를 통해 ReplayInner를 Replay
      c.buffer.replay(inner);
      ...
    }
  }
  ...

  static final class ReplayInner<T> implements ReplaySubscription<T> {
    final CoreSubscriber<? super T> actual;
    final ReplaySubscriber<T> parent;
    int index;
    int tailIndex;
    Object node;
    int fusionMode;
    long totalRequested;
    ...
  }

  // ReplayBuffer의 구현체를 가지고 있음
  static final class ReplaySubscriber<T> implements InnerConsumer<T>, Disposable {
    final ReplayBuffer<T> buffer;
    ...
    
    public void onNext(T t) {
      ReplayBuffer<T> b = this.buffer;
      if (b.isDone()) {
        Operators.onNextDropped(t, this.currentContext());
      } else {
        ++this.produced;
        // onNext가 처리될 때 마다 buffer에 value를 추가
        b.add(t);
        ...
      }
    }
  }
  
  static final class UnboundedReplayBuffer<T> implements ReplayBuffer<T> {
    ...
    // subscribe mode에 따른 
    public void replay(ReplaySubscription<T> rs) {
      if (rs.enter()) {
        if (rs.fusionMode() == 0) {
          this.replayNormal(rs);
        } else {
          this.replayFused(rs);
        }

      }
    }
    
    ...
    
    void replayNormal(ReplaySubscription<T> rs) {
      int missed = 1;
      Subscriber<? super T> a = rs.actual();
      ...

      do {
        ...
        // node(element값)들을 ReplayInner에서 가져옴
        Object[] node = (Object[])((Object[])rs.node());
        ...
        while(e != r) {
          ...

          // 현재 index가 buffer된 사이즈라면, 다음 값을 가져오기 위해 break
          empty = index == this.size;
          if (empty) {
            break;
          }
          
          
          // tailIndex는 현재 처리할 노드
          T v = node[tailIndex];
          a.onNext(v);
          // index를 한칸 뒤로
          ++tailIndex;
          ++index;
          ...
        }

        ...

        rs.index(index);
        rs.tailIndex(tailIndex);
        rs.node(node);
        ...
      } while(missed != 0);
    }
  }

  static final class SizeBoundReplayBuffer<T> implements ReplayBuffer<T> {
    // 사이즈가 정해진 replay 시나리오, 중첩구조를 가진 Node(AtomicReferenece + index)를 사용
    // 나머지는 UnboundedReplayBuffer와 대동소이
    ...
  }

  static final class SizeAndTimeBoundReplayBuffer<T> implements ReplayBuffer<T> {
    // 사이즈와 time이 정해진 시나리오, 중첩구조를 가진 TimeNode(AtomicReferenece + index + time)를 사용
    // 나머지는 UnboundedReplayBuffer와 대동소이
    ...
  }

  ...
}

cache()의 동작방식은
1. 최초 subscribe시 buffer에 처리된 값을 넣고
2. 이후 subscribe는 buffer에서 값을 빼서 전달해주는 방식

cache() 또한 ConnectableFlux을 확장한 FluxReplay를 사용하기 때문에
Hot Publisher로 분류된다.

Conclusion

일반적인 Backpressure 개념과 어울리는 cold와 다르게, hot Source은 publisher 쪽에서 주도적으로 element를 발행한다.
Hot Publisher는 Hot Source를 취급할 수 있는 Publisher이며, 대부분 reactive를 지원하는 프레임워크 및 라이브러리에서 사용 중이다.

대부분의 비즈니스는 cold 만으로 충분하다.
일부 비즈니스는 cold → hot으로 전환하는 것이 유리하지만, hot publisher는 backpressure buffer, replay 정책등을 잘 고려해서 사용해야 한다.

REFERENCE

https://projectreactor.io/docs/core/release/reference/#advanced

https://m.blog.naver.com/gngh0101/221560774000

Clean Code in Reactive

북극곰은콜라 — Thu, 25 Jan 2024 17:56:18 +0900

개요

Reactive 모델은 익숙한 기존 Thread 모델보다 가독성이 떨어지는 이슈가 있다.
이러한 문제는 Reactive의 한계가 아닌, 코드를 작성할 때 가독성을 고려하지 않고 작성하면 발생한다.
이번 리뷰는 가독성 좋은 Reactive 코드를 위한 개념들에 대해 정리한다.

1. 비즈니스 로직은 Operator가 기준이 된다.

userService.getFavorites(userId) 
           .map(Favorite::toRequestModel)
           .flatMap(favoriteService::getDetails)

Reactive 모델은 Data Flow가 곧 비즈니스이다.
Data Flow는 결국 비즈니스의 “행위”가 되며, 행위는 operator의 묶음으로 표현하게 된다.
이는 결국 추후 Reactive 코드를 읽을 때 operator를 기준으로 비즈니스를 이해하게 되도록 만든다.

위 예제의 비즈니스 해석은
1. userService에서 유저가 좋아하는 것들을 가져온다. (Create Data Flow)
2. requestModel로 변환한다. (change data format)
3. favoriteService로 부터 details를 가져오는 스트림으로 변환한다. (to another data flow)

1-1. Operator를 기준으로 구분을 나눈다.

// Reactive Operator is the key to Reactive programming

//Bad
userService.getFavorites(userId).map(Favorite:toRequestModel)
           .flatMap(favoriteService::getDetails) 
 
// Good
userService.getFavorites(userId) 
           .map(Favorite::toRequestModel)
           .flatMap(favoriteService::getDetails)

코드를 읽을 때, 위 → 아래, 왼쪽 → 오른쪽 으로 읽는다.
operator를 수직으로 배열하여, 하나의 행위를 하나의 라인으로 배치되도록 하면 가독성이 높아진다.

1-2. Operator간의 간격을 줄인다.

// Reduce the distance between Operators

//Bad
userService.getFavorites(userId)
           .map { 
               val (favorites, user) = it
               val userRequest = user.toUserRequest()
               GetFavoriteDetailRequest(
                   favorites = favorites,
                   user = userRequest
               )
            }
           .flatMap(favoriteService::getDetails) 
  
//Good
userService.getFavorites(userId)
           .map(this:toRequestModel)
           .flatMap(favoriteService::getDetails) 
  
fun toRequestModel(input: Tuple2<Favorites, Users>) {
     val (favorites, user) = input
     userRequest = user.toUserRequest()
     GetFavoriteDetailRequest(
        favorites = favorites,
        user = userRequest
     )
}

operator간의 간격이 길어지면, 개발자는 비즈니스를 해석하기 위해 많은 라인을 읽어야 한다.
따라서 길어지는 내부 로직을 별도의 function으로 정의하여, 피로도를 줄인다.

이 방식은 function의 name으로 내용을 충분히 설명할 수 있어야한다.
너무 포괄적인 function naming은 오히려 가독성을 떨어뜨릴 뿐 아니라, 혼란을 가중시킨다.
ex) Map<String, Object> getOthers()
→ 다른 무언가를 가져오는 함수로 보이지만, 구체적인 내용을 알 수 없어 개발자가 무조건 해당 함수를 들여다 보아야 한다.

1-3. 적절한 Operator 사용

// Use Operators matching the name

//Bad
userService.getFavorites(userId)
           .map { 
               log.info("Received favoirtes, $it")
               it.toRequestModel()
            }
           .flatMap(favoriteService::getDetails) 
  
//Good
userService.getFavorites(userId)
           .doOnNext { log.info("Received favoirtes, $it") }
           .map(this:toRequestModel)
           .flatMap(favoriteService::getDetails)

operator를 적절히 사용하는 것이 가독성을 높이는 방법이다.
위 log.info()는 로깅 작업으로, map Operation이랑 전혀 관련이 없다.
이를 분리하여 가독성을 높일 수 있다.

2. Operation 결과는 Null 대신 empty()

// Null equivalent in reactive is Empty

//Bad
Flux.just("a", "b", "c", "d")
        .flatMap(s -> {
          if (s.equals("b")) {
            return null;
          }
          return Mono.just(s);
        })
        .filter(Objects::nonNull)
        .doOnNext(log::info)
        .subscribe();

//Good
Flux.just("a", "b", "c", "d")
        .flatMap(s -> {
          if (s.equals("b")) {
            return Mono.empty();
          }
          return Mono.just(s);
        })
        .doOnNext(log::info)
        .subscribe();

Operation의 결과는 Null이 아닌 Empty로 처리한다.
NPE의 위험 뿐 아니라, Null Check 로직은 가독성을 배로 힘들게 만든다.

3. Method Reference 사용

// Use a method reference

// Bad
userService.getUser(userId)
           .map { it.toFavoriteReq() }
           .flatMap { 
               favoriteService
                       .getFavorites(it)
                       .flatMap { 
                          favoriteService.getDetails(it.toDetailRequest) 
                       }
  
           }
  
// Good 
userService.getUser(userId)
           .map(User::toFavoriteReq)
           .flatMap { favoriteReq ->
               favoriteService
                       .getFavorites(favoriteReq)
                       .map(Favorite:toDetailRequest)
                       .flatMap(favoriteService::getDetail) 
                            
           }

Method Reference는 variable을 숨기며, 가독성을 높인다.
zip 등 일부 Operator를 제외하면, 모두 넘어오는 인자는 단건이며, 이는 생략하여 가독성을 높일 수 있다.

4. Operator의 분리

// Don’t let Collection API shadow Operators

//Bad
Flux.just("abcd", "1234")
        .flatMap(s -> Flux.fromIterable(Arrays.stream(s.split(""))
            .map(c -> c + "X")
            .collect(Collectors.toList())))
        .doOnNext(log::info)
        .subscribe();
        
//Good
private Stream<String> mapToX(final Stream<String> upstream) {
  return upstream.map(s -> s + "X");
}

Flux.just("abcd", "1234")
        .flatMap(s -> Flux.fromIterable(
            this.mapToX(Arrays.stream(s.split("")))
                .collect(Collectors.toList())))
        .doOnNext(log::info)
        .subscribe();
        
//Kotlin
private fun <T, R> Iterable<T>.streamMap(transform: (T) -> R): List<R> = this.map(transform)

Flux.just("abcd", "1234")
            .flatMap { Flux.fromIterable(it.toCharArray().toList().streamMap { c -> c + "X" }) }
            .doOnNext{println(it)}
            .subscribe()

Reactor의 map과 java streams의 map은 operation 이름이 중복된다.
이는 혼동을 불러올 수 있기 때문에, Function을 분리하여 사용한다.

5. Publisher Type 변수명

// Make variable name distinguishable

// Bad
val numberKor = Mono.just("hana")
val numberEng = Flux.just("one", "two")
numberEng
      .zipWith(numberKor)
      .doOnNext { zipped ->
         val (eng, kr) = zipped
         log.info("English:$eng, Korean:$kr")
       }
  
// Good
val numberKorMono = Mono.just("hana")
val numberEngFlux = Flux.just("one", "two")
  
numberEngFlux
     .zipWith(numberKorMono)
     .doOnNext { zipped ->
        val (eng, kr) = zipped
        log.info("English:$eng, Korean:$kr")
     }

Mono 또는 Flux 타입의 변수를 사용할 때, 기존 변수들과 차이를 두고 naming 해야한다.
명확하게 해당 변수는 Publisher를 의미한다고 알려줘야, 혼동이 없다.

6. 비즈니스 내 직접적인 subscibe() 피하기

// Avoid calling subscribe() directly

// Bad
userService
         .getUser(req)
         .flatMap(userService::changePassword)
         .doOnNext {
              auditLogger
                      .auditLog(it)
                      .subscribe()
         }

비즈니스에서 직접적인 subscribe()가 늘어나면, 좀비 프로세스가 발생할 수 있다.
이는 시스템에 큰 부담으로 작용하기 때문에 피해야 한다.
별도의 Subscribe를 담당하는 모듈을 만들어 관리하는 방안이 필요하다.

7. Log는 Operation과 함께 작성

//Bad
public Mono<String> funcA() {
  log.info("funcA() process");
  
  return Mono.just("a")
}

public Mono<String> service() {
  Mono<String> a = funcA();
  
  // no process with a
  return Mono.just("b");
}

-----------------------------------------------------------
//Good
public Mono<String> funcA() {
  return Mono.just("a")
    .doOnNext(s -> log.info("funcA() process"))
}

public Mono<String> service() {
  Mono<String> a = funcA();
  
  // no process with a
  return Mono.just("b");
}

일반적으로 로그는 특정 프로세스의 현 상태 또는 프로세스 기록을 남긴다.
reactive 환경에서는 [함수의 호출 != 데이터 처리] 이기 때문에 로그는 operation과 함께 작성해야 오해가 생기지 않는다.

8. reusable Method 작성

//Bad
public Flux<Article> getUserArticle(final User user) {
  return articleService.findAllByUserId(user.getUserId)
}

//Good
public Flux<Article> getUserArticle(final String userId) {
  return articleService.findAllByUserId(userId)
}

지속적으로 늘어나는 함수를 줄이기 위해서는, 함수의 재사용은 필수이다.
재사용 가능한 함수를 위해서는, 특정 service 또는 vo에 종속적이지 않은 함수를 작성하는 것이 바람직하다.

Conclusion

Reactive Code의 가독성을 높이기 위한 방법
1. 적절한 Operator를 사용한다.
2. 함수는 하나의 기능만 하도록 한다.
3. 변수 명 및 함수 명에 공을 들인다.
로 요약할 수 있다.

clean code를 지향할 때, 좋은 방법 중 하나는 꼼꼼한 코드리뷰가 있다.
이후 코드 리뷰 시 변수 명 및 함수 명을 다 같이 확인하고, 논의를 거쳐 최종 merge 되는 과정이 코드 품질에 도움이 될 것으로 생각한다.

당연한 이야기들로 보이기 때문에, 자주 간과하게 되는 것들이다...

REFERENCE

GraphQL Overview

북극곰은콜라 — Mon, 15 Jan 2024 10:32:39 +0900

GraphQL 이란

META에서 개발한 Query Language over HTTP.
SQL이 Application → DB로 데이터를 쿼리하는 언어라면, GraphQL은 Application → Server로 데이터를 쿼리하는 언어

GraphQL is for…

Client ↔︎ Server 간의 Data Provide Mismatch를 해결하기 위해 개발된 언어
No more Overfetching, Underfetching
데이터의 제공 주체는 서버이며, 서버는 다수의 client를 위한 서비스를 제공하기 때문에, 데이터에 기반하여, API를 제공한다.
이에 client는 필요한 Data 이외의 데이터를 함께 제공받거나(overfetching), 필요한 데이터를 모으기 위해 여러번 호출 (underfetching, n+1) 해야 하는 상황이 발생할 수 있다.

Client n+1?

client가 특정 게시자의 게시글 내용 전체를 쿼리하고 싶다면
일반적으로 다음의 과정을 따른다
1. GET /xx/list API를 통해 xx의 특정 게시자 게시글 list를 받는다
2. GET /xx/{id} API를 통해 1번 쿼리된 게시글 수 만큼 요청한다.
이에 list요청 1번, 세부 게시글 n번의 요청이 필요하다.
서버에서 전용 API를 만들어 줄 수 있지만, 이는 장기적으로 부적절하다.

GraphQL 장단점

장점

1. Overfetching, Underfetching을 해결할 수 있다.
+응답 Size를 줄일 수 있다.
2. Endpoint 및 request parameter, response Object 등 정의를 줄인다.
3. 데이터 제공 로직이 간소화된다.
- Data의 Depth와 상관없이 한번에 쿼리가 가능하다.
- 표준화된 요청 로직 작성 가능
- 한번에 여러 Type의 Data를 쿼리 할 수 있다.
4. 서버 ↔︎ 클라이언트의 커플링 일부 감소 효과… (ex: data type 변경 시 api 사용자가 아닌, 해당 데이터를 사용하는 client에게만 영향)

단점

1. 서버 ↔︎ 클라이언트 간의 소통방식의 변화: client는 Data 구조에 대한 이해가 필요하고, server는 client에게 데이터 변화를 고지해야 함
2. Data 설계의 복잡성 증가: client가 쿼리를 작성하기 때문에, Data 설계 시 많은 경우의 수를 고려해야 함
3. HTTP 캐싱 이점을 활용하기 힘들다: Endpoint가 하나 이기 때문
4. 에러 핸들링 난이도가 상승: 하나에 요청에 n개의 에러가 발생할 수 있기 때문
5. 요청 및 응답이 무거워질 수 있다: 뎁스가 높아지거나, 데이터 자체가 큰 경우에 대해 서버에서 핸들링 하기가 힘들다
6. MSA 구조에 대응하기 위해 다른 솔루션이 필요: MSA 구조에서 client가 각 서버로 graphQL 쿼리를 하면, 기존 목적에 위배되는 상황 발생 (후술)
7. 파일업로드는 통합 불가

Concepts

Document

query {
  author(limit: 5) {
    id
    name
    articles {
      id
      title
      content
    }
  }
}

GraphQL의 Request String(Body)를 documnet라고 한다.

Fields

author, id, name, article, id, title, content가 field이다.

Arguments

author(limit: 5)의 limit 부분이 Arguments이다.

Variables

{
  limit: 5
}

query($limit: Int) {
  author(limit: $limit) {
    id
    name
    articles {
      id
      title
      content
    }
  }
}

위 쿼리의 Argument를 Variables로 바꿔서 쓰는 방법
limit: 5로 variable을 선언하고, 쿼리에서 해당 variable을 사용한다.

Aliases / Fragments

// Alias
query fetchAuthor {
  author(id: 1) {
    name
    profile_pic_large: profile_pic(size: "large")
    profile_pic_small: profile_pic(size: "small")
  }
}

// Fragments
fragment authorFields on author {
  id
  name
  profile_pic
  created_at
}

query fetchAuthor {
  author(id: 1) {
    ...authorFields
  }
}

query fetchAuthors {
  author(limit: 5) {
    ...authorFields
  }
}

Alias는 response 받을 값을 다르게 지정하여 return 받기 위한 방법
Fragments는 query template를 만들어서 재사용하기 위한 방법

Operation

GraphQL는 크게 3가지 동작을 가진다.
1. Fetching: Read dataMutation:
2. CUD data
3. Subscription: Realtime update (over websocket)

Fetching

{
  author {
    id
    name
  }
}

author의 id와 name을 쿼리하는 예시

Mutation

mutation {
  insert_todos(objects: [{ title: "New Todo" }]) {
    returning {
      id
      title
      is_completed
      is_public
      created_at
    }
  }
}

“new todo”라는 object를 insert하고, response로 id 등 서버 생성 값을 받는 예시

Subscription

subscription {
  todos {
    id
    created_at
    is_completed
    is_public
    title
  }
}

todos에 대한 신규 데이터를 실시간으로 제공 받는 operation 예시

Apollo Federation

MSA 구조에서 GraphQL을 적용하게 되면, 수 많은 서버로 각각 GraphQL요청을 보내야 한다.
이는 over/underfetching을 방지하기 위한 GraphQL의 근본 사상을 위협하게 된다.
Apollo팀에서는 이를 해결하기 위해 router를 통한 graph 연동으로 솔루션을 제공한다.

Router는 Root로 할당되며, 각 GraphQL API 서버들을 하위 뎁스로 갖는다.
client는 router를 통해 GraphQL 통신을 하며, Router가 각 API 서버로 Data를 Fetching해주는 역할을 한다.

사례 & 인사이트 (중복 내용 제거)

Naver (2020)

강점:
- 강력한 개발자 경험 제공: Client가 Data Schema를 이해하고 쿼리를 작성할 수 있음, 이는 투명한 정보를 통해 client의 책임 있는 API 호출을 유도함
- 성능 이점: 모바일 디바이스처럼 한정된 네트워크 대역폭 또는 한정된 리소스인 경우, 원 쿼리를 통한 데이터 access는 큰 이점을 가짐
- 안정적인 subscription: 원하는 data만 구독하여 실시간 데이터 처리를 효율적으로 할 수 있음

- Schema 관리를 위한 모니터링 툴이 필수
- schema 버전 관리가 필수
- Data Schema 설계를 GraphQL의 관계 중심으로 설계해야 함
- Data Graph를 관리하기 위한 비용이 적지 않음

Kakao

gql은 퍼포먼스적인 장점이 분명 존재합니다. 하지만 개인적으로 더 관심이 가는 장점은 바로 생산성 향상입니다. gql은 기존 백앤드-프론트앤드 협업 문화를 많이 바꿀것으로 예상합니다. gql의 협업 구조상 프론트앤드쪽에 조금 더 할일이 많아지고 힘이 실리는 느낌입니다. 에자일하게 웹사이트 프로젝트를 진행하는데 gql이 많은 도움이 될 것이라고 생각합니다.
개발자 여러분에게 안타까운 소식을 전하자면, 이 글을 읽었다고 해서 gql을 바로 실전에서 사용하기는 쉽지 않을 것입니다. 이 글에서는 gql의 클라이언트 모듈에 대해서는 구체적으로 언급하지도 않았습니다. 특히 react를 혼합해서 사용하려면, 또 다시 가파른 고개를 넘어서야 제대로 사용 할 수 있을 것입니다.
…

Google Cloud

그래프를 데이터 중심 계층 구조로 취급

- GraphQL은 Data에 Access 할 수 있는 하나의 계층으로 취급해야 합니다.
- REST의 /a의 GET, POST는 a 객체를 조회/추가 한다고 하듯이, GraphQL의 Query 및 operation도 그러해야 합니다.
- GraphQL을 활용할 때 빠지기 쉬운 함정은 operation 시 이를 함수처럼 사용하는 경우 입니다.
- 함수로 취급하여 operation하면, 점점 데이터 스키마와 멀어지게 되며, 이는 schema를 더 이상 관리할 수 없는 상황이 발생 함

GraphQL을 고집하지 않기

- GraphQL은 항상 최선의 선택이 아니라는 것을 염두 해야 한다.
- GraphQL은 REST의 대체제가 아닌, 선택사항이며, 데이터 구조 상 REST가 더 적합한 경우도 많다.
- 가령 4번째 depth안의 모든 name에 대한 조회를 한다면, graphQL은 쿼리의 비대함 뿐 아니라, 서버의 부답을 작용할 것

AWS

GraphQL이 유리한 경우
- 대역폭이 제한되어 있으며 요청 및 응답 수를 최소화하려는 경우
- 여러 데이터 소스가 있고 이를 하나의 엔드포인트에서 결합하려는 경우
- 고객의 요청이 매우 다양하고 기대하는 응답도 크게 다른 경우

REST가 유리한 경우
- 애플리케이션 규모가 작고 데이터가 덜 복잡한 경우
- 모든 클라이언트에서 유사하게 사용되는 데이터와 작업이 있는 경우
- 복잡한 데이터 쿼리가 필요 없는 경우

Conclusion

GraphQL 도입 시의 이점 대비 리스크 및 단점이 너무 크게 다가온다.
장단점을 미루어 보았을 때, 비즈니스 Data 구조가 depth가 적고 wide하게 확장되는 상황에서 매우 유용할 것으로 생각된다.
- depth가 늘어날 수록 서버의 성능 부담이 크게 증가한다. 하지만, 클라이언트가 서버의 부담을 고려하여 쿼리를 하는 것은 말이 안된다. 반면 wide한 data가 많아질 수록 클라이언트의 호출 수가 증가하게 된다.
여러 사례를 보았을 때, 비즈니스 또는 데이터 구조에 따라서 GraphQL 도입 여부를 결정하는 것이 바람직 하다.

REFERENCE

https://hasura.io/learn/graphql/intro-graphql/core-concepts/

https://www.howtographql.com/basics/1-graphql-is-the-better-rest/

https://www.apollographql.com/docs/federation/

https://deview.kr/data/deview/session/attach/1100_T1_박성현_GraphQL API 까짓거 운영해보지 뭐.pdf

Netflix OSS란 (feat. Service Mesh)

북극곰은콜라 — Fri, 5 Jan 2024 15:21:18 +0900

개요

1. Netflix OSS 및 Spring Cloud Netflic 구성 요소 소개
2. Spring with Netflix에서 제시한 MSA 구조 소개
3. 부록으로 MSA 서비스간의 통신을 infra로 풀어낸 side-car 패턴의 구성방안에 대해 소개

Service Mesh란?

Service Mesh는 여러 서비스(MSA등)간의 의사소통을 책임지는 Layer를 말한다.
Layer가 어떻게 구성되는지 장단점이 존재하며, 각 솔루션들이 존재한다.

방식	솔루션	설명
PaaS	Azure fabric, lagom…	플랫폼 서비스로 mesh구조를 풀어낸 방안 개발자는 Mesh 구성 및 동작에 대해서 신경 쓰지 않는다. Framework 형태로 제공되며, 특화된 코드를 필요로 합니다.
Side car Proxy	Istio, Consul…	Service 형태로 mesh구조를 관리하는 방안 sideCar 패턴으로 Application에 Binding 된다. 개발자는 sideCar를 바라보고 호출하며, sideCar들에 대한 control을 중앙에서 한다. 이는 오케스트레이션에 매우 유리한 구조로, 쿠버네티스와 조합이 많이 된다.
Library	Netflix OSS, Spring Cloud	라이브러리 형태로 mesh구조를 제공하는 방안 개발자는 library API를 통해 직접 Service Mesh를 구성 및 Custom 할 수 있다.

Netflix OSS 란?

Netflix는 2007년 DB 문제로 인한 서비스 중단을 겪고 나서, 신뢰성 높고 scale-out이 가능한 시스템을 구축하기로 결정했다.
Netflix는 명확한 목적성을 가지고 신규 시스템 개발을 진행했다.
- 고가용성: fail-over처리, 장애 확산 방지 등 서비스 안정성 확보
- scale-out: 수평적 확장이 가능한 시스템
- Easy Deploy: 손쉬운 배포 / 관리 환경
Netflix는 위 목적성을 가지고 7년 이상 개발을 진행했으며, 그 노하우를 Netflix OSS라는 이름으로 공개하였다.
2015년 Spring은 Netflix OSS를 Integration한 Spring Cloud Netflix 1.0 Release
2018년 Netflix가 Spring Cloud Netflix 기여

Spring Cloud Netflix?

Spring Cloud Netflix provides Netflix OSS integrations for Spring Boot apps through autoconfiguration and binding to the Spring Environment and other Spring programming model idioms. With a few simple annotations, you can quickly enable and configure the common patterns inside your application and build large distributed systems with battle-tested Netflix components. The patterns provided include Service Discovery (Eureka).

Spring with Netflix OSS

https://dzone.com/articles/microservices-journey-from-netflix-oss-to-istio-se

항목	상세
Eureka	Service Discovery를 담당하는 모듈 Service Registry (ex: Zookeeper)와 연동하여, Enable 된 Service정보를 찾을 수 있게 하는 역할
API gateway Zuul	Single Endpoint를 제공해주는 모듈 MSA 구조에서 쪼개진 Service들을 통합하여 사용하는 효과를 보이고, 인증 등 공통으로 필요한 기능을 통합 관리 할 수 있다. Zuul은 API Gateway의 구현체에 해당되며, 핵심은 filter를 통해 pre → routing → post → error 단계로 요청을 수행하는 구조를 가지고 있다.
Ribbon	Client Side Load Balancer 정적 분산 또는 Eureka와 연동하여 동적 분산도 가능 분산 룰을 custom 할 수 있으며 netflix는 지역별 서버 대응하기 위해 사용 (Zone Aware Load Balancer)
hystrix	Circuit breaker MSA 환경에서 장애 확산을 최대한 억제하기 위한 circuit breaker 서비스 장애, 응답지연, 과 트레픽 상황의 전체 시스템으로 확산 되는 것을 막을 수 있다.
Config Server	통합 Config 관리 외부에서 config를 주입받을 수 있는 기능을 제공
OpenFeign	MSA의 네트워크 Client를 제공

Spring Cloud에서 제시하는 MSA 구조

전체 application의 config 관리, 모니터링, 장애 확산 방지, 서비스 디스커버리 등 MSA 환경의 scale-out, 고가용성을 제공할 수 있는 구조
다수의 유사한 서비스를 scale-out할 수 있는 구조에 대한 예시이다.

Appendix: Side Car Proxy를 통한 Service Mesh 구성

Sidecar Pattern

모든 Application(Container)에 추가로 sidecar(Container)를 배포하고 Application의 통신은 sidecar를 통해서 진행하도록 세팅
Service ↔︎ Service간의 직접 통신을 infra로 분리하여 MSA 환경의 필요 기능을 비즈니스에서 분리합니다.
MSA 운영 배포에 필요한 기능을 sidecar가 가지는 구조는, Application의 수정 없이, MSA 환경에 대응할 수 있는 이점을 기집니다.
sidecar로 Istio, Consul 같은 솔루션들은 MSA 환경에서 필요한 대부분의 기능들을 제공
- Service Discovery
- load balancing
- Dynamic Routing
- Circuit Breaking
- TLS
- 인증
- Health check, retry,timeout
- Metric

REFERENCE

https://spring.io/projects/spring-cloud-netflix/

https://bravenamme.github.io/2020/07/21/msa-netflix/

https://programmaticponderings.com/2016/02/15/diving-deeper-into-getting-started-with-spring-cloud/

https://velog.io/@tedigom/MSA-제대로-이해하기-4Service-Mesh-f8k317qn1b

Spring Properties from Lib Resources (PropertySourcesPlaceholderConfigurer, EnvironmentPostProcessor)

북극곰은콜라 — Tue, 2 Jan 2024 17:07:41 +0900

개요

Spring 프로젝트의 Properties를 구성하는 방법은 여러 가지가 있다.
그중 프로젝트 외부(external jar)의 resources에서 Load 하여 추가하는 방법에 대해 정리하고자 한다.

문제 상황

1. Github Project를 public으로 설정하면 일부 정보들은 노출되지 않도록 관리해야 한다.
ex) db password.. etc

2. Multi Project 구조 같이 공통적으로 적용되어야 하는 Properties를 따로 관리해야 할 때
ex) Actuator 설정, 접속정보 등

Properties file을 Runtime에 외부에서 Load 하게 되면 위 문제상황을 해결할 수 있다.
일반적으로는 Server에 관리되는 Properties 파일을 두고 runtime 시점에 로드하거나, System Properties로 설정하는 방법을 사용한다.
이번에 소개하는 방식은, lib(jar) 안에 들어있는 Properties 파일을 runtime 시점에 load 하는 방법이다.

PropertySourcesPlaceholderConfigurer

PropertySourcesPlaceholderConfigurer는 Context에 적용된 Properties에 접근하여 작업을 할 수 있는 config bean이다.
org.springframework.core.env의 PropertySources를 통해 get/set 할 수 있다.

PropertySourcesPlaceholderConfigurer 분석

Member Variables	Desc
MutablePropertySources propertySources	적용할 PropertySource 들
PropertySources appliedPropertySources	기존에 적용된 PropertySource들
Environment environment	Spring Context

Method	Desc
void setPropertySources(PropertySources propertySources)	PropertySources를 추가할 수 있는 method이다. configurer당 1개의 PropertySources(Iterable)을 가지며 최종 적용 시 기존 Sources에 추가된다.
PropertySources getAppliedPropertySources()	Runtime 상 설정된 Properties를 가져오는 method PropertySources를 add할 수 있다. 대부분 자동설정되는 property는 immutable 하다.

configurer에서 주로 사용되는 property getter, setter들이다.
그 외 상위 클래스의 method를 활용해서 세팅하는 것도 가능하다.

Secret Application Yaml 적용

@Bean
@ConditionalOnResource(resources = "classpath:application-secret.yml")
public YamlPropertiesFactoryBean yamlPropertiesFactoryBean() {
  YamlPropertiesFactoryBean bean = new YamlPropertiesFactoryBean();
  bean.setResources(new ClassPathResource("application-secret.yml"));
  return bean;
}

@Bean
@ConditionalOnBean(YamlPropertiesFactoryBean.class)
public PropertySourcesPlaceholderConfigurer propertySourcesPlaceholderConfigurer(final YamlPropertiesFactoryBean yamlPropertiesFactoryBean) {
  PropertySourcesPlaceholderConfigurer configurer = new PropertySourcesPlaceholderConfigurer();
  Properties secretProperties = yamlPropertiesFactoryBean.getObject();
  if (secretProperties != null) {
    log.info("apply application-secret.yml");
    configurer.setProperties(secretProperties);
  }
  return configurer;
}

classpath의 yaml 파일을 읽어서 PropertySourcesPlaceholderConfigurer에 적용하는 코드이다.
configurer를 Bean으로 등록하면, BeanFactoryPostProcessor에서 설정파일 로드 및 주입작업을 진행한다.

BeanFactoryPostProcessor?
bean 생성 완료 전 개입가능한 processor
BeanPostProcessor보다 먼저 수행되며 특정 bean 생성 시점에 트리거링 됨
일반적으로 Dynamic 하게 bean을 생성 또는 변경하기 위해 사용됨

문제점 발생

@Value 등 Bean 생성 시점이 Processor보다 이후 life-cycle을 가진 부분에서는 문제가 없었으나
PropertySource load 순서가 보장될 수 없는 상황이 발생

문제 상황:
- Actuator 설정을 전체 Multi-project에서 공유하기 위해 적용했지만, Actuator 라이브러리에서 management application properties를 주입받는 시점이 PropertySourcesPlaceholderConfigurer 보다 이전에 동작함.
따라서 PropertySourcesPlaceholderConfigurer로 actuator Property 주입이 불가

EnvironmentPostProcessor

package org.springframework.boot.env;

@FunctionalInterface
public interface EnvironmentPostProcessor {
  void postProcessEnvironment(ConfigurableEnvironment environment, SpringApplication application);
}

Spring env를 구성할 수 있는 Processor이다.
주요 메서드인 postProcessEnvironment()의 invoke 시점은 ApplicationContext가 재생성(refresh)하는 시점이다.
따라서 spring run부터 ~ context 구성 전에 어딘가에서 실행되기 때문에, lib의 properties 사용시점 전에 주입이 보장될 수 있다.

구현

PropertiesApplier

interface PropertiesApplier extends EnvironmentPostProcessor {
  @Override
  default void postProcessEnvironment(ConfigurableEnvironment environment, SpringApplication application){
    try {
      environment
          .getPropertySources()
          .addFirst(this.getTargetProperties());
    } catch (IOException e) {
      // no logger loaded yet...
      e.printStackTrace(System.out);
    }
  }

  PropertySource<?> getTargetProperties() throws IOException;

  default PropertySource<?> getTargetProperties(final String fileName) throws IOException {
    List<PropertySource<?>> secretPropertySources = new YamlPropertySourceLoader()
        .load("classpath:" + fileName, new ClassPathResource(fileName));
    if (secretPropertySources == null || secretPropertySources.isEmpty()) {
      throw new IOException("fail to find " + fileName);
    }
    System.out.println(((OriginTrackedMapPropertySource) secretPropertySources.get(0)).getSource());
    return secretPropertySources.get(0);
  }
}

EnviromentPostProcessor를 상속받는 interface로 공통 함수를 구현했다.
전체 flow는
1. load property
2. add property
이며, 공통 함수로 classpath에서 file 가져오는 메서드가 있다.

Implements

// load secret properties from classpath
public class SecretPropertiesApplier implements PropertiesApplier {
  @Override
  public PropertySource<?> getTargetProperties() throws IOException {
    return this.getTargetProperties("application-secret.yml");
  }
}

// load actuator properties from classpath
public class ActuatorPropertiesApplier implements PropertiesApplier {
  @Override
  public PropertySource<?> getTargetProperties() throws IOException {
    return this.getTargetProperties("application-actuator.yml");
  }
}

application-secret.yml 및 application-actuator.yml을 classpath에서 읽어서 적용되도록 구현

resources/META-INF/spring.factories

org.springframework.boot.env.EnvironmentPostProcessor=\
com.pbear.lib.properties.ActuatorPropertiesApplier,\
com.pbear.lib.properties.SecretPropertiesApplier

EnviromentPostProcessor를 적용하기 위해서는 spring.factories에 명시를 해줘야 한다.
implements 한 두 class의 full path를 명시하여 적용.

Conclusion + Next..

Spring Property 주입은 매우 다양한 방법을 제공하고 있다.
덕분에 큰 작업 없이, 원하는 시점에 property 주입이 가능했다.
Spring에서는 기본적으로 EnviromentPostProcessor를 통한 property 주입을 추천하고 있다.

현재로 기본 LIB 구성은 완료되었다.
이후 공통부분이 나올 때마다 LIB를 업데이트하려고 한다.

다음 작업 예정은 starter library들이다.
작업 예정으로는
1. pbear-starter-webflux: webclient를 설정 및 build 하여 bean으로 등록, webflux관련 기본 로직 관련 starter
2. pbear-starter-r2dbc: r2dbc connection factory를 build하여 bean 등록 starter
3. pbear-starter-kafka: kafka Topic에 대한 정보를 제공해 주는 starter
4. pbear-starter-redis: Redis connection factory 및 기타 template 설정 starter
5. pbear-starter-mongodb: ...
6. pbear-starter-websocket: ...
7. ...
등 있다...
재사용성이 높은 모듈로 만드는 것이 목표
-> starter library만 implement 하면, 기본적인 접속정보 주입 등은 완료되도록.. + custom config에 열려있는 구조

xx. annotation 기반의 openfeign도 고려 중

기본 starter 구성 후 기본적인 구성인
account 관리 서버, gateway, access-control server (OAuth) 등 작업하고자 한다.
해당 서버들이 24년 첫 프로젝트가 될 예정

REFERENCE

https://docs.spring.io/spring-framework/docs/current/javadoc-api/org/springframework/context/support/PropertySourcesPlaceholderConfigurer.html

https://www.baeldung.com/spring-boot-environmentpostprocessor

AnnotationProcessor를 통한 project 내 ServerInfo Enum 생성

북극곰은콜라 — Mon, 25 Dec 2023 01:13:53 +0900

개요

중복되는 코드를 줄이기 위해 개인 서버 프로젝트를 gradle을 활용한 subproject 구조로 잡았었다.
새로 생성되는 subproject에서 중복 로직들을 모은 LIB project를 implementation 하여, 중복을 줄이고자 시도 중이다.
문제는, 프로젝트가 추가될 때마다 LIB project의 코드를 추가해 주는 방식은, 목표했던 편의성과는 거리가 있다.
이에 프로젝트 전체를 지속적으로 모니터링하여, 자동으로 최신화하는 방법을 모색했다.
목표는 수동으로 코드의 추가 없이, 신규 프로젝트의 설정 및 properties 등을 스크랩하여 추가할 수 있는 방안을 마련하는 것이다.

AnnotationProcessor란

JAVA 5에서 신규 도입된 개념으로
Compile 시점에 JAVA의 소스를 AST(Abstract Syntax tree) 구조로 참조할 수 있으며, 수정 및 생성이 가능하게 해주는 기능이다.
AnnotationProcessor라는 이름처럼, annotation 기반으로 element를 참조한다.

대표적으로 AnnotationProcessor를 활용한 library로 lombok, queryDSL 등이 있다.

Abstract Syntax Tree란

AST란 소스코드를 트리구조로 추상화한 것이다.
컴파일러에서 자주 사용되는 자료구조이며, 소스코드를 분석하는 데 사용된다.
javac의 컴파일 단계에서 쓰이는 것은 물론이며, javascript의 lint, formatter등에서도 활용된다.
더 깊게 들어가면 CFG(context-free-grammar), DOM(Document Object Model) 등 여러 개념들이 함께 사용된다. 더 자세한 사항은 다른 포스팅에서 다루도록 하겠다.
이번 포스팅에서 AST는 소스코드를 분석하여 트리구조화 시키는 자료구조 정도로 이해하고 넘어가겠다.

javax.annotation.processing.Processor

AnnotationProcessor에서 제공하는 대표적인 interface 및 abstract class이다.
일반적으로 AbstractProcessor를 구현한다.

필수 구현 method로 process(Set <TypeElement>, RoundEnvironment)가 있다.
compile 시점에 process method가 invoke 된다고 생각해도 무방하다.

RoundEnvironment

annotated element를 받을 수 있는 evvironment이다.
Annotation을 element를 찾아서, code generate 등 작업을 진행할 수 있도록 도와준다.

ProcessingEnvironment

processing을 위한 환경을 제공하는 인터페이스
AbstractProcessor에서 기본적으로 구성해서 제공해 준다.
이번에는 getFiler를 통해 filer를 불러와서 generated에 java 파일을 생성하려 한다.

TypeElement (Element)

Element는 소스코드상의 type, parameter 등 여러 정보를 AST로 분석하여 제공해 준다.
이번 요구사항에서는 크게 활용되지 않기 때문에 생략하겠다.
Java Interface로 추상화해서 제공하기 때문에, 사용법은 비교적 간단하다. (코드 분석 및 제공은 Javac에서 해준다...)

Google AutoService

This is an annotation processor library that helps us with generating Java Service Provider Interface (SPI) configuration files.
...
Google AutoService is an open source code generator tool, developed under the Google Auto project. There are also two other tools besides AutoService: AutoValue and AutoFactory.
The purpose of this library is to save effort and time and, at the same time, to prevent misconfiguration.

간단하게 구글에서 제공하는 AnnotationProcessor 라이브러리로, Java SPI 설정파일, manifest 등 메타파일을 자동으로 생성해 주는 역할을 한다.
해당 라이브러리로 AnnotationProcessor를 구성하기 위한 작업을 간소화하고 안정성을 확보할 수 있다.
물론 주의사항으로, 의존성이 복잡한 구조로 엮이는 경우 의도하지 못한 상황이 발생할 수 있다. 대표적으로 local, release, test 환경의 의존성 구조가 크게 달라지는 경우, 의존성의 순서와 관련하여 특정 processor가 load 하지 못하거나 실패하게 될 수 도 있다.

AnnotationProcessor기반 serverInfo 수집 processor 구현

목표

1. compile 시점에 동작
2. Project의 root로부터 하위 모든 file을 full scan
3. 모든 yml file search 및 파싱
4. spring.application.name 및 server.port 속성들을 찾아서 객체화
5. name port 등을 속성으로 가지는 enum java파일 생성
6. 다른 subproject에서 generate 된 enum 파일을 사용하여, 프로젝트 내 모든 serverInfo를 get 할 수 있음

Gradle 구조

Root project 'pbear-root'
\--- Project ':pbear-spring'
     +--- Project ':pbear-spring:pbear-devtool'
     +--- Project ':pbear-spring:pbear-lib'
     \--- Project ':pbear-spring:pbear-sample'

build.gradle (Root Project)

...

dependencies {
	...

    if (project.name != 'pbear-devtool') {
        compileOnly project(':pbear-spring:pbear-devtool')
        annotationProcessor project(':pbear-spring:pbear-devtool')

        if (project.name != 'pbear-lib') {
            implementation project(':pbear-spring:pbear-lib')
        }
    }
}

...

AnnotationProcessor가 동작하는 project인 pbear-devtool 생성
devtool은 annotationProcessor를 구현할 library가 될 것이며 추후 다른 기능을 추가하기 위해 모든 프로젝트에서 의존성을 갖게 한다.
또한 pbear-lib도 모든 project에서 의존성을 가지게 되는 library성 프로젝트이다.

build.gradle (devtool)

version = '0.0.1'

bootJar { enabled = false }

dependencies {
    implementation 'org.yaml:snakeyaml:2.2'
    implementation 'com.google.auto.service:auto-service:1.1.1'
    annotationProcessor 'com.google.auto.service:auto-service:1.1.1'
}

dependencies로
1. yml 파싱을 위한 snakeyaml
2. annotationProcessor meta 생성을 위한 Google의 auto-service
Main Class가 없기 때문에, spring boot plugins의 bootjar는 disable

build.gradle (lib)

...

tasks.named('compileJava') {
    it.dependsOn('clean')
}

지속적으로 serverInfo가 최신화되기 위한 compileJava의 clean 의존성 설정

Processor 구현

Custom Annotation Class

public @interface EnablePBearServerInfoDevtool {
}

적용되는 프로젝트를 특정하기 위한 annotation class

Processor

@SupportedAnnotationTypes("com.pbear.devtool.annotation.EnablePBearServerInfoDevtool")
@SupportedSourceVersion(SourceVersion.RELEASE_17)
@AutoService(Processor.class)
@SuppressWarnings({"unused"})
public class ServerProperitesProcessor extends AbstractProcessor {
  private static final String SERVER_ENUM_PACKAGE_NAME = "com.pbear.devtool";
  private static final String SERVER_ENUM_CLASS_NAME = "Server";

  @Override
  public boolean process(Set<? extends TypeElement> annotations, RoundEnvironment roundEnv) {
    roundEnv.getElementsAnnotatedWith(EnablePBearServerInfoDevtool.class)
        .stream()
        .filter(element -> element.getKind() == ElementKind.CLASS)
        .findFirst()
        .ifPresent(element -> this.createServerResource((TypeElement) element));

    return true;
  }

  ...
}

기본 구성

@SupportedAnnotationTypes("com.pbear.devtool.annotation.EnablePBearServerInfoDevtool")
@SupportedSourceVersion(SourceVersion.RELEASE_17)
로 target annotation 및 java version 지정

Google AutoService 선언

AbstractProcessor extends

EnablePBearServerInfoDevtool 어노테이션이 하나라도 있으면 실행이 되며 비즈니스로직이 실행된다.

createServerResource()

private void createServerResource(TypeElement typeElement) {
    try {
      System.out.println(typeElement.getQualifiedName());
      File currentDir = new File(System.getProperty("user.dir"));
      File rootDir = this.getRootProjectDirectory(currentDir);
      System.out.println("root dir:" + rootDir.getCanonicalPath());
      List<File> ymlFileList = this.matchChildFileExtension(rootDir);
      List<ServerInfo> serverInfoList = this.getSpringServerInfoList(ymlFileList);
      System.out.println(serverInfoList);
      this.writeServerInfoEnum(serverInfoList);

    } catch (IOException e) {
      throw new RuntimeException(e);
    }
}

1. 실행되는 현 directory를 기준으로 root를 찾는다.
2. root를 기준으로 하위 디렉터리를 순회하며 yml을 찾는다. (nio files 활용)
3. spring.application.name 및 server.port를 찾아서 ServerInfo 생성
4. enum file 작성

private void writeServerInfoEnum(final List<ServerInfo> serverInfoList) throws IOException {
    FileObject fileObject = processingEnv
        .getFiler()
        .createSourceFile(SERVER_ENUM_PACKAGE_NAME + "." + SERVER_ENUM_CLASS_NAME);
    try (PrintWriter out = new PrintWriter(fileObject.openWriter())) {
      String tab = "  ";

      // package com.pbear.devtool;
      out.print("package ");
      out.print(SERVER_ENUM_PACKAGE_NAME);
      out.println(";");
      out.println();

      // public enum Server {
      out.print("public enum ");
      out.print(SERVER_ENUM_CLASS_NAME);
      out.println(" {");

      ...
    }
}

AbstartProcessor에서 제공하는 processingEnv를 통해 generated에 sourceFile을 작성했다.
작성은 PrintWriter를 통해 손수 작성...

devtool 사용

package com.pbear.lib;

import com.pbear.devtool.annotation.EnablePBearServerInfoDevtool;

@EnablePBearServerInfoDevtool
public class ServerInfoDevtool {
}

간단하게 Annotation을 달아서 사용

compile 후 build/generated/annotationProcessor/java 밑으로 java 파일이 생성된 것을 확인할 수 있다.

처음 그린 그림은 zookeeper를 통한 service registry를 사용하는 구성이었다.
Service Registry를 통해 msa구조를 잡으면 cloud 환경에서는 적은 수고로 서버 간 연동 및 오토스케일링을 대응할 수 있다.
하지만 로컬 서버 하나 운영하는 상황에서 이는 상당히 불필요한 작업이다.
1. 개발환경에서 zookeeper에 대한 대응을 해야 한다.
2. 동적으로 서버를 discovery 할 수 있는 장점이, 1 서버 구성에서는 무의미하다.
3. zookeeper를 관리해야 한다.

이에, 이런 부분을 대체하기 위해 AnnotationProcessor를 구현해서 Server 정보를 빌드 시점에 모아서 쓸 수 있도록 시도 중이다.
하지만, 이러면 앞단의 gateway는 서버가 추가될 때마다 다시 빌드해서 배포해야 하는 상황이 발생할 것이다.
이에 대한 해결책은 아직 고민 중이다.

일단 다음은 일단 github에 올라가면 안 되는 secret properties를 배포 시점에 로드하는 구성을 lib에 구현하고자 한다.

REFERENCE

https://taes-k.github.io/2021/04/18/java-annotation-processing/
https://github.com/taes-k/sample-annotation-processing
https://www.baeldung.com/java-annotation-processing-builder

Gradle Docker build (feat. Jenkins CI/CD)

북극곰은콜라 — Fri, 22 Dec 2023 08:01:24 +0900

개요

Jenkins에 CI / CD를 구성하는 작업은
신규 프로젝트 생성시마다 해줘야하는 귀찮은 작업 중 하나다.
또한 개발 / 배포 환경 상 자주 바뀌는 부분도 없고, 대부분 비슷하게 동작한다.
이러한 공통부분을 묶어서, 하나의 CI / CD로 모든 project (gradle subproject)를 빌드 배포할 수 있도록 구성하려 한다.

Gradle docker build

'com.bmuschko.docker-spring-boot-application'는 docker build를 지원하는 gradle plugin이다.
이를 활용하여, gradle의 task를 통해 docker image 생성까지 구성하고자 한다.

docker image 생성을 gradle에서 하는 이유?
기본적으로 docker image 생성 시 project의 name 및 version이 필요하다.
project name은 jenkins에서 argument로 받는다고 해도, gradle의 project.version을 jenkins에서 가져오기에는 복잡하고 효율적이지 않다고 판단했다.
따라서 gradle에서 docker image build까지 담당하는 것이 깔끔할 것이라 판단했다.

gradle-docker-plugin (bmuschko)

docker-spring-boot-application plugin은 4가지 task를 지원한다. (상세 스펙은 reference 참조)
dockerCreateDockerfile
- dockerfile을 작성할 수 있도록 도와주는 task이다.
- springBootApplication Object로 baseImage, jvmArgs등을 설정할 수 있도록 도와준다.
dockerBuildImage
- docker Image를 build하는 task이다.
- dependsOn(dockerCreateDockerfile)이며 앞 task에서 생성되는 Dockerfile을 기반으로 docker image를 build한다.

docker {
    springBootApplication {
        baseImage = 'openjdk:8-alpine'
        ports = [9090, 8080]
        images = ['awesome-spring-boot:1.115', 'awesome-spring-boot:latest']
        jvmArgs = ['-Dspring.profiles.active=production', '-Xmx2048m']
    }
}

Guild에 나오는 간단 세팅이다.
기본적으로 SpringBootApplication annotation을 찾아서 main으로 세팅하고
부가적인 정보를 springBootApplication Object로 받아서 추가한다.

Read yml in gradle docker task

[root] gradle.build

import org.yaml.snakeyaml.Yaml

buildscript {
    repositories {
        mavenCentral()
    }
    dependencies {
        classpath('org.yaml:snakeyaml:2.0')
    }
}

plugins {
    id 'com.bmuschko.docker-spring-boot-application' version '9.4.0'
}

...

subprojects {
    ...

    docker {
        dockerCreateDockerfile.doFirst {
            def appConfig = new Yaml().load( project.file('src/main/resources/application.yml').newInputStream() )
            springBootApplication {
                baseImage = 'openjdk:17'
                ports = [appConfig.server.port, appConfig.server.port]
                images = ["${project.name}:${project.version}", "${project.name}:latest"]
                jvmArgs = ['-Dspring.profiles.active=release', '-Duser.timezone=Asia/Seoul']
            }
        }
        dockerBuildImage.dependsOn('build')
    }
}

plugin user guide의 sample code를 그대로 사용하기에는 문제가 있다.
현 project 계획은 root 밑으로 subprojects들이 있고 jenkins에서 ci / cd의 task에 subproject를 지정하여 빌드 및 배포를 하려한다.
따라서 예시처럼, 각 build.gradle마다 port 등 을 지정하는 방식은 쓸 수 없다.

task 실행 시점에 해당 프로젝트의 설정을 읽어오는 방식으로 적용하고자 한다.
spring의 application.yml을 읽어서 server.port 값을 세팅하도록 설정했다.
snakeyaml library로 yml을 파싱하여 값을 추출했다.

Jenkins CI / CD 구성

CI

build parameter

빌드할 project를 선택할 수 있도록 parameter 구성
프로젝트가 추가될 때 마다. Choices를 추가해주어야 한다...

Build Steps

gradle 레퍼로 실행
build parameter로 dockerBuildImage task execute
이는 clean -> ... -> build -> dockerCreateDockerfile -> dockerBuildImage 순으로 진행된다.

CD

build parameter

CD 역시 build할 project와 버전을 parameter로 받는다.

Build Steps

Jenkins의 Docker Build Plugin으로 로컬 이미지를 컨테이너 run하는 방식
복잡한 구성은 최대한 root의 gradle.build로 빼는 방향으로 develop할 예정

Next..

2024에는 각 project들의 호흡을 짧게 가져가려고 한다.
인프라는 기존에 있던, RDB, Kafka, Redis, MongoDB 등을 활용한다.
다음 작업 사항은 각 인프라에 접속하는 정보를 제공하는 provider를 lib에 구현하고자 한다.
이후 프로젝트는 lib를 implementation하여 provider를 통해 접속정보를 포함한 config를 얻을 수 있을 것이다.
이는 신규 프로젝트를 손쉽게 시작할 수 있게 할것이라 기대한다.

REFERENCE

https://github.com/bmuschko/gradle-docker-plugin

https://plugins.gradle.org/plugin/com.bmuschko.docker-spring-boot-application

https://bmuschko.github.io/gradle-docker-plugin/current/user-guide/

https://bmuschko.github.io/gradle-docker-plugin/current/user-guide/#spring-boot-plugin-extension

Multi-project 구조 설계 (Gradle)

북극곰은콜라 — Thu, 21 Dec 2023 08:16:21 +0900

개요

지난 시즌 개발 중 신규 프로젝트 시작할 때 큰 귀찮음이 있었다.
1. 프로젝트마다 중복되는 코드: log 설정, db설정, kafka 설정, 등등..
2. 프로젝트마다 중복되는 작업: github, jenkins CI/CD, docker config 등등..

이런 귀찮음은 결국 신규 프로젝트를 시작할 때 부담으로 작용하게 되었고
간단한 아이디어를 테스트 하기에 좋지 못했다.
이번 시즌에는 이러한 부분을 사전에 방지하고자 한다.

이 글은 Gradle의 Multi-Project 구조를 통해
이러한 문제상황을 해결해보려 한다.

Multi-Project 구조 설계

Gradle은 Multi-Project 구조를 지원한다.
이번 프로젝트는 2-depth 이상으로 구성하려 한다.

Root project 'pbear-root'
\--- Project ':pbear-spring'
     +--- Project ':pbear-spring:pbear-lib'
     \--- Project ':pbear-spring:pbear-sample'

Project 구조이다.
전체적으로 java 프로젝트를 대상으로 하며
일단 Spring Project를 1-depth로 잡았다.
2-depth부터 개발이 진행될 프로젝트들이 나열되는데
기본적으로 lib를 두고, spring-project에서 사용될 공통 코드 및 설정을 implementation 해서 사용하고자 한다.

[root] setting.gradle

rootProject.name = 'pbear-root'

include 'pbear-spring'
include 'pbear-spring:pbear-lib'
include 'pbear-spring:pbear-sample'

특이사항은 없으며
하위 프로젝트의 build.gradle을 include 시켰다.

[root] build.gradle

group = 'com.pbear'

subprojects {
    apply plugin: 'java'
    apply plugin: 'java-library'

    sourceCompatibility = 17
    targetCompatibility = 17

    dependencies {
        compileOnly 'org.projectlombok:lombok:1.18.28'
        annotationProcessor 'org.projectlombok:lombok:1.18.28'
    }

    repositories {
        mavenCentral()
    }
}

subprojects를 통해 하위 프로젝트에 적용될 plugin, dependencies 및 repositories를 설정했다.

[pbear-spring] build.gradle

plugins {
    id 'org.springframework.boot' version '3.2.0' apply false
    id 'io.spring.dependency-management' version '1.1.4' apply false
}

ext {
    set('springCloudVersion', "2023.0.0")
}

subprojects {
    apply plugin: 'org.springframework.boot'
    apply plugin: 'io.spring.dependency-management'

    dependencyManagement {
        imports {
            mavenBom "org.springframework.cloud:spring-cloud-dependencies:${springCloudVersion}"
        }
    }

    test {
        useJUnitPlatform()
    }
}

1-depth의 spring을 주제로 묶은 프로젝트이다.
여기서 spring의 dependencies를 통합해서 관리하고자 한다.
기본적으로 spring의 dependency-management 플러그인을 사용하고, spring boot 및 spring cloud version을 관리할 수 있도록 세팅했다.

[pbear-lib] build.gradle

version = '0.0.1'

dependencies {
    implementation 'org.springframework.boot:spring-boot-autoconfigure'
}

2-depth의 Library에 해당하는 프로젝트이다.
추후 추가될 예정이며, 여기부터는 project version 관리를 한다.

[pbear-sample] build.gradle

version = '0.0.0'

dependencies {
    implementation project(':pbear-spring:pbear-lib')

    implementation 'org.springframework.boot:spring-boot-starter-webflux'
}

REST echo기능을 하나 넣은 sample project이다.
추후 추가되는 프로젝트는 위처럼 pbear-lib를 implementation을 해서 사용한다.

위 프로젝트 구조를 통해
프로젝트 추가 시 낭비되는 작업들을 최소화시킬 수 있을 것이라 판단된다.
ex) github project 추가, spring dependency 작업, 중복 기능 구현, 설정 등

Common logback 설정

[pbear-lib] logback.xml

Root project 'pbear-root'
\--- Project ':pbear-spring'
     +--- Project ':pbear-spring:pbear-lib'
          \--- src/main/resources/logback.xml
     \--- Project ':pbear-spring:pbear-sample'

<?xml version="1.0" encoding="UTF-8"?>
<configuration>
    <springProperty name="APP_NAME" source="spring.application.name"/>

    <springProfile name="local">
        <property name="FILE_PATH" value="/users/xxxxx/workspace/logs"/>
        <property name="FILE_NAME" value="${APP_NAME}"/>
    </springProfile>

    <springProfile name="release">
        <property name="FILE_PATH" value="/logs"/>
        <property name="FILE_NAME" value="${APP_NAME}"/>
    </springProfile>

    <appender name="STDOUT" class="ch.qos.logback.core.ConsoleAppender">
        <encoder>
            <pattern>%d{yyyyMMdd HH:mm:ss} [%thread] %-5level%logger{5} - %msg %n</pattern>
        </encoder>
    </appender>

    <appender name="RollingFileAppender" class="ch.qos.logback.core.rolling.RollingFileAppender">
        <file>${FILE_PATH}/${FILE_NAME}.log</file>

        <encoder>
            <pattern>%d{yyyyMMdd HH:mm:ss} [%thread] %-5level%logger{5} - %msg %n</pattern>
        </encoder>

        <rollingPolicy class="ch.qos.logback.core.rolling.TimeBasedRollingPolicy">
            <fileNamePattern>${FILE_PATH}/${FILE_NAME}.log.%d{yyyy-MM-dd}_%i.gz</fileNamePattern>
            <timeBasedFileNamingAndTriggeringPolicy class="ch.qos.logback.core.rolling.SizeAndTimeBasedFNATP">
                <maxFileSize>1GB</maxFileSize>
            </timeBasedFileNamingAndTriggeringPolicy>
            <maxHistory>30</maxHistory>
        </rollingPolicy>
    </appender>

    <springProfile name="local">
        <root level="INFO">
            <appender-ref ref="STDOUT" />
        </root>
    </springProfile>

    <springProfile name="release">
        <root level="INFO">
            <appender-ref ref="RollingFileAppender" />
        </root>
    </springProfile>
</configuration>

공통 library에 자주 사용하는 logback을 넣고 다른 project에서 implementation 하면
실제 기동 시 해당 logback이 적용된다.
변수는 모두 spring properties로 받아온다.

이로서 신규 프로젝트는 로깅에 대한 설정을 스킵할 수 있다.
또한 log관련 변동사항이 다 같이 적용되고, log의 형식도 통일할 수 있다.

Next..

신규 프로젝트마다. CI / CD설정하고, docker 설정 만드는 것도 많이 귀찮은 작업이었다.
프로젝트 구조를 잡았으니
다음은 Jenkins를 통해 CI / CD를 공통화할 계획이다.

REFERENCE

https://docs.gradle.org/current/userguide/multi_project_builds.html

Jenkins Docker Builder 연동 이슈 (connection refused)

북극곰은콜라 — Wed, 20 Dec 2023 10:31:09 +0900

개요

Jenkins는 CI / CD를 구성할 수 있는 강력한 툴이다.
Docker는 환경을 포함해서 Application을 이미지화 할 수 있는 툴이며
Jenkins를 통해 docker로 배포하는 방법은 많이 활용되는 조합이다.

문제 발생

기존 배포 방식

일반적인 배포방식으로는
1. Jenkins에서 build 및 docker image 생성
2. docker image를 DockerHub로 업로드
3. 배포 받을 서버에 dockerHub에서 특정 이미지를 받아서 실행하도록 command
이 있다.

배포 방식 단순화

2023 개인서버에는 위 로직을 통해 배포를 진행했었다.
넥스트 계획의 핵심은, 중복되는 작업들을 최대한 자동화 시키고 요구사항에서 벗어나는 확장성을 줄이고자한다.
이에, 서버 한곳에서 빌드 및 배포가 진행될 것이기에 로직을 단순화 시켰다.
1. Jenkins에서 build 및 docker image 생성
2. 서버에 Docker Command를 통해 컨테이너 생성 및 run

Jenkins Docker Plugin 적용

단순화된 배포방식으로, 기존 복잡한 Jenkins File대신
Jenkins Plugin을 최대한 활용하기로 결정

Connection Refuse 발생

Something went wrong, cannot connect to unix:///var/run/docker.sock, cause: org.apache.hc.client5.http.HttpHostConnectException: Connect to unix://localhost:2375 [localhost/127.0.0.1] failed: Connection refused

포럼에서 Jenkins는 Docker Builder 설정을 수동으로 해야한다고 가이드하여
해당 설정을 하면, docker에서 connection refuse가 떨어진다.

netstat -tnlp | grep 2375

/etc/docker# docker --version
Docker version 23.0.4, build f480fb1

확인해보니 2375로 LISTEN중인 어플리케이션이 없었다.
docker는 apt-get으로 설치한후 mount point 변경 등 작업을 한 상황이다.

/etc/docker/damon.json

{
  "log-driver": "json-file",
  "log-opts": {
    "max-size": "10m",
    "max-file": "3"
  },
  "hosts": ["unix:///var/run/docker.sock", "tcp://0.0.0.0:2375"]
}

docker에서 REST API가 열리지 않은 것으로 판단되여
docker reference를 통해 설정을 진행했다.
"hosts": ["unix:///var/run/docker.sock", "tcp://0.0.0.0:2375"]를 json 설정파일에 추가했다.

Service Run Fail 발생

systemctl restart docker
Job for docker.service failed because the control process exited with error code.
See "systemctl status docker.service" and "journalctl -xeu docker.service" for details.

docker service가 실패했으며
journal을 확인해 보니

journalctl -xeu docker.service
...

.... dockerd[2153802]: unable to configure the Docker daemon with file /etc/docker/daemon.json: the following directives are specified both as a flag and in the configuration file: hosts: (from fla>
.... systemd[1]: docker.service: Main process exited, code=exited, status=1/FAILURE

...

specified both as a flag and in the configuration file: hosts
해당 문구로 볼때, docker.service 파일에서 hosts관련 옵션이 있는것으로 추정

/lib/systemd/system/docker.service

...
[Service]
Type=notify
# the default is not to use systemd for cgroups because the delegate issues still
# exists and systemd currently does not support the cgroup feature set required
# for containers run by docker
ExecStart=/usr/bin/dockerd -H fd:// --containerd=/run/containerd/containerd.sock
ExecReload=/bin/kill -s HUP $MAINPID
TimeoutStartSec=0
RestartSec=2
Restart=always
...

역시 dockerd execute할 때 -H 옵션이 있었다.

systemctl daemon-reload
systemctl start docker

// docker service status 확인
root@m-H110M4-C2D:/etc/docker# systemctl status docker
● docker.service - Docker Application Container Engine
     Loaded: loaded (/lib/systemd/system/docker.service; enabled; vendor preset: enabled)
     Active: active (running) since Wed 2023-12-20 10:27:46 KST; 1min 3s ago
TriggeredBy: ● docker.socket
       Docs: https://docs.docker.com
   Main PID: 2153904 (dockerd)
      Tasks: 139
     Memory: 58.6M
        CPU: 4.071s
     CGroup: /system.slice/docker.service
             ├─2153904 /usr/bin/dockerd --containerd=/run/containerd/containerd.sock
             ├─2154352 /usr/bin/docker-proxy -proto tcp -host-ip 0.0.0.0 -host-port 9021 -container-ip 172.29.0.3 -container-port 9021
             ├─2154360 /usr/bin/docker-proxy -proto tcp -host-ip :: -host-port 9021 -container-ip 172.29.0.3 -container-port 9021
             ...

// LISTEN port 확인
netstat -tnlp | grep 2375
tcp6       0      0 :::2375                 :::*                    LISTEN      2153904/dockerd

Jenkins 연동도 정상적으로 작동 확인

REFERENCE

https://docs.docker.com/engine/reference/commandline/dockerd/#daemon-configuration-file

Micrometer Log Tracing (feat. Spring Boot 3)

북극곰은콜라 — Thu, 14 Dec 2023 16:08:00 +0900

Micrometer란

Vendor-neutral application observability facade

micrometer는 observability의 파사드(고수준 인터페이스)를 제공해주는 프로젝트이다.
observability는 Application의 가시성을 제공해주는 것을 말하며, 이는 Application 내에서 발생하는 process를 외부로 제공해주는 것 이다.
JVM -based Application라면 ventdor에 상관없이 적용할 수 있다.

Project Develop History

2016 [Spring] Create tracing library(Spring Cloud Sleuth) from Spring Cloud team
2017 [Micrometer] Micrometer Project 시작 (only for jvm based application observation)
2018 [Micrometer] 1.0.0 RELEASE
2022.1 [Micrometer-tracing] 1.0.0-M1 RELEASE
2022.11 [Micrometer] 1.10.0 (GA version) RELESE
2022.11 [Micrometer-tracing] 1.0.0 RELEASE → Spring Cloud Sleuth를 흡수
…

Spring 공식 Document에서 Spring Cloud Sleuth는 Micrometer-Tracing Project로 이사 간 사항을 고시하고 있다.
Spring-Cloud 2022 버전부터 Sleuth 적용 시 Initilization Error와 함께 위 공지가 나온다.

Features

1.   Easy to Integration with Spring Project
2.   Easy to pass Metrics to Monitoring tool
3.   Provide Tracing Library
4.   Provide Context Propagation Library

Instrumentation

1.   Provide Spring Metrics
2.   Provide JVM Metrics
3.   Provide Cache Metrics
4.   Provide Instrumentation for Netty
5.   Provide OkHttpClient Metrics
6.   Provide Instrumentation for Jetty, Jersey

Support Monitoring Tools

// Log Tracing 란

MSA 구조에서 End to End를 사이에 일어난 사항을 확인하기 위한 Tracing 기법
log를 기반으로, traceId, spanId (+parentSpanId)를 활용하여 전체적인 flow를 파악한다.
slow process, error point를 잡아내기에 용이 함

Tracing 적용 가이드

Spring boot 3 기반 프로젝트에서 REST, RSocket, Kafka(reactor)에 Tracing 및 Propagation, Zipkin 연동 가이드

Test Version Specification

구분	항목	Version
Java	Java	17
Spring	org.springframework.boot	3.1.5
Spring	io.spring.dependency-management	1.1.2
Spring	org.springframework.cloud:spring-cloud-dependencies	2022.0.3
Reactor	io.projectreactor.kafka:reactor-kafka	1.3.22
Brave	io.zipkin.brave:brave-bom	5.15.1
RSocket	io.rsocket:rsocket-micrometer	1.1.4
Docker	openzipkin/zipkin	3.0.0-rc0 (latest)

ZipKin Setup

docker run -d -p 9411:9411 openzipkin/zipkin

REST Tracing

REST Tracing의 경우 Conifg 만으로 적용이 가능하다.
Spring Actuator를 통해서 연동이 가능
WebClient는 반드시 Builder를 인자로 받아 Bean으로 선언해야한다.

Gradle

implementation 'org.springframework.boot:spring-boot-starter-actuator'
implementation 'io.micrometer:micrometer-tracing-bridge-brave'
// for report
implementation 'io.zipkin.reporter2:zipkin-reporter-brave'

application.yml

logging:
  pattern:
    level: "%5p [%X{traceId},%X{spanId}]"
management:
  tracing:
    sampling:
      probability: 1.0
    propagation:
      consume: b3
      produce: b3_multi
    enabled: true
  zipkin:
    tracing:
      endpoint: http://localhost:9411/api/v2/spans

Hooks

private static void hooks() {
  Hooks.enableAutomaticContextPropagation();
}

WebClient

@Bean
public WebClient webClient(WebClient.Builder builder) {
  return builder.build();
}

Test Log

// Application 1
2023-12-07 10:22:36 [reactor-http-nio-6] INFO [65711e5cd3177ba2125ebb529a63dbf4,125ebb529a63dbf4] c.e.tracing4spring3.rest.RestT - get /test start
...
2023-12-07 10:22:36 [reactor-http-nio-6] INFO [65711e5cd3177ba2125ebb529a63dbf4,125ebb529a63dbf4] c.e.tracing4spring3.rest.RestT - res: {result=success}

// Application 2
2023-12-07T10:22:17.100+09:00  INFO [65711e48970b05e498223b2f239e48ca,1c828e842276ba45] 12932 --- [ctor-http-nio-4] : test1 <<<, header: 
  [X-B3-TraceId:"65711e48970b05e498223b2f239e48ca", X-B3-SpanId:"f7fe2062438d0f0e", X-B3-ParentSpanId:"98223b2f239e48ca", X-B3-Sampled:"1", accept-encoding:"gzip", user-agent:"ReactorNetty/1.1.12", host:"127.0.0.1:9083", accept:"*/*"]
...

ZipKin

RSocket Tracing

RSocket Tracing의 경우 Integration을 위한 코드 작성이 필요하다.
1. RSocketResponderTracingObservationHandler, RSocketRequesterTracingObservationHandler 를 Bean으로 생성 2. Micrometer에서 제공하는 RSocketProxy 구현체를 RSocketConnector, RSocketServer의 Interceptor에 등록한다.
// Inteceptor 등록은 Customizer를 통해 적용
micormeter에서 Sample Code를 제공한다.

Gradle

implementation 'io.rsocket:rsocket-micrometer:1.1.4'

application.yml

상동

ObservationHandler Bean등록

@Bean
@Order(Ordered.HIGHEST_PRECEDENCE + 10)
RSocketResponderTracingObservationHandler rSocketResponderTracingObservationHandler(Tracer tracer, Propagator propagator) {
  return new RSocketResponderTracingObservationHandler(tracer, propagator, new ByteBufGetter(), true);
}

@Bean
@Order(Ordered.HIGHEST_PRECEDENCE + 10)
RSocketRequesterTracingObservationHandler rSocketRequesterTracingObservationHandler(Tracer tracer, Propagator propagator) {
  return new RSocketRequesterTracingObservationHandler(tracer, propagator, new ByteBufSetter(), true);
}

RSocketServer 설정

@Bean
ObservationRSocketServerCustomizer observationRSocketServerCustomizer(ObservationRegistry observationRegistry) {
  return new ObservationRSocketServerCustomizer(observationRegistry);
}


class ObservationRSocketServerCustomizer implements RSocketServerCustomizer {

  private final ObservationRegistry observationRegistry;

  ObservationRSocketServerCustomizer(ObservationRegistry observationRegistry) {
    this.observationRegistry = observationRegistry;
  }

  @Override
  public void customize(RSocketServer rSocketServer) {
    rSocketServer.interceptors(ir -> ir.forResponder(
            (RSocketInterceptor) rSocket -> new ObservationResponderRSocketProxy(rSocket, this.observationRegistry))
        .forRequester((RSocketInterceptor) rSocket -> new ObservationRequesterRSocketProxy(rSocket,
            this.observationRegistry)));
  }
}

RSocketReuqester (Connector) 설정

@Bean
ObservationRSocketConnectorConfigurer observationRSocketConnectorConfigurer(
    ObservationRegistry observationRegistry) {
  return new ObservationRSocketConnectorConfigurer(observationRegistry);
}

class ObservationRSocketConnectorConfigurer implements RSocketConnectorConfigurer {

  private final ObservationRegistry observationRegistry;

  ObservationRSocketConnectorConfigurer(ObservationRegistry observationRegistry) {
    this.observationRegistry = observationRegistry;
  }

  @Override
  public void configure(RSocketConnector rSocketConnector) {
    rSocketConnector.interceptors(ir -> ir.forResponder(
            (RSocketInterceptor) rSocket -> new ObservationResponderRSocketProxy(rSocket, this.observationRegistry))
        .forRequester((RSocketInterceptor) rSocket -> new ObservationRequesterRSocketProxy(rSocket,
            this.observationRegistry)));
  }
}

Test Log

// Application 1
2023-12-07 11:27:49 [reactor-http-nio-6] INFO [65712da58aa02571bfd0fef42b4056f9,bfd0fef42b4056f9] c.e.t.rsocket.RSocketService - rsocket request start
...
Frame => Stream ID: 1 Type: REQUEST_RESPONSE Flags: 0b100000000 Length: 175
Metadata:
         +-------------------------------------------------+
         |  0  1  2  3  4  5  6  7  8  9  a  b  c  d  e  f |
+--------+-------------------------------------------------+----------------+
|00000000| fe 00 00 09 08 74 65 73 74 2e 31 2e 31 0b 58 2d |.....test.1.1.X-|
|00000010| 42 33 2d 54 72 61 63 65 49 64 00 00 20 36 35 37 |B3-TraceId.. 657|
|00000020| 31 32 64 61 35 38 61 61 30 32 35 37 31 62 66 64 |12da58aa02571bfd|
|00000030| 30 66 65 66 34 32 62 34 30 35 36 66 39 0a 58 2d |0fef42b4056f9.X-|
|00000040| 42 33 2d 53 70 61 6e 49 64 00 00 10 31 30 37 32 |B3-SpanId...1072|
|00000050| 36 35 37 36 61 34 66 63 65 34 65 39 10 58 2d 42 |6576a4fce4e9.X-B|
|00000060| 33 2d 50 61 72 65 6e 74 53 70 61 6e 49 64 00 00 |3-ParentSpanId..|
|00000070| 10 62 66 64 30 66 65 66 34 32 62 34 30 35 36 66 |.bfd0fef42b4056f|
|00000080| 39 0b 58 2d 42 33 2d 53 61 6d 70 6c 65 64 00 00 |9.X-B3-Sampled..|
|00000090| 01 31                                           |.1              |
+--------+-------------------------------------------------+----------------+
...

// Application 2
2023-12-07T11:27:49.831+09:00  INFO [65712da58aa02571bfd0fef42b4056f9,9618da9fe0e57514] 12932 --- [ctor-http-nio-9] : do handle
...

Zipkin

Kafka (Reactor)

Reactor-Kafka에서는 비교적 최근에 Tracing Observation Integration이 추가 되었다.
이슈번호 321에서 다뤄졌으며, 2023.10.27에 머지 되었다. (https://github.com/reactor/reactor-kafka/issues/321)
적용된 버전은 1.3.22 이다.

Reactor-Kafka에서 Tracing을 위한 interface로 SenderOptions, ReceiverOptions에서 withObservation() 메서드를 제공한다.
인자로 ObservationRegistry(Micrometer)를 넣어서 tracing을 propagation 한다.
Receiver의 경우 Propagation된 context를 flow에 할당하는 추가적인 로직이 필요하다.

Gradle, application.yml

상동

KafkaSender (producer)

SenderOptions<String, Object> senderOptions = SenderOptions.create(senderProps);
return KafkaSender.create(senderOptions.withObservation(observationRegistry));

ReceiverOptions<String, String> receiverOptions = ReceiverOptions.create(consumerConfig);
KafkaReceiver<String, String> kafkaReceiver = KafkaReceiver.create(
    receiverOptions
        .withObservation(observationRegistry)
        .atmostOnceCommitAheadSize(20)
        .subscription(Pattern.compile("*")));
        

kafkaReceiver
        .receive()
        .flatMap(record -> {
          Observation receiverObservation =
              KafkaReceiverObservation.RECEIVER_OBSERVATION.start(null,
                  KafkaReceiverObservation.DefaultKafkaReceiverObservationConvention.INSTANCE,
                  () ->
                      new KafkaRecordReceiverContext(
                          record, "user.receiver", receiverOptions.bootstrapServers()),
                  observationRegistry);

          return Mono.just(record)
              .doOnNext(r -> log.info("topic: {}, key: {}, value: {}", r.topic(), r.key(), r.value()))
              .doOnTerminate(receiverObservation::stop)
              .doOnError(receiverObservation::error)
              .contextWrite(context -> context.put(ObservationThreadLocalAccessor.KEY, receiverObservation));})
        .subscribe();

Test Log

2023-12-07 13:28:53 [reactor-http-nio-4] INFO [65714a05e50e542ff15b4dfb2c7c3906,f15b4dfb2c7c3906] c.e.t.kafka.ProducerConfig - produce data >> ProducerRecord(topic=chchoi.test.2, partition=null, headers=RecordHeaders(headers = [], isReadOnly = false), key=1, value={"id":"xxx","message":"test"}, timestamp=null)
2023-12-07 13:28:53 [reactor-http-nio-4] INFO [65714a05e50e542ff15b4dfb2c7c3906,f15b4dfb2c7c3906] c.e.t.kafka.ProducerConfig - produce data >> ProducerRecord(topic=chchoi.test.2, partition=null, headers=RecordHeaders(headers = [], isReadOnly = false), key=2, value={"id":"xxx","message":"test"}, timestamp=null)
2023-12-07 13:28:53 [reactive-kafka-test-1-1] INFO [65714a05e50e542ff15b4dfb2c7c3906,71bd25628c1e61ec] c.e.t.kafka.ConsumerConfig - topic: chchoi.test.2, key: 1, value: "{\"id\":\"xxx\",\"message\":\"test\"}"
2023-12-07 13:28:53 [reactive-kafka-test-1-1] INFO [65714a05e50e542ff15b4dfb2c7c3906,d0527c836ddc587c] c.e.t.kafka.ConsumerConfig - topic: chchoi.test.2, key: 2, value: "{\"id\":\"xxx\",\"message\":\"test\"}"

Kafdrop

Zipkin

Conclusion

Spring Cloud Slueth가 Micrometer로 move 됨
Micrometer-tracing에서 Spring Cloud Sleuth로 migration guide를 제공
Micrometer는 Spring이랑 호환성이 매우 뛰어남
Spring Project에서 Log Tracing을 적용하기에 적절
추후 ZipKin 등 log monitoring 도입을 위한 확장성 제공
추후 JVM Metrics등 정보를 받을 수 있도록 확장성을 제공
Spring boot 3에 적용된 reference는 부족함

REFERENCE

REST

RSocket

Reactor-Kafka

시즌2 기획

북극곰은콜라 — Thu, 16 Nov 2023 14:51:32 +0900

개요

연말을 준비하면서 개인 서버의 서비스들을 정리해보고자 한다.
한 동안 바쁜 일정도 있었지만, 최근 서비스 개발이 없었던 이유 중 가장 큰 것은 모노리틱 구조로 설계한 서버도 한몫을 하고 있다.
이전에 MSA 식으로 개발해 봤던 부분과, 올해 모노리틱으로 설계한 부분의 장단점을 분석하고 다음 시즌에는 보다 길고 탄탄한 서비스를 만드는 방향으로 기획하려 한다.

모노리틱 서비스 구조 문제

모노리틱 서비스를 개발할 때 발생하는 문제점에 대한 고찰

너무 많아지는 의존성

예를 들면, 한 프로젝트 내에서 여러 DataSource를 관리해야 되는 문제가 발생했다.
여러 서비스의 성격이 다르고, 적합한 DataSource가 다르다 보니, 서버에 지속적으로 Data Access Point가 늘어나게 되었다.

현시점 연동 상황...
서비스 1은 사실 레디스가 필요 없지만, 프로젝트가 하나기에 영향을 받는다.
개발 시점에, 여러 인프라를 신경 써야 한다...
실제로 db를 안 쓰더라도, 로컬 개발 시, 개발환경의 모든 인프라를 챙겨서 세팅해야 run이 가능하다.

번거로운 서비스 다운

개인 개발 특성상,
실험적인 서비스 또는 한시적인 기능을 돌릴 때가 있다.
하지만, 모노리틱 구조상, 패키지 구조를 신경을 많이 써야, 스무스한 제거가 가능하다.
(하지만, 그런 한시적, 실험적인 부분에 공들여서 만들 리가 없었다..)

비대해지는 소스

일반적인 문제
소스가 점점 뚱뚱해지면서, 리펙토링 등 대부분의 작업에서 리소스가 추가적으로 투입된다.
단순 빌드시간만 해도 계속 늘어난다...

MSA 구조 문제

이전에 MSA 구조로 개발을 진행했었다.
하지만, 여러 문제점이 발생했으며
모든 문제는 하나의 이유로 귀결된다
-> 1인 개발이기에 투입가능한 리소스(시간+열정)가 부족하다..

인프라 작업 시간

당연하게도 1인 개발에서 서버 인프라 관리는 스스로 해야 한다.
또한 비용 투입 없이 하기에, Cloud 서비스 같은 부분은 불가하다.
이에 인프라 하나 추가할 때 모든 관련 설정을 스스로 해야 하고, 이에 투입되는 비용이 너무 컸다.

반복 작업

개인 개발의 최대 동기는 새로운 걸 해보면서 느끼는 재미이다.
하지만, 여러 이유로 반복적인 작업이 늘어난다.
가령 CI / CD도 프로젝트 생성 시마다 일일이 작업해야 하며, 시스템 간 연동을 위한 코드, ip / port 매핑 작업 등등이 있다.
이에 점점 새로운 시도를 하기 귀찮아지며, 신규 개발에서 멀어져 갔다..

Point to Point 연결, 서비스 의존성

A, B 서비스 간의 변경인데, 연동되어 있던 C에서 문제가 발생
인증 쪽 프로세스 변경이라도 일어나면 머리가 아파옵니다.
앞단 인증 쪽에 role 베이스 인가관리 추가하다가, 엄청 터져나갔던 기억이 있네요...

통합 테스트 환경 구축

모듈 여러 개의 통합 테스트를 진행하려면 띄울 거 다 띄우고 진행해야 합니다.
리소스가 부족한 상황에서 mocking을 통한 test case 작성은, 너무나도 힘들었네요...

Next 설계

MSA 구조 채택

모노리틱으로 구성해 본 결과, 1인 개발은 빠른 치고 빠지기가 가능한 MSA 구조가 적합할 것이라 판단됩니다.

손쉬운 프로젝트 추가/제거 구조 확보

최대한 신규 서비스를 추가하기 쉬운 구조를 확보하고 시작
현 계획은
1. Jenkins Script를 활용하여, CI / CD 구성 간소화
2. Zookeeper를 통한 신규 시스템 연동 과정 단순화
3. 관제 서버를 구현하여, 전체적인 서버들의 상황을 모니터링
정도 있다.

Point to Point -> Event Driven

Kafka를 활용하여, 대부분의 비즈니스를 event driven으로 구성,
서비스의 가용성 및 확장성을 확보

마치며

이번에는 전체적인 서버 아키텍처를 설계하고 시작할 것
지금까지의 경험을 최대한 살려서, 지속 가능한 서버 운영을 목표로 함

Windows 10 부팅 지연 이슈 (시스템 예약 위치..)

북극곰은콜라 — Tue, 14 Nov 2023 00:40:46 +0900

개요

어느 날부터인가 부팅이 수십 초 느려지는 현상이 생겼다.
해결 과정에 대해 정리한다.

추측 1

Boot Disk 우선순위 문제?

느려지는 구간은 구동 후 메인보드 로고가 뜨고, BIOS 설정으로 들어갈 수 있는 로딩화면이었다.
이와 비슷한 현상은 이전에 경험해 봤었는데,
바로 boot disk의 우선순위가 잘못 설정되어 있을 때였다.
정기적으로 윈도우를 포맷하여 사용하기에, 이번에도 그런 이슈 일 것이라 추측했다.

스크린샷은 못 찍었지만
확인한 사항으로는 부팅 우선순위는 윈도우가 설치된 SSD었다.
우선 BIOS를 초기 설정으로 되돌리고, 디스크를 윈도우가 설치된 SSD로 돌려보았다.
하지만, 현상은 동일했다.

추측 2

MainBoard 이슈?

두 번째로 의심한 사항은, 메인보드의 자체적인 이슈이다.
사용 후 1~2년 후에 갑자기 나타난 이슈라 솔직히 그럴 리 없다 생각했다.
그래도 일단 확인정도는 해봐야 하기에 관련 이슈를 검색해 보았다.

부팅속도 관련 이슈가 있었으나, 이는 특정 제조사에서 발생하는 이슈였고, 내가 골랐던 메인보드 제조사는 관련 사항이 없었다.
생각해 보면, 메인보드 고를 때 꽤나 시간 들여서 하드웨어 이슈사항에 대해서 검색해 보았었기에, 이 문제는 아닐 거라 생각했다.

실마리 발견!

결국 이슈는 해결 못한 체 어제까지 해당 이슈를 체념하고 있었다.
다른 사항 때문에 디스크 관리자 쪽을 보았었는데, 시스템 예약이 이상하게 잡혀있던 것을 발견했다!
분명 시스템 예약은 C드라이브 쪽 디스크에 있어야 정상일 텐데...

시스템 예약이란

시스템 예약은 윈도우 설치 도중 생성되는 파티션으로, 시스템에서 나중에 사용하기 위해 일부 공간을 미리 할당해 놓는 곳이다. 중요한 점은 부팅을 위한 구성요소 중 일부가 여기에 저장되는 것이다.

역할

여기에는 부팅을 위한 데이터 (BCD), 윈도우 복구 환경 (WinRE) 등 시스템에서 필요한 데이터를 저장하는 역할을 한다. BCD는 부팅할 때 참조하는 데이터이고, WinRE는 윈도우 복구 툴을 사용할 때 참조하는 데이터이다.
요약하면, 윈도우 시스템에서 필요한 1차적인 데이터들이라 볼 수 있다.

추측

현상은 윈도우 Booting이 오래 걸리는 것이며, 디스크를 못 찾는 현상과 유사했었다.
이에 부팅 시 시스템 예약 파티션을 찾지 못해서 지연이 발생한 것이라 추측했다.

검색해 보니 윈도우 설치위치와 다른 곳에 할당된 시스템 예약을 복구할 수 있는 방법이 있었다.
이를 적용해 보았다.

해결과정

여러 블로그를 뒤져서 다른 파티션의 시스템 예약을 옮기는 방법을 찾았다.
요약하면
1. 간단하게 BCD 부팅 파일을 윈도우가 설치된 디스크에 새로 생성하고
2. 부팅 옵션을 해당 디스크로 설정하고
3. 잘못된 시스템 예약을 disable 시킨다.

BCD 부트 매니저 생성 및 설정

// bcdboot 명령을 통해 bootmgr를 생성한다.
bcdboot c:\windows /s c: /l ko-kr 
// bcdedit을 통해 부팅할 파티션을 지정한다.
bcdedit /set {bootmgr} device partition=c:

지금은 이미 활성해서 회색이지만, 파티션을 활성 파티션으로 표시한다.

잘못된 시스템 예약 파티션 Disable

C:\windows\system32>diskpart

...

DISKPART> list disk

  디스크 ###  상태           크기     사용 가능     Dyn  Gpt
  ----------  -------------  -------  ------------  ---  ---
  디스크 0    온라인        931 GB       1024 KB
  디스크 1    온라인       1863 GB           0 B
  디스크 2    온라인        232 GB           0 B
  디스크 3    온라인        111 GB       1024 KB

DISKPART> select disk 0

0 디스크가 선택한 디스크입니다.

DISKPART> list partition

  파티션 ###  종류              크기     오프셋
  ----------  ----------------  -------  -------
  파티션 1    주                  549 MB  1024 KB
  파티션 2    주                  930 GB   550 MB

DISKPART> select partition 1

1 파티션이 선택한 파티션입니다.

DISKPART> inactive

...

diskpart를 통해 500MB쯤 되는 시스템 예약을 inactive 시켰다.

주저리

부팅 지연 이슈는 해결되었다.
기분이 좋은 것을 보니 생각보다 그동안 스트레스를 받았던 것 같다.
이 이슈는 아마 언젠가 윈도우 포맷 중 설정을 잘못해서 발생한 것으로 추정된다.

정기적으로 포맷하는 습관을 줄여야 하는데...
학창 시절 윈도우는 SSD에 설치해야겠는데, 돈은 없어서 SSD 용량이 적었다...
이에 SSD로 윈도우만 설치하고, 상대적으로 싼 HDD로 다른 프로그램을 사용하던 시절이 있었다.
하지만 윈도우는 사용하다 보면 local 등 여러 잡다한 데이터가 쌓이게 되고, SSD의 용량이 부족해졌다.
그 시절부터 정기적으로 용량 확보를 위해 windows 포맷을 즐겼었다.
한 번씩 대청소를 하는 기분 + 새로 PC를 최적화 세팅하는 즐거움? 이 있어 아직도 하고 있다...

지금 쓰는 윈도우 SSD가 120GB 밖에 안 되는 것도 이 영향이 있다.
근데 슬슬 이 습관도 자제하는 게 좋을지도 모른다고 생각한다.

REFERENCE

- https://quasarzone.com/bbs/qf_cmr/views/2111658

- https://rootblog.tistory.com/218 (Special Thanks)

Spring Webflux Threading (publishOn, subscribeOn) 분석

북극곰은콜라 — Mon, 30 Oct 2023 19:56:02 +0900

개요

Reactor에서 제공하는 Pub / Sub 모델은 실행될 Thread를 전략적으로 선택할 수 있게 interface를 제공한다.
- publishOn(Scheduler scheduler): 어디에서 Publish 될 것인가
- subscribeOn(Scheduler scheduler): 어디에서 subscribe 할 것인가

Scheduler

interface Scheduler extends Disposable {
    
  Disposable schedule(Runnable task);
  Disposable schedule(Runnable task, long initialDelay, TimeUnit delayUnit);
  Disposable schedulePeriodically(Runnable task, long initialDelay, long period, TimeUnit unit);
  
  long now(TimeUnit unit);
  
  Worker createWorker();
  
  interface Worker extends Disposable {
    Disposable schedule(Runnable task);
    Disposable schedule(Runnable task, long initialDelay, TimeUnit delayUnit);
    Disposable schedulePeriodically(Runnable task, long initialDelay, long period, TimeUnit unit);
  }
}

Scheduler는 사용자에게 threading을 효율적으로 제어할 수 있도록 설계된 interface이다.
Worker는 Scheduler에 의해 create되며, 역할은 task를 execute 하는 것이다.
일반적으로 구현체는 각각 용도에 맞는 ExecutorService 또는 그 reference를 가지고 있으며
해당 executorService를 활용하여 Thread를 구현로직에 따라 Execute한다. (일반적으로 스케쥴링을 위한 ScheduledExecutorService를 가지고 있다.)

Default Schedulers

Project Reactor에서는 기 구현된 클래스들을 제공한다.
이는 Schedulers 클래스의 static 메서드로 제공 받을 수 있다.

주요 Scheduler

ImmediateScheduler:
- Thread 변경 없는 scheduler → ExecutorService를 쓰지 않는다.
- interface상 scheduler가 notNull일 시 사용
singleScheduler:
- Thread 하나 짜리 executorService에서 돌아가는 scheduler, 한번에 하나만 실행될 작업에 적합
ParallelScheduler:
- Parall한 작업을 수행하기 위한 scheduler, 다수의 작업을 짧게 실행하기에 적합하다.
- I/O등 작업을 수행하기 부적합. (parall Thread는 기본적으로 CPU 갯수)
- 기본적인 Reactor 연산의 기본값 (reactor-http-nio 등)
BoundedElasticScheduler:
- ExecutorService에서 Worker를 생성하고, 재사용
- I/O 작업 등 시간이 걸리는 작업을 수행하기 적합
- worker는 1분 이상 idle 되면 제거
ExecutorScheduler:
- custom executor를 세팅할 수 있는 scheduler
- 개발자는 반드시 executorService로 lifeCycle 관리를 해야 함

Operator: PublishOn(), SubscribeOn()

Reactor에서 Scheduler를 적용할 수 있게 제공하는 method 이다.
- publishOn(): Source로부터 이하 로직이 실행 될 Scheduler를 지정할 수 있는 메서드 subscribeOn(): Source부터 - Scheduler가 지정되지 않은 upStream의 시작점부터 Scheduler를 적용할 수 있는 메서드

PublishOn()

public static void main(String[] args) {
  Mono.just("pubEx")
      .doOnNext(body -> log.info("1"))
      .publishOn(Schedulers.newSingle("single1"))
      .doOnNext(body -> log.info("2"))
      .publishOn(Schedulers.parallel())
      .doOnNext(body -> log.info("3"))
      .publishOn(Schedulers.boundedElastic())
      .doOnNext(body -> log.info("4"))
      .subscribe();
}

09:47:37.881 [main] INFO com.ht.iot.smr.node.sample.inbound.rest.TestRouter -- 1
09:47:37.886 [single1-1] INFO com.ht.iot.smr.node.sample.inbound.rest.TestRouter -- 2
09:47:37.887 [parallel-1] INFO com.ht.iot.smr.node.sample.inbound.rest.TestRouter -- 3
09:47:37.888 [boundedElastic-1] INFO com.ht.iot.smr.node.sample.inbound.rest.TestRouter -- 4

최초 실행 쓰레드는 main으로 1번 로그는 main Thread에서 실행된다.
2, 3, 4는 각각 doOnNext 전 Scheduler를 지정하여 실행된 것을 확인할 수 있다.

SubscribeOn()

public static void main(String[] args) {
  Mono.just("subEx")
      .doOnNext(body -> log.info("1"))
      .doOnNext(body -> log.info("2"))
      .subscribeOn(Schedulers.newSingle("single1"))
      .doOnNext(body -> log.info("3"))
      .subscribeOn(Schedulers.parallel())
      .doOnNext(body -> log.info("4"))
      .subscribeOn(Schedulers.boundedElastic())
      .subscribe();
}

10:18:58.911 [single1-1] INFO com.ht.iot.smr.node.sample.inbound.rest.TestRouter -- 1
10:18:58.914 [single1-1] INFO com.ht.iot.smr.node.sample.inbound.rest.TestRouter -- 2
10:18:58.914 [single1-1] INFO com.ht.iot.smr.node.sample.inbound.rest.TestRouter -- 3
10:18:58.914 [single1-1] INFO com.ht.iot.smr.node.sample.inbound.rest.TestRouter -- 4

SubscribeOn은 PublishOn과 다르게, Scheduler가 적용되지 않은 upStream에 Scheduler를 등록한다.
따라서 최초의 newSingle() 스케쥴러는 적용되었지만, 이하 parallel, boundedElastic은 적용되지 못 했다.
자세한 사항은 후술

public Mono<ServerResponse> test(final ServerRequest serverRequest) {
  return serverRequest.bodyToMono(HashMap.class)
      .flatMap(x -> Mono.just(x)
          .subscribeOn(Schedulers.boundedElastic())
          .doOnNext(body -> log.info(Thread.currentThread().getName()))
          .doOnNext(body -> log.info("1"))
          .doOnNext(body -> log.info("2")))
      .flatMap(x -> ServerResponse.ok().build());
}

2023-10-26T14:04:40.575+09:00  INFO 10540 --- [oundedElastic-1] c.h.i.s.n.s.inbound.rest.TestRouter      : boundedElastic-1
2023-10-26T14:04:40.575+09:00  INFO 10540 --- [oundedElastic-1] c.h.i.s.n.s.inbound.rest.TestRouter      : 1
2023-10-26T14:04:40.575+09:00  INFO 10540 --- [oundedElastic-1] c.h.i.s.n.s.inbound.rest.TestRouter      : 2

scheduler 적용 예시

Scheduler 적용/미적용 비교

public static void main(String[] args) {
    Flux.fromIterable(List.of("1","2","3","4"))
        .doOnNext(TestRouter::wait1000)
        .subscribe();
    Flux.fromIterable(List.of("A","B","C","D"))
        .doOnNext(TestRouter::wait1000)
        .subscribe();
  }

10:00:06.700 [main] INFO com.ht.iot.smr.node.sample.inbound.rest.TestRouter -- 1
10:00:07.712 [main] INFO com.ht.iot.smr.node.sample.inbound.rest.TestRouter -- 2
10:00:08.720 [main] INFO com.ht.iot.smr.node.sample.inbound.rest.TestRouter -- 3
10:00:09.726 [main] INFO com.ht.iot.smr.node.sample.inbound.rest.TestRouter -- 4
10:00:10.737 [main] INFO com.ht.iot.smr.node.sample.inbound.rest.TestRouter -- A
10:00:11.741 [main] INFO com.ht.iot.smr.node.sample.inbound.rest.TestRouter -- B
10:00:12.752 [main] INFO com.ht.iot.smr.node.sample.inbound.rest.TestRouter -- C
10:00:13.765 [main] INFO com.ht.iot.smr.node.sample.inbound.rest.TestRouter -- D

1초씩 딜레이를 줘서 로깅하는 로직이 실행 된다.
1번 Subscribe가 종료되어야, 2번 subscribe가 진행되는 것을 확인할 수 있다.
이는 내부 로직이 main Thread에서 진행되기 때문에, main이 blocking으로 동작하여, 1번 subscribe line이 끝나야 2번 subscribe line이 실행되기 때문

public static void main(String[] args) {
    Flux.fromIterable(List.of("1","2","3","4"))
        .publishOn(Schedulers.boundedElastic())
        .doOnNext(TestRouter::wait1000)
        .subscribe();
    Flux.fromIterable(List.of("A","B","C","D"))
        .publishOn(Schedulers.boundedElastic())
        .doOnNext(TestRouter::wait1000)
        .subscribe();
  }

10:02:43.690 [boundedElastic-2] INFO com.ht.iot.smr.node.sample.inbound.rest.TestRouter -- A
10:02:43.690 [boundedElastic-1] INFO com.ht.iot.smr.node.sample.inbound.rest.TestRouter -- 1
10:02:44.704 [boundedElastic-2] INFO com.ht.iot.smr.node.sample.inbound.rest.TestRouter -- B
10:02:44.704 [boundedElastic-1] INFO com.ht.iot.smr.node.sample.inbound.rest.TestRouter -- 2
10:02:45.714 [boundedElastic-1] INFO com.ht.iot.smr.node.sample.inbound.rest.TestRouter -- 3
10:02:45.714 [boundedElastic-2] INFO com.ht.iot.smr.node.sample.inbound.rest.TestRouter -- C
10:02:46.727 [boundedElastic-2] INFO com.ht.iot.smr.node.sample.inbound.rest.TestRouter -- D
10:02:46.727 [boundedElastic-1] INFO com.ht.iot.smr.node.sample.inbound.rest.TestRouter -- 4

Scheduler 적용 시 이하 프로세스는 Scheduler에서 관리되며 main Thread의 경우 다음 line으로 넘어간다.
Scheduler는 각각의 Thread에서 로직을 executorService를 통해서 실행하며, 서로 간섭하지 않는다.

PublishOn() VS SubscribeOn()

public static void main(String[] args) {
  Mono.just("pub vs sub")
      .doOnNext(body -> log.info("1"))
      .publishOn(Schedulers.newSingle("pub"))
      .doOnNext(body -> log.info("2"))
      .publishOn(Schedulers.parallel())
      .doOnNext(body -> log.info("3"))
      .subscribeOn(Schedulers.newSingle("sub"))
      .doOnNext(body -> log.info("4"))
      .subscribe();
}

10:28:30.634 [sub-1] INFO com.ht.iot.smr.node.sample.inbound.rest.TestRouter -- 1
10:28:30.638 [pub-2] INFO com.ht.iot.smr.node.sample.inbound.rest.TestRouter -- 2
10:28:30.638 [parallel-1] INFO com.ht.iot.smr.node.sample.inbound.rest.TestRouter -- 3
10:28:30.638 [parallel-1] INFO com.ht.iot.smr.node.sample.inbound.rest.TestRouter -- 4

1번 로직은 본래 main 쓰레드에서 execute 했었지만 .subscribeOn(Schedulers.newSingle("sub")) 으로 인하여 sub(single)에서 execute되었다.
2번은 .publishOn(Schedulers.newSingle("pub")) 으로 pub(single)에서 실행 되었으며
3,4번은 다시 parallel로 변경 된 상황이다.

Conclusion

Schedule in Webflux

정리하면 PubOn과 SubOn은 주도권을 누가 가져갈 것 인가에 대한 차이이다.
- PubOn은 이하 로직은 내가 주도권을 가지고 Schedule을 지정 하는 것
- SubOn은 수동적으로 Schedule을 지정하는 것 이다.
가령 일반적으로 http 요청을 받아 response를 주는 과정은 Webflux에서 주도권을 가지고 Schedule을 지정한다.
따라서 HttpHandle 과정 request → executeHandler → (handle) → handleResult → response는 reactor의 schedule(reactor-http-nio-x)에서 처리하게 된다.
해당 스케쥴은 netty(or jetty, undertow, etc…) 에서 관리되는 executor를 사용하고 있다.
따라서 capacity가 유한하며, 서버 기동 시 설정에 의해 결정된다.

// 주의!
reactor-http 쪽 WorkerPool 또한 유한하기 때문에, I/O 작업 등 기타 시간이 걸리는 작업은 최대한 다른 Scheduler에서 실행되는 것이 바람직하다.
ex) DB 작업은 r2dbc에서 관리되는 scheduler로 실행되게 flatmap해서 사용해야, http-netty-connector가 효율적으로 request를 accept 할 수 있다. 그렇기 때문에, R2DBC 또는 reactive하지 않은 방식으로 DB를 사용할 경우 오히려 servlet 방식보다 성능이 떨어질 수 있다.

public Mono<ServerResponse> test(final ServerRequest serverRequest) {
  return serverRequest.bodyToMono(HashMap.class)
      .doOnNext(body -> log.info(Thread.currentThread().getName()))
      .doOnNext(body -> log.info("1"))
      .doOnNext(body -> log.info("2"))
      .subscribeOn(Schedulers.boundedElastic())
      .flatMap(x -> ServerResponse.ok().build());
}

2023-10-26T13:11:29.742+09:00  INFO 10884 --- [ctor-http-nio-3] c.h.i.s.n.s.inbound.rest.TestRouter      : reactor-http-nio-3
2023-10-26T13:11:29.742+09:00  INFO 10884 --- [ctor-http-nio-3] c.h.i.s.n.s.inbound.rest.TestRouter      : 1
2023-10-26T13:11:29.742+09:00  INFO 10884 --- [ctor-http-nio-3] c.h.i.s.n.s.inbound.rest.TestRouter      : 2

netty에서 이미 Scheduler를 지정했기 때문에 subscribeOn이 적용되지 못한 상황 예시

Schedule 활용 예시

1. Webflux Request handling 최적화

public Mono<ServerResponse> test(final ServerRequest serverRequest) {
  return serverRequest.bodyToMono(HashMap.class)
      .doOnNext(x -> wait1000("1"))
      .doOnNext(x -> wait1000("2"))
      .doOnNext(x -> wait1000("3"))
      .flatMap(x -> ServerResponse.ok().build());
}

2023-10-26T13:51:49.133+09:00  INFO 19628 --- [ctor-http-nio-3] c.h.i.s.n.s.inbound.rest.TestRouter      : 1: reactor-http-nio-3
2023-10-26T13:51:50.144+09:00  INFO 19628 --- [ctor-http-nio-3] c.h.i.s.n.s.inbound.rest.TestRouter      : 2: reactor-http-nio-3
2023-10-26T13:51:51.160+09:00  INFO 19628 --- [ctor-http-nio-3] c.h.i.s.n.s.inbound.rest.TestRouter      : 3: reactor-http-nio-3

// Scheduler 적용
public Mono<ServerResponse> test(final ServerRequest serverRequest) {
  return serverRequest.bodyToMono(HashMap.class)
      .publishOn(Schedulers.boundedElastic())
      .doOnNext(x -> wait1000("1"))
      .doOnNext(x -> wait1000("2"))
      .doOnNext(x -> wait1000("3"))
      .flatMap(x -> ServerResponse.ok().build());
}

2023-10-26T13:53:37.177+09:00  INFO 24192 --- [oundedElastic-1] c.h.i.s.n.s.inbound.rest.TestRouter      : 1: boundedElastic-1
2023-10-26T13:53:38.187+09:00  INFO 24192 --- [oundedElastic-1] c.h.i.s.n.s.inbound.rest.TestRouter      : 2: boundedElastic-1
2023-10-26T13:53:39.200+09:00  INFO 24192 --- [oundedElastic-1] c.h.i.s.n.s.inbound.rest.TestRouter      : 3: boundedElastic-1

Webflux에서 시간이 오래 소요 될 것 같은 작업은 publishOn을 통해 reactor Thread를 release

2. 여러 작업을 동시에 execute 할 때

public Mono<ServerResponse> test(final ServerRequest serverRequest) {
  return serverRequest.bodyToMono(HashMap.class)
      .doOnNext(x -> Mono.just(x)
          .subscribeOn(Schedulers.boundedElastic())
          .doOnNext(xx -> wait2000("1"))
          .subscribe())
      .doOnNext(x -> Mono.just(x)
          .subscribeOn(Schedulers.boundedElastic())
          .doOnNext(xx -> wait1000("2"))
          .subscribe())
      .doOnNext(x -> Mono.just(x)
          .subscribeOn(Schedulers.boundedElastic())
          .doOnNext(xx -> wait1000("3"))
          .subscribe())
      .doOnNext(body -> log.info("last"))
      .flatMap(x -> ServerResponse.ok().build());
}

2023-10-26T14:10:30.927+09:00  INFO 15004 --- [ctor-http-nio-3] c.h.i.s.n.s.inbound.rest.TestRouter      : last
2023-10-26T14:10:31.930+09:00  INFO 15004 --- [oundedElastic-6] c.h.i.s.n.s.inbound.rest.TestRouter      : 3: boundedElastic-6
2023-10-26T14:10:31.930+09:00  INFO 15004 --- [oundedElastic-1] c.h.i.s.n.s.inbound.rest.TestRouter      : 2: boundedElastic-1
2023-10-26T14:10:32.933+09:00  INFO 15004 --- [oundedElastic-4] c.h.i.s.n.s.inbound.rest.TestRouter      : 1: boundedElastic-4

별도의 scheduler를 설정해서 subscribe를 하는 경우
메인 flow 외 별도의 flow로 consume을 하게 된다.
이 상황에 Scheduler를 설정하면 손쉽게 해당 flow를 별도의 schedule로 동작하게 할 수 있다.

3. 전역 또는 Scoped에서 한번에 하나만 실행

@Scheduled("...")
public void batch1_1() {
  Mono.just("1")
      .publishOn(Schedulers.single())
      .doOnNext(TestRouter::wait1000)
      .subscribe();
}
@Scheduled("...")
public void batch1_2() {
  Mono.just("2")
      .publishOn(Schedulers.single())
      .doOnNext(TestRouter::wait1000)
      .subscribe();
}

위 상황처럼 배치가 여러개 돌아갈 때
한번에 하나씩만 수행하도록 하고 싶다면, single() 스케쥴러를 통해 스케쥴링 하면 된다.
이러면 batch1_1과 batch1_2가 동시에 수행되는 것을 방지할 수 있다.

요약

- Reactor진영에서는 Scheduler를 통해 로직이 실행 될 Thread 환경을 지정할 수 있다.
- 로직의 실행 Thread에 대한 주도권을 가질 땐 PublishOn, 로직을 subscribe할 때 default를 지정 할 목적이면 subscribeOn
- Webflux에서 I/O등 시간이 걸리는 작업은 scheduler를 지정하여(elastic 추천) 수행

REFERENCE

https://spring.io/blog/2019/12/13/flight-of-the-flux-3-hopping-threads-and-schedulers

Spring RSocket Code 분석

북극곰은콜라 — Sun, 29 Oct 2023 13:43:49 +0900

개요

RSocket을 Spring에 Integration 하는 코드 분석

RSocket은 Spring-Message 라이브러리를 통해 Spring Context에 Integration 되었다.

ini Server

public abstract class AbstractMethodMessageHandler<T>
		implements ReactiveMessageHandler, ApplicationContextAware, InitializingBean, BeanNameAware {
		...
    @Override
	public void afterPropertiesSet() {
		List<? extends HandlerMethodArgumentResolver> resolvers = initArgumentResolvers();
		...
		this.invocableHelper.addArgumentResolvers(resolvers);
		List<? extends HandlerMethodReturnValueHandler> handlers = initReturnValueHandlers();
		...
		this.invocableHelper.addReturnValueHandlers(handlers);
		initHandlerMethods();
	}
	...
}

public class RSocketMessageHandler extends MessageMappingMessageHandler {
    ...
    @Override
	public void afterPropertiesSet() {
		// Add argument resolver before parent initializes argument resolution
		getArgumentResolverConfigurer().addCustomResolver(new RSocketRequesterMethodArgumentResolver());

		super.afterPropertiesSet();

		getHandlerMethods().forEach((composite, handler) -> {
			if (composite.getMessageConditions().contains(RSocketFrameTypeMessageCondition.CONNECT_CONDITION)) {
				MethodParameter returnType = handler.getReturnType();
				if (getCardinality(returnType) > 0) {
					throw new IllegalStateException(
							"Invalid @ConnectMapping method. " +
									"Return type must be void or a void async type: " + handler);
				}
			}
		});
	}
	...
}

spring message에서 구현된 reactive 환경의 invoke handle method 관련 클래스
InitializingBean을 구현하여, spring init 시점에 handlerMethod들을 load 한다.
invocableHelper는 추후 payload를 handling할 때 사용

Handle Payload

...
@Override
public Mono<Payload> requestResponse(Payload payload) {
	return handleAndReply(payload, FrameType.REQUEST_RESPONSE, Flux.just(payload)).next();
}
...


private Flux<Payload> handleAndReply(Payload firstPayload, FrameType frameType, Flux<Payload> payloads) {
	...
	MessageHeaders headers = createHeaders(firstPayload, frameType, responseRef);
	...
	Flux<DataBuffer> buffers = payloads.map(this::retainDataAndReleasePayload).doOnSubscribe(s -> read.set(true));
	Message<Flux<DataBuffer>> message = MessageBuilder.createMessage(buffers, headers);
	return Mono.defer(() -> this.messageHandler.handleMessage(message))
			...
}

RSocket 메시지를 파싱하고 fire&forget, request&response, request&stream 등 정보를 바탕으로 호출되는 메서드이다.
1. payload에서 header 파싱
2. payload에서 DataBuffer로 read
3. DataBuffer + header 로 Message 생성
4. messageHandler로 messsage handle

AbstractMethodMessageHandler (spring-messaging)

@Override
public Mono<Void> handleMessage(Message<?> message) throws MessagingException {
	...
	match = getHandlerMethod(message);
	...
	return handleMatch(match.mapping, match.handlereMthod, message);
}

protected Mono<Void> handleMatch(T mapping, HandlerMethod handlerMethod, Message<?> message) {
	handlerMethod = handlerMethod.createWithResolvedBean();
	return this.invocableHelper.handleMessage(handlerMethod, message);
}

public Mono<Void> handleMessage(HandlerMethod handlerMethod, Message<?> message) {
	InvocableHandlerMethod invocable = initMessageMappingMethod(handlerMethod);
	..
	return invocable.invoke(message)
			.switchIfEmpty(Mono.defer(() -> handleReturnValue(null, invocable, message)))
			.flatMap(returnValue -> handleReturnValue(returnValue, invocable, message))
			...
}

private Match<T> getHandlerMethod(Message<?> message) {
	List<Match<T>> matches = new ArrayList<>();

	RouteMatcher.Route destination = getDestination(message);
	List<T> mappingsByUrl = (destination != null ? this.destinationLookup.get(destination.value()) : null);
	if (mappingsByUrl != null) {
		addMatchesToCollection(mappingsByUrl, message, matches);
	}
	if (matches.isEmpty()) {
		// No direct hits, go through all mappings
		Set<T> allMappings = this.handlerMethods.keySet();
		addMatchesToCollection(allMappings, message, matches);
	}
	if (matches.isEmpty()) {
		handleNoMatch(destination, message);
		return null;
	}
	Comparator<Match<T>> comparator = new MatchComparator(getMappingComparator(message));
	matches.sort(comparator);
	if (logger.isTraceEnabled()) {
		logger.trace("Found " + matches.size() + " handler methods: " + matches);
	}
	Match<T> bestMatch = matches.get(0);
	if (matches.size() > 1) {
		Match<T> secondBestMatch = matches.get(1);
		if (comparator.compare(bestMatch, secondBestMatch) == 0) {
			HandlerMethod m1 = bestMatch.handlerMethod;
			HandlerMethod m2 = secondBestMatch.handlerMethod;
			throw new IllegalStateException("Ambiguous handler methods mapped for destination '" +
					(destination != null ? destination.value() : "") + "': {" +
					m1.getShortLogMessage() + ", " + m2.getShortLogMessage() + "}");
		}
	}
	return bestMatch;
}

handlerMethod

spring-messaging에서 구현한 class이다. method invoke하기 위한 모든 정보를 맴버로 갖는다.

Match

mapping 정보 + handlerMethod를 가진 spring-messageing의 private class

1. Message를 handle할 수 있는 method를 찾는다 (mapping 정보 등..)
2. invoke가 가능한 method 프락시 객체 생성
3. reflection으로 method 실행

Spring Cloud Gateway Code 분석

북극곰은콜라 — Sat, 28 Oct 2023 12:38:25 +0900

개요

Spring Cloud Gateway 동작 원리를 code를 통해 분석

Spring Cloud Gateway 동작 원리

Predicates and filters are specific to routes

Spring Cloud Gateway의 핵심 아이디어인 “Routing 및 지역적 filter apply” 를 위해 HandlerMapping을 구현해서 추가했다.
HandlerMapping은 Filter 이후 Exchange를 처리할 Handler를 찾는 클래스이다.

RoutePredicateHandlerMapping으로 구현했으며, 구현된 핵심은
exchange를 기반으로 Route를 찾아서 attribute에 route를 넣는 작업
이후 FilteringWebHandler(webHandler 구현체)를 통해 작업을 진행

FilteringWebHandler는 exchange에서 Route를 가져와서 필터가 필요한지 확인한다.
적용된 필터와, GlobalFilter랑 합쳐서 FilterChain을 만들어 처리한다.

GatewayAutoConfiguration

@Configuration(proxyBeanMethods = false)
@ConditionalOnProperty(name = "spring.cloud.gateway.enabled", matchIfMissing = true)
@EnableConfigurationProperties
@AutoConfigureBefore({ HttpHandlerAutoConfiguration.class, WebFluxAutoConfiguration.class })
@AutoConfigureAfter({ GatewayReactiveLoadBalancerClientAutoConfiguration.class,
		GatewayClassPathWarningAutoConfiguration.class })
@ConditionalOnClass(DispatcherHandler.class)
public class GatewayAutoConfiguration {
  ...
  
  @Bean
  @ConditionalOnMissingBean
  public FilteringWebHandler filteringWebHandler(List<GlobalFilter> globalFilters) {
		return new FilteringWebHandler(globalFilters);
  }
	
  ...
  
  @Bean
  @ConditionalOnMissingBean
  public RoutePredicateHandlerMapping routePredicateHandlerMapping(FilteringWebHandler webHandler,
			RouteLocator routeLocator, GlobalCorsProperties globalCorsProperties, Environment environment) {
		return new RoutePredicateHandlerMapping(webHandler, routeLocator, globalCorsProperties, environment);
  }
  
  ...
}

RoutePredicateHandlerMapping

// AbstractHandlerMapping
public Mono<Object> getHandler(ServerWebExchange exchange) {
  return this.getHandlerInternal(exchange).map((handler) -> {
    ...
    ServerHttpRequest request = exchange.getRequest();
    ...
    return handler;
  });
}

HandlerMapping은 전략패턴으로 구성되었으며
구현체의 getHandlerInternal()을 호출해 Mono로 Handler를 받아 Handler 공통 작업을 수행한다.

@Override
protected Mono<?> getHandlerInternal(ServerWebExchange exchange) {
	...

	return Mono.deferContextual(contextView -> {
		...
		return lookupRoute(exchange)
				.flatMap((Function<Route, Mono<?>>) r -> {
					...

					exchange.getAttributes().put(GATEWAY_ROUTE_ATTR, r);
					return Mono.just(webHandler);
				}).switchIfEmpty(Mono.empty().then(Mono.fromRunnable(() -> {
					...
				})));
	});
}

protected Mono<Route> lookupRoute(ServerWebExchange exchange) {
	return this.routeLocator.getRoutes()
			.concatMap(route -> Mono.just(route).filterWhen(r -> {
				exchange.getAttributes().put(GATEWAY_PREDICATE_ROUTE_ATTR, r.getId());
				return r.getPredicate().apply(exchange);
			})
					...
			.next()
			.map(route -> {
				...
				validateRoute(route, exchange);
				return route;
			});
}

RoutePredicateHandlerMapping은 lookupRoute로 Predicate에 부합하는 Route 객체를 exchange에 attribute로 put 한다.

FilteringWebHandler (Gateway)

@Override
public Mono<Void> handle(ServerWebExchange exchange) {
    Route route = exchange.getRequiredAttribute(GATEWAY_ROUTE_ATTR);
    List<GatewayFilter> gatewayFilters = route.getFilters();

    List<GatewayFilter> combined = new ArrayList<>(this.globalFilters);
    combined.addAll(gatewayFilters);
    AnnotationAwareOrderComparator.sort(combined);

    ...

    return new DefaultGatewayFilterChain(combined).filter(exchange);
}

HandlerMapping의 getHandler() 는 최종적으로
return Mono.just(webHandler); 를 통해서 FilteringWebHandler를 반환한다.
이 후 handlerAdapter에서 FilteringWebHandler의 handle()을 호출한다.

Match Exchange with Route

lookupRoute

// RoutePredicateHandlerMapping.java
protected Mono<Route> lookupRoute(ServerWebExchange exchange) {
	return this.routeLocator.getRoutes()
			.concatMap(route -> Mono.just(route).filterWhen(r -> {
				exchange.getAttributes().put(GATEWAY_PREDICATE_ROUTE_ATTR, r.getId());
				return r.getPredicate().apply(exchange);
			})
			...
			.next()
			.map(route -> {
				...
				validateRoute(route, exchange);
				return route;
			});
}

// RouteDefinitionRouteLocator
@Override
public Flux<Route> getRoutes() {
	return getRoutes(this.routeDefinitionLocator.getRouteDefinitions()); // RouteDefinitions from CacheFlux
}

private Flux<Route> getRoutes(Flux<RouteDefinition> routeDefinitions) {
	Flux<Route> routes = routeDefinitions.map(this::convertToRoute);
    ...
	return routes.map(route -> {
		...
		return route;
	});
}

Cache로 부터 모든 Route 객체를 변환 받아 predicate를 돌린다.

번외: Predicate Route

Java Predicate를 reactior를 통해 Async하게 test할 수 있게 하는 Spring Cloud Gateway의 아이디어이다.
사용자가 작성한 Predicate 전체를 sync하게 처리하지 않고, 모든 predicate를 async하게 바꿔 처리하기 위함으로 추정된다.
delegate와 decorate 패턴을 활용한다.

Java Predicate

@FunctionalInterface
public interface Predicate<T> {
  boolean test(T var1);

  default Predicate<T> and(Predicate<? super T> other) {
    Objects.requireNonNull(other);
    return (t) -> {
      return this.test(t) && other.test(t);
    };
  }

  default Predicate<T> negate() {
    return (t) -> {
      return !this.test(t);
    };
  }

  default Predicate<T> or(Predicate<? super T> other) {
    Objects.requireNonNull(other);
    return (t) -> {
      return this.test(t) || other.test(t);
    };
  }

  static <T> Predicate<T> isEqual(Object targetRef) {
    return null == targetRef ? Objects::isNull : (object) -> {
      return targetRef.equals(object);
    };
  }

  static <T> Predicate<T> not(Predicate<? super T> target) {
    Objects.requireNonNull(target);
    return target.negate();
  }
}

Java Objects의 Functional 인테페이스이다.
특정 Object의 조건을 서술한 Function을 사전에 정의하여
다른 로직에서 해당 조건을 불러와 사용할 수 있다.
또한
and, or, negate, not, isEqual 메서드를 지원하여 function의 chaining을 할 수 있게 했다.

// 심플한 사용 예
Predicate<Object> isString = o -> o instanceof String;
System.out.println(isString.test("")); // true
System.out.println(isString.test(1)); // false

// predicate Chain
Predicate<String> isStartWithA = s -> s.startsWith("A");
Predicate<String> isEndWithA = s -> s.endsWith("A");
System.out.println(isStartWithA.and(isEndWithA).test("ABB")); // false
System.out.println(isStartWithA.and(isEndWithA).test("ABA")); // true

Predicate with Reactor

public interface AsyncPredicate<T> extends Function<T, Publisher<Boolean>>, HasConfig {
  default AsyncPredicate<T> and(AsyncPredicate<? super T> other) {
	return new AndAsyncPredicate<>(this, other);
  }
  
  default AsyncPredicate<T> negate() {
		return new NegateAsyncPredicate<>(this);
  }
  
  default AsyncPredicate<T> not(AsyncPredicate<? super T> other) {
		return new NegateAsyncPredicate<>(other);
  }
  
  default AsyncPredicate<T> or(AsyncPredicate<? super T> other) {
		return new OrAsyncPredicate<>(this, other);
  }
	
  ...
}

Predicate를 Reactive 환경에서 Async하게 처리하기 위해 구현된 파트 중 일부이다.
Predicate의 체인을 만들고
Java Function apply를 통해 모든 Predicate를 순서있는 비동기 처리를 구현했다.

분석

// Default
@Override
public Publisher<Boolean> apply(T t) {
	return Mono.just(delegate.test(t));
}

// Negate
@Override
public Publisher<Boolean> apply(T t) {
	return Mono.from(predicate.apply(t)).map(b -> !b);
}

// And
@Override
public Publisher<Boolean> apply(T t) {
	return Mono.from(left.apply(t)).flatMap(result -> !result ? Mono.just(false) : Mono.from(right.apply(t)));
}

// Or
@Override
public Publisher<Boolean> apply(T t) {
	return Mono.from(left.apply(t)).flatMap(result -> result ? Mono.just(true) : Mono.from(right.apply(t)));
}

default는 최초의 Predicate를 받아 delegate 패턴을 통해 predicate를 위임하는 기초 구현체이다.
negate, and, or는 다른 AsyncPredicate를 생성자로 받아 apply 시 각각의 로직을 publisher에 append하는 구현체이다.

// Simple Example
Predicate<String> isStartWithA = s -> s.startsWith("A");
AsyncPredicate.DefaultAsyncPredicate<String> predicate1 = new AsyncPredicate.DefaultAsyncPredicate<>(isStartWithA);

Predicate<String> isEndWithA = s -> s.endsWith("A");
AsyncPredicate.DefaultAsyncPredicate<String> predicate2 = new AsyncPredicate.DefaultAsyncPredicate<>(isEndWithA);

AsyncPredicate.OrAsyncPredicate<String> orPredicate = new AsyncPredicate.OrAsyncPredicate<>(predicate1, predicate2);

Flux.just("BBB", "ABB", "ABA")
    .flatMap(orPredicate)
    .doOnNext(System.out::println)
    .subscribe();

-> false, true, true

AsyncPredicate in Spring Cloud Gateway

// RouteDefinitionRouteLocator
private Route convertToRoute(RouteDefinition routeDefinition) {
	AsyncPredicate<ServerWebExchange> predicate = combinePredicates(routeDefinition);
	...
}

private AsyncPredicate<ServerWebExchange> combinePredicates(RouteDefinition routeDefinition) {
  ...
  AsyncPredicate<ServerWebExchange> predicate = lookup(routeDefinition, predicates.get(0));
  for (PredicateDefinition andPredicate : predicates.subList(1, predicates.size())) {
		AsyncPredicate<ServerWebExchange> found = lookup(routeDefinition, andPredicate);
		predicate = predicate.and(found);
  }
  return predicate;
}

// RoutePredicateHandlerMapping
protected Mono<Route> lookupRoute(ServerWebExchange exchange) {
	return this.routeLocator.getRoutes()
		.concatMap(route -> Mono.just(route).filterWhen(r -> {
			...
			return r.getPredicate().apply(exchange);
		})
		...
}

RouteDefinition: Library 사용자가 Route Rule에 대해 정의 할 수 있는 객체이다.
Spring Cloud Gateway는 사용자가 정의한 RouteDefinition에서 predicate들을 flat한 AsyncPredicate로 만든다.
이 후 RoutePredicateHandlerMapping 에서 predicate를 통해 route를 찾을 때 사용한다.

Spring Webflux, HttpHandler code 분석

북극곰은콜라 — Fri, 27 Oct 2023 18:29:08 +0900

개요

Spring Webflux가 http Request를 받아서 handler를 찾아 mapping, execute 및 response handle하는 과정에 대한 분석을 진행한다.

Spring Webflux HttpHandler 분석

HttpHandler

Http 요청에 대한 전반적인 처리를 담당하는 interface
AutoConfiguration으로 Bean으로 만들어지며, Builder를 통해 생성된다.
Builder는 생성된 Bean들을 기반으로 Handler를 생성한다.
따라서 HttpHandler Bean 생성 시점은 매우 늦다 (order = -2147483638)

생성 Flow 요약

1. AutoConfig를 통해 Builder를 생성 (with applicationContext)
2. Builder 내부에 webFliters, exceptionHandler, httpHandlerDecorator, sessionManager, codecConfigurer, contextResolver, forwardHeaderTransformer 할당 (load from bean)
a. HttpHandlerDecoratorFactory Bean을 통해서 httpHandlerDecorator를 load
b. Decorator 패턴으로 구현된 HttpHandlerDecorator를 Fuction으로 merge
3. Builder를 통해 HttpHandler Build
a. DispatcherHandler를 FilteringWebHandler에 delegate 할당
b. FilteringWebHandler를 ExceptionHandlingWebHandler에 delegate 할당
c. ExceptionHandlingWebHandler를 HttpWebHandlerAdapter에 delegate 할당
4. 기타 webflux 설정

동작 Flow 요약

1. ServerHttpRequest 수신
2. Exchange 생성
3. ExceptionHandler 추가 (onErrorResume)
a. 추가 후 다음 handler 호출
4. FilterHandler에서 filterChain으로 filter(exchange)
a. filter 후 다음 handler 호출
5. DispatcherHandler에서 exchange Handling
a. HandlerMapping을 통해 target handler 찾기
b. handler를 support하는 adapter를 통해 handler(exchange)
c. handle 결과에 대해서 처리 (rest응답, viewModel 등…)

// HttpHandlerAutoConfiguration
@AutoConfiguration(
  after = {WebFluxAutoConfiguration.class}
)
@ConditionalOnClass({DispatcherHandler.class, HttpHandler.class})
@ConditionalOnWebApplication(
  type = Type.REACTIVE
)
@ConditionalOnMissingBean({HttpHandler.class})
@AutoConfigureOrder(-2147483638)
public class HttpHandlerAutoConfiguration {
  ...

  @Bean
  public HttpHandler httpHandler(ObjectProvider<WebFluxProperties> propsProvider) {
    HttpHandler httpHandler = WebHttpHandlerBuilder.applicationContext(this.applicationContext).build();
    ...
  }

  ...
}

// WebHttpHandlerBuilder
// builder 생성 시점에 Bean들을 load하여, build 시점에 HttpHandler에 적용한다.

// applicationContext를 통한 생성
public static WebHttpHandlerBuilder applicationContext(ApplicationContext context) {
  // webHandler(Dispatcher) 기반 Builder 생성
  WebHttpHandlerBuilder builder = new WebHttpHandlerBuilder((WebHandler)context.getBean("webHandler", WebHandler.class), context);
  
  // WebFilter Bean 모두 가져와서 정렬 후 추가
  List<WebFilter> webFilters = context.getBeanProvider(WebFilter.class).orderedStream().toList();
  builder.filters((filters) -> {
    filters.addAll(webFilters);
  });
  
  // exceptionHandler들 로드해서 정렬 후 추가
  List<WebExceptionHandler> exceptionHandlers = context.getBeanProvider(WebExceptionHandler.class).orderedStream().toList();
  builder.exceptionHandlers((handlers) -> {
    handlers.addAll(exceptionHandlers);
  });
  
  // Decorator 모두 가져와서 정렬 후 추가
  Stream var10000 = context.getBeanProvider(HttpHandlerDecoratorFactory.class).orderedStream();
  Objects.requireNonNull(builder);
  var10000.forEach(builder::httpHandlerDecorator);

  // sessionManager 로드
  try {
    builder.sessionManager((WebSessionManager)context.getBean("webSessionManager", WebSessionManager.class));
  } catch (NoSuchBeanDefinitionException var8) {
  }

  // codecConfigurer 로드
  try {
    builder.codecConfigurer((ServerCodecConfigurer)context.getBean("serverCodecConfigurer", ServerCodecConfigurer.class));
  } catch (NoSuchBeanDefinitionException var7) {
  }

  // localeContextResolver 로드
  try {
    builder.localeContextResolver((LocaleContextResolver)context.getBean("localeContextResolver", LocaleContextResolver.class));
  } catch (NoSuchBeanDefinitionException var6) {
  }

  // forwardedHeaderTransformer 로드
  try {
    builder.forwardedHeaderTransformer((ForwardedHeaderTransformer)context.getBean("forwardedHeaderTransformer", ForwardedHeaderTransformer.class));
  } catch (NoSuchBeanDefinitionException var5) {
  }

  return builder;
}

// HttpHandler build
public HttpHandler build() {
  // webHandler Merge (DispathcerHandler + ExceptionHandlingWebHandler + FilteringWebHandler)
  WebHandler decorated = new FilteringWebHandler(this.webHandler, this.filters);
  WebHandler decorated = new ExceptionHandlingWebHandler(decorated, this.exceptionHandlers);
  HttpWebHandlerAdapter adapted = new HttpWebHandlerAdapter(decorated);
  if (this.sessionManager != null) {
    adapted.setSessionManager(this.sessionManager);
  }

  if (this.codecConfigurer != null) {
    adapted.setCodecConfigurer(this.codecConfigurer);
  }

  if (this.localeContextResolver != null) {
    adapted.setLocaleContextResolver(this.localeContextResolver);
  }

  if (this.forwardedHeaderTransformer != null) {
    adapted.setForwardedHeaderTransformer(this.forwardedHeaderTransformer);
  }

  if (this.applicationContext != null) {
    adapted.setApplicationContext(this.applicationContext);
  }

  adapted.afterPropertiesSet();
  return (HttpHandler)(this.httpHandlerDecorator != null ? (HttpHandler)this.httpHandlerDecorator.apply(adapted) : adapted);
}

HttpWebHandlerAdapter (implements HttpHandler)

Http Request 처리를 Decorate할 수 있는 Handler 구현체이다.
핵심 메서드는 interface의 handle 메서드와 createExchange가 있다.
1. request, response, filter 설정등을 바탕으로 exchange 생성
2. (let delegate) handle exchange
실제 exchange의 Handling 처리는 delegate를 통해 진행
default: ExceptionHandlingWebHandler → FilteringWebHandler → DispatcherHandler

createExchange(…)

protected ServerWebExchange createExchange(ServerHttpRequest request, ServerHttpResponse response) {
  return new DefaultServerWebExchange(request, response, this.sessionManager, this.getCodecConfigurer(), this.getLocaleContextResolver(), this.applicationContext);
}

ServerHttpRequest + 기타 handler들 → exchange 생성

handle(...)

public Mono<Void> handle(ServerHttpRequest request, ServerHttpResponse response) {
  if (this.forwardedHeaderTransformer != null) {
    try {
      request = this.forwardedHeaderTransformer.apply(request);
    } catch (Throwable var4) {
      ...
    }
  }

  ServerWebExchange exchange = this.createExchange(request, response);
  ...
  Mono var10000 = this.getDelegate().handle(exchange).doOnSuccess((aVoid) -> {
    this.logResponse(exchange);
  })
  ...
  return var10000.then(Mono.defer(response::setComplete));
}

1. request의 Header 처리 (Transformer)
2. exchange 생성
3. reqeust logging
4. delegate (Decorator)를 통한 exchange handle
5. success / fail 처리 (response logging, etc)
6. response complete

ExceptionHandlingWebHandler

delegate handle에서 발생한 error 시그날을
onErrorResume으로 load 된 WebExceptionHandler 처리한다.

FilteringWebHandler

private final DefaultWebFilterChain chain;

public Mono<Void> handle(ServerWebExchange exchange) {
  return this.chain.filter(exchange);
}

FilterChain으로 exchange를 filter
filter 후 delegate(DispatcherHandler)로 handle() 넘김

DispatcherHandler

// DispathcerHandler
public Mono<Void> handle(ServerWebExchange exchange) {
  if (this.handlerMappings == null) {
    return this.createNotFoundError();
  } else {
    return CorsUtils.isPreFlightRequest(exchange.getRequest()) ? this.handlePreFlight(exchange) : Flux.fromIterable(this.handlerMappings).concatMap((mapping) -> {
      return mapping.getHandler(exchange);
    })
    .next()
    ...
    }).flatMap((handler) -> {
      return this.handleRequestWith(exchange, handler);
    });
  }
}

private Mono<Void> handleRequestWith(ServerWebExchange exchange, Object handler) {
  if (ObjectUtils.nullSafeEquals(exchange.getResponse().getStatusCode(), HttpStatus.FORBIDDEN)) {
    return Mono.empty();
  } else {
    if (this.handlerAdapters != null) {
      Iterator var3 = this.handlerAdapters.iterator();

      while(var3.hasNext()) {
        HandlerAdapter adapter = (HandlerAdapter)var3.next();
        if (adapter.supports(handler)) {
          return adapter.handle(exchange, handler).flatMap((result) -> {
            return this.handleResult(exchange, result);
          });
        }
      }
    }

    return Mono.error(new IllegalStateException("No HandlerAdapter: " + handler));
  }
}

1. HandlerMapping을 통해 Handler를 찾아온다.
- 없으면 404
2. 현재 handler를 support 하는 HandlerAdapter를 찾아와서 handle()
3. handlerAdapter는 @RequestMapping, RouterFunction등으로 만들어진 Bean
4. Adapter는 각 Handler의 handle()을 호출
- exchange → 각 handle()의 파라미터로
5. Adapter는 handler의 return 값을 HandlerResult에 담아서 return
6. resultHandler들 중에서 support하는 resultHandler를 찾아서 handlerResult

Webflux HttpHandler 구현 아이디어

목표 (추정)

1. 여러 하위 로직을 합쳐서 하나의 handling 로직을 만들고 싶다
2. handling 로직을 확장성 있게 가져가고 싶다. (기존 로직에 추가하거나, 다음 단계로 놓거나..)

아이디어

1. Decorator 패턴을 이용해서 특정 로직에 기능을 추가할 수 있는 구조를 갖는다.
2. Delegate 패턴을 이용해서 외부에서 위임 클래스 로직을 호출할 수 있게한다.
3. Adapter 패턴을 통해 decorate된 클래스를 최종 클래스에서 사용한다.
// 이 부분은 다른 프로젝트에서 만든 httpHandler에 WebHandler를 붙이기 위함

코드 분석

public interface HttpHandler {
  Mono<Void> handle(ServerHttpRequest request, ServerHttpResponse response);
}

public interface WebHandler {
  Mono<Void> handle(ServerWebExchange exchange);
}

조합 및 확장이 필요한 기능
- 여러 HttpHandler 모듈에서 exchange를 받아서 req 처리 → res 처리

Decorator 패턴 적용

public HttpHandler build() {
  WebHandler decorated = new FilteringWebHandler(this.webHandler, this.filters);
  WebHandler decorated = new ExceptionHandlingWebHandler(decorated, this.exceptionHandlers);
  ...
}

확장이 필요한 기능은 WebHandlerDecorator를 확장하여 handle() 메서드를 구현한다.
Concrete는 DispatcherHandler에 해당되며, ExceptionHandlingWebHandler, FilteringWebHandler 등은 decorate class에 해당된다.

Delegate 패턴 적용

// httpHandler에서 ExceptionHandler 호출
@Override
public Mono<Void> handle(ServerHttpRequest request, ServerHttpResponse response) {
	...
	return getDelegate().handle(exchange)
			.doOnSuccess(aVoid -> logResponse(exchange))
			.onErrorResume(ex -> handleUnresolvedError(exchange, ex))
			.then(Mono.defer(response::setComplete));
}

// ExceptionHandler에서 super(Decorator)를 통해 FilteringHandler 호출
@Override
public Mono<Void> handle(ServerWebExchange exchange) {
    ...
	completion = super.handle(exchange);
	...
}
@Override
public Mono<Void> handle(ServerWebExchange exchange) {
	return this.delegate.handle(exchange);
}

// FilteringHandler에서 DefaultWebFilterChain을 통해 DispatcherHandler 호출
@Override
public Mono<Void> handle(ServerWebExchange exchange) {
	return this.chain.filter(exchange);
}
@Override
public Mono<Void> filter(ServerWebExchange exchange) {
	return Mono.defer(() ->
			this.currentFilter != null && this.chain != null ?
					invokeFilter(this.currentFilter, this.chain, exchange) :
					this.handler.handle(exchange));
}

Decorator class에 delegate가 있다.
앞쪽 클래스에서 자신의 로직 처리 후 delegate를 통해 다음 webHandler 처리를 위임한다.

Adapter를 통한 WebHandler를 HttpHandler에 적용

WebHandler + HttpHandler

Conclusion

<HttpHandler>
HttpHandler는 Http Request를 처리하는 목적으로 만든 인터페이스이다.
Spring Webflux는 httpHandler를 통해서 http request를 handling한다.
HttpHandler를 확장하여 구현하면, 기본 제공하는 handler를 교체할 수 있다.

<WebHandler>
WebHandler는 web에서의 request 처리를 주 목적으로 만든 인터페이스이다.
WebHandler를 구현한 핵심 클래스는 DispatcherHandler 이다.
DispatcherHandler는 request dispatcher에 대한 기능을 구현했다.

<HttpHander + WebHandler>
두 인터페이스를 Adapter 패턴으로 합쳤다.
HttpHandler에서 WebHandler의 인터페이스를 호출한다.

<WebHandler 동작 구조>
기본적으로 DispatcherHandler를 호출하게 되며
dispatch 이외의 기능은 decorator 패턴과 delegate 패턴으로 확장했다.
decorator 클래스에서 delegate로 dispatcher 또는 다른 decorator들을 가지고 있으며, delegate 호출 전 후로 기타 로직들을 넣었다.
위의 Adapter또한 decorator로 다른 decorator를 delegate로 가지고 있다가 호출한다.

<기본 flow>
WehHandlerAdapter -> ExcpetionHandlingWebHandler -> FilteringWebHandler -> DispatcherHandler

Decorator, Delegate 패턴으로 기능의 확장을 확인할 수 있었다.
http handle 과정에서 추가로직을 확장하기 쉬운 구조이다.

Spring Cloud Sleuth란 - 분산 Tracing

북극곰은콜라 — Mon, 11 Sep 2023 17:57:21 +0900

Spring Cloud Sleuth란

Spring Cloud의 분산 트레이싱 솔루션으로 개발 오픈소스

Trace And Span

name	desc
Trace	전체 작업을 하나로 묶는 것 작업 당 64-bit ID 하나를 가진다.
Span	분산 시스템에서 세부 작업, 다른 서비스, 다른 머신 또는 다른 쓰레드 등으로 나누어 질 수 있다. 각각 64-bit ID를 가진다. 최초의 Span은 traceId와 동일하며, root span으로 불린다.

분산 시스템의 한 작업의 예이다.
전체 작업을 하나의 Trace로 묶고, 세부 작업을 Span으로 표현한다.
이를 통해 전체 프로세스를 한번에 tracing 할 수 있으며, 세부적인 작업에 대한 부분도 확인 가능하다.

전체 작업을 Span을 기준으로 tree 구조화 할 수 있다.
이는 span을 기준으로 flow를 추적하기 좋은 구조이다.

Log Sample

service1.log:2016-02-26 11:15:47.561  INFO [service1,2485ec27856c56f4,2485ec27856c56f4,true] 68058 --- [nio-8081-exec-1] i.s.c.sleuth.docs.service1.Application   : Hello from service1. Calling service2
service2.log:2016-02-26 11:15:47.710  INFO [service2,2485ec27856c56f4,9aa10ee6fbde75fa,true] 68059 --- [nio-8082-exec-1] i.s.c.sleuth.docs.service2.Application   : Hello from service2. Calling service3 and then service4
service3.log:2016-02-26 11:15:47.895  INFO [service3,2485ec27856c56f4,1210be13194bfe5,true] 68060 --- [nio-8083-exec-1] i.s.c.sleuth.docs.service3.Application   : Hello from service3
service2.log:2016-02-26 11:15:47.924  INFO [service2,2485ec27856c56f4,9aa10ee6fbde75fa,true] 68059 --- [nio-8082-exec-1] i.s.c.sleuth.docs.service2.Application   : Got response from service3 [Hello from service3]
service4.log:2016-02-26 11:15:48.134  INFO [service4,2485ec27856c56f4,1b1845262ffba49d,true] 68061 --- [nio-8084-exec-1] i.s.c.sleuth.docs.service4.Application   : Hello from service4
service2.log:2016-02-26 11:15:48.156  INFO [service2,2485ec27856c56f4,9aa10ee6fbde75fa,true] 68059 --- [nio-8082-exec-1] i.s.c.sleuth.docs.service2.Application   : Got response from service4 [Hello from service4]
service1.log:2016-02-26 11:15:48.182  INFO [service1,2485ec27856c56f4,2485ec27856c56f4,true] 68058 --- [nio-8081-exec-1] i.s.c.sleuth.docs.service1.Application   : Got response from service2 [Hello from service2, response from service3 [Hello from service3] and from service4 [Hello from service4]]

Trace Visualize

ZipKin

각 서비스에서 소요된 시간 및 호출정보를 한번에 파악할 수 있다.

에러에 대한 부분도 한번에 파악할 수 있다.

Kibana with logstash

Logstash를 통해 collect된 정보를 기반으로 kibana연동

동작 원리

Spring Cloud Sleuth는 2.0.0버전부터 Brave 라이브러리를 도입했다.
따라서 Tracing 및 ZipKin 통합 관련 동작은 Brave가 담당한다.
Sleuth에서 Brave 라이브러리를 활용하여, MDC에 특정 key로 trace정보를 propagation한다.
그 외 각 instrument 라이브러리에서 brave를 통해 관리되는 trace정보를 propagation할 tracing 객체들을 구현해 놓았다.

기본 동작 (Brave)

// Tracer(brave) 생성
new Tracer(...)

// Span 생성
tracer.newTrace().name("xxx").start(); // 인스턴스 span
tracer.startScopedSpan("xxx"); // Threadlocal 기반 span

// 다음 span 생성
tracer.nextSpan();

// propagation (to other system)
tracing.propagation()
  .injector(Request::addHeader)
  .inject(span.context(), request);

// span 종료
span.finish();;

Tracer (Sleuth)

Spring Cloud Sleuth에서 Tracing을 위해 사용하는 핵심 Interface
Bean으로 만들어 다른 component들과 Integration한다.
Sleuth에서 구현체로 BraveTracer를 기본적으로 사용하며, bridge 패턴으로 구성되어 있다.
(내부적으로 brave 라이브러리의 Tracer를 가지고 Sleuth의 기능을 구현했다.)

Tracer (Brave)

Brave에서 구현한 Tracer의 실제 동작을 담당하는 클래스
newSpan, nextSpan, newTraceContext, newChild 등 Tracing에 필요한 객체를 생성하고 관리할 수 있다.

Propagation (brave)

brave에서 정의한 trace propagation을 위한 interface
일반적으로 Span을 다른 Object에 넘기기 위한 Injector와 다른 Object에서 Span을 추출하기 위한 Extractor interface와 함께 구현된다.

Propagation의 구현체들

// B3 Propagation

분산 시스템 환경에서, 시스템 간 Tracing을 위한 스펙이 별도로 필요하다.
B3 Propagation은 Tracing Propagation의 스펙 중 하나이며, 많은 Tracing system과 호환이 된다.
주로 header에 키로 “X-B3-” 로 시작한다.

Name	Mandatory(O / X)	Desc
traceId	O	64 또는 128 bit의 traceId
spanId	O	64 bit의 spanId
parentSpanId	X	현재 spanId의 parent 일반적으로 parent가 없는 경우 (traceId == spanId) 생략한다.
SamplelingState	X	현재 수신한 propagation을 Tracing System (ex. zipkin)에게 전파 할 지에 대한 Flag 값이다. · Defer: 수신 시스템이 알아서 판단 · Deny: 전파 X · Accept: 가능하면 전파 O · Debug: Debug모드로 전파

Propagation 방식

Multiple Headers

// http header
x-b3-traceid:"88666bfe25af4d12", 
x-b3-spanid:"67ba768f6754994f",
x-b3-parentspanid:"88666bfe25af4d12", 
x-b3-sampled:"0"

Http header 같이 여러 값을 헤더에 넣기 좋은 경우 사용
위 attributes 중 해당되는 값을 넣는다.
// 위 예제의 smapled 0는 deny를 의미한다.

Single Header

// kafka header
b3: 3bce497d9c6833a4-e4efb90513184e29-0

b3={TraceId}-{SpanId}-{SamplingState}-{ParentSpanId}
형식으로 전달한다.

ParentSpanId를 전파하는 이유

Tracing System에서 Tree 구조를 만들기 위해서 사용한다.
Tracing System으로 전파된 정보의 위치를 결정하기 위함

기술 검증

1. Thread Switching에 따른 Tracing 동작 확인
2. Rest 서버 간 Tracing 동작 확인 (WebClient)
3. Kafka Publish, Subscribe의 동작 확인
4. Rsocket Server / client 동작 확인

환경

JDK 11
Spring boot 2.7.0
Sring cloud Sleuth 3.1.9
Spring webflux
Spring data r2dbc
reactor-kafka 1.2.7.RELEASE

1. Webflux (Reactor Netty) Tracing

기본 Tracing 동작 확인
Reactor의 Thread 변경에 따른 Tracing 확인

시나리오

1. Http Request
2. R2DBC MariaDB Query
3. Http Response

log

2023-09-04 16:57:45.216  INFO [sleuthTest,20dc9c663477eddc,20dc9c663477eddc] 24344 --- [ctor-http-nio-4] c.e.l.sample.webflux.TraceHandler        : traceService() start
2023-09-04 16:57:45.440  INFO [sleuthTest,20dc9c663477eddc,20dc9c663477eddc] 24344 --- [actor-tcp-nio-2] c.e.l.sample.r2dbc.R2dbcService          : r2dbcSelectCall()
2023-09-04 16:57:45.444  INFO [sleuthTest,20dc9c663477eddc,20dc9c663477eddc] 24344 --- [actor-tcp-nio-2] c.e.l.sample.webflux.TraceHandler        : traceService() end

2. Rest Servers Tracing

Http 서버 간 Tracing 동작 확인
WebClient TraceId, SpanId 등 Header injection 동작 확인
Create SpanId 동작 확인

시나리오

1. 사용자 → 서버1 REST 요청
2. 서버1 → 서버2 REST 요청 (WebClient)
3. 서버2 → 서버1 응답
4. 서버1 → 사용자 응답

log

// 서버1 (before Request)
2023-09-04 17:20:04.372  INFO [sleuthTest,f988661d4e75a625,f988661d4e75a625] 17692 --- [ctor-http-nio-4] c.e.l.sample.webflux.TraceHandler        : traceService() start

// 서버2
2023-09-04 17:20:04.494  INFO [,f988661d4e75a625,e72c2850246440e5] 18248 --- [ctor-http-nio-3] c.e.r.TestRestController                 : GET /test start
2023-09-04 17:20:04.495  INFO [,f988661d4e75a625,e72c2850246440e5] 18248 --- [ctor-http-nio-3] c.e.r.TestRestController                 : accept-encoding : gzip
2023-09-04 17:20:04.495  INFO [,f988661d4e75a625,e72c2850246440e5] 18248 --- [ctor-http-nio-3] c.e.r.TestRestController                 : user-agent : ReactorNetty/1.0.19
2023-09-04 17:20:04.495  INFO [,f988661d4e75a625,e72c2850246440e5] 18248 --- [ctor-http-nio-3] c.e.r.TestRestController                 : host : localhost:8080
2023-09-04 17:20:04.495  INFO [,f988661d4e75a625,e72c2850246440e5] 18248 --- [ctor-http-nio-3] c.e.r.TestRestController                 : accept : */*
2023-09-04 17:20:04.495  INFO [,f988661d4e75a625,e72c2850246440e5] 18248 --- [ctor-http-nio-3] c.e.r.TestRestController                 : X-B3-TraceId : f988661d4e75a625
2023-09-04 17:20:04.495  INFO [,f988661d4e75a625,e72c2850246440e5] 18248 --- [ctor-http-nio-3] c.e.r.TestRestController                 : X-B3-SpanId : e72c2850246440e5
2023-09-04 17:20:04.495  INFO [,f988661d4e75a625,e72c2850246440e5] 18248 --- [ctor-http-nio-3] c.e.r.TestRestController                 : X-B3-ParentSpanId : f988661d4e75a625
2023-09-04 17:20:04.495  INFO [,f988661d4e75a625,e72c2850246440e5] 18248 --- [ctor-http-nio-3] c.e.r.TestRestController                 : X-B3-Sampled : 0

// 서버1 (after Request)
2023-09-04 17:20:04.552  INFO [sleuthTest,f988661d4e75a625,f988661d4e75a625] 17692 --- [ctor-http-nio-4] c.e.l.sample.webClient.WebClientService  : qweasd
2023-09-04 17:20:04.554  INFO [sleuthTest,f988661d4e75a625,f988661d4e75a625] 17692 --- [ctor-http-nio-4] c.e.l.sample.webflux.TraceHandler        : traceService() end

3. Kafka Pub / Sub Tracing

Kafka Producer의 header injection 확인
Kafka Consumer의 message header로 부터 traceId 연계 확인

시나리오

1. REST 요청
2. Topic Messsage Produce
3. Consume Topic Message

log

// REST 요청 받음
2023-09-04 17:33:53.615  INFO [sleuthTest,3bce497d9c6833a4,3bce497d9c6833a4] 7340 --- [ctor-http-nio-4] c.e.l.sample.webflux.TraceHandler        : traceService() start

// init Producer
2023-09-04 17:33:53.626  INFO [sleuthTest,3bce497d9c6833a4,3bce497d9c6833a4] 7340 --- [ctor-http-nio-4] o.a.k.clients.producer.ProducerConfig    : ProducerConfig values: 
	acks = -1
	batch.size = 16384
	...
2023-09-04 17:33:53.632  INFO [sleuthTest,3bce497d9c6833a4,3bce497d9c6833a4] 7340 --- [ctor-http-nio-4] o.a.k.clients.producer.KafkaProducer     : [Producer clientId=producer-1] Instantiated an idempotent producer.
2023-09-04 17:33:53.643  INFO [sleuthTest,3bce497d9c6833a4,3bce497d9c6833a4] 7340 --- [ctor-http-nio-4] o.a.kafka.common.utils.AppInfoParser     : Kafka version: 3.1.1

// produce start
2023-09-04 17:33:53.644  INFO [sleuthTest,3bce497d9c6833a4,3bce497d9c6833a4] 7340 --- [ctor-http-nio-4] o.a.kafka.common.utils.AppInfoParser     : Kafka commitId: 97671528ba54a138
2023-09-04 17:33:53.644  INFO [sleuthTest,3bce497d9c6833a4,3bce497d9c6833a4] 7340 --- [ctor-http-nio-4] o.a.kafka.common.utils.AppInfoParser     : Kafka startTimeMs: 1693816433643
...
2023-09-04 17:33:53.687  INFO [sleuthTest,3bce497d9c6833a4,3bce497d9c6833a4] 7340 --- [       single-1] c.e.l.sample.kafka.KafkaService          : response: cm: 1, rm: chchoi.test.1-0@53
2023-09-04 17:33:53.687  INFO [sleuthTest,3bce497d9c6833a4,3bce497d9c6833a4] 7340 --- [       single-1] c.e.l.sample.kafka.KafkaService          : response: cm: 2, rm: chchoi.test.1-0@54
2023-09-04 17:33:53.687  INFO [sleuthTest,3bce497d9c6833a4,3bce497d9c6833a4] 7340 --- [       single-1] c.e.l.sample.kafka.KafkaService          : response: cm: 3, rm: chchoi.test.1-0@55
// produce end

// consume start
2023-09-04 17:33:53.746  INFO [sleuthTest,3bce497d9c6833a4,2f0175bf3ca03167] 7340 --- [     parallel-3] c.e.l.sample.kafka.ReadyListener         : next....
2023-09-04 17:33:53.746  INFO [sleuthTest,3bce497d9c6833a4,2f0175bf3ca03167] 7340 --- [     parallel-3] c.e.l.sample.kafka.ReadyListener         : topic: chchoi.test.1, key: null, value: 1-9ccf744f-052e-497b-bf92-556d8a501768
2023-09-04 17:33:53.746  INFO [sleuthTest,3bce497d9c6833a4,7435a497d71b90ab] 7340 --- [     parallel-3] c.e.l.sample.kafka.ReadyListener         : next....
2023-09-04 17:33:53.746  INFO [sleuthTest,3bce497d9c6833a4,7435a497d71b90ab] 7340 --- [     parallel-3] c.e.l.sample.kafka.ReadyListener         : topic: chchoi.test.1, key: null, value: 2-6c5ecc32-12d9-416b-8df3-79a6a892e411
2023-09-04 17:33:53.747  INFO [sleuthTest,3bce497d9c6833a4,ca941de8f65d2d36] 7340 --- [     parallel-3] c.e.l.sample.kafka.ReadyListener         : next....
2023-09-04 17:33:53.747  INFO [sleuthTest,3bce497d9c6833a4,ca941de8f65d2d36] 7340 --- [     parallel-3] c.e.l.sample.kafka.ReadyListener         : topic: chchoi.test.1, key: null, value: 3-72b7d2fc-5baf-4897-a65c-4748465706da
// consume end

// rest end
2023-09-04 17:33:53.747  INFO [sleuthTest,3bce497d9c6833a4,3bce497d9c6833a4] 7340 --- [       single-1] c.e.l.sample.webflux.TraceHandler        : traceService() end

4. RSocket Server / Client Tracing

RSocket Server의 요청 받을 때 Tracing 동작 확인
RSocket Client의 요청할 때 traceId관련 injection 확인

시나리오

1. REST 요청
2. 서버1 → 서버2 RSocket 요청
3. RSocket 응답
4. REST 응답

log

// 서버1
2023-09-04 17:45:46.148  INFO [sleuthTest,95ab4dfd5ea0968b,95ab4dfd5ea0968b] 7340 --- [ctor-http-nio-4] c.e.l.sample.webflux.TraceHandler        : traceService() start
2023-09-04 17:45:46.154  INFO [sleuthTest,95ab4dfd5ea0968b,95ab4dfd5ea0968b] 7340 --- [ctor-http-nio-4] c.e.l.sample.rsocket.RSocketService      : traceRSocket() start
2023-09-04 17:45:46.253 DEBUG [sleuthTest,95ab4dfd5ea0968b,95ab4dfd5ea0968b] 7340 --- [actor-tcp-nio-3] io.rsocket.FrameLogger                   : sending -> 
Frame => Stream ID: 0 Type: SETUP Flags: 0b0 Length: 75
Data:

2023-09-04 17:45:46.280 DEBUG [sleuthTest,95ab4dfd5ea0968b,95ab4dfd5ea0968b] 7340 --- [actor-tcp-nio-3] io.rsocket.FrameLogger                   : sending -> 
Frame => Stream ID: 1 Type: REQUEST_RESPONSE Flags: 0b100000000 Length: 95
Metadata:
         +-------------------------------------------------+
         |  0  1  2  3  4  5  6  7  8  9  a  b  c  d  e  f |
+--------+-------------------------------------------------+----------------+
|00000000| fe 00 00 06 05 2f 74 65 73 74 fd 00 00 19 94 95 |...../test......|
|00000010| ab 4d fd 5e a0 96 8b 1f 0e e7 1a 2e 31 9c ce 95 |.M.^........1...|
|00000020| ab 4d fd 5e a0 96 8b 01 62 33 00 00 23 39 35 61 |.M.^....b3..#95a|
|00000030| 62 34 64 66 64 35 65 61 30 39 36 38 62 2d 31 66 |b4dfd5ea0968b-1f|
|00000040| 30 65 65 37 31 61 32 65 33 31 39 63 63 65 2d 30 |0ee71a2e319cce-0|
+--------+-------------------------------------------------+----------------+
Data:
         +-------------------------------------------------+
         |  0  1  2  3  4  5  6  7  8  9  a  b  c  d  e  f |
+--------+-------------------------------------------------+----------------+
|00000000| 71 77 65 61 73 64                               |qweasd          |
+--------+-------------------------------------------------+----------------+
2023-09-04 17:45:46.396 DEBUG [sleuthTest,95ab4dfd5ea0968b,95ab4dfd5ea0968b] 7340 --- [actor-tcp-nio-3] io.rsocket.FrameLogger                   : receiving -> 
Frame => Stream ID: 1 Type: NEXT_COMPLETE Flags: 0b1100000 Length: 30
Data:
         +-------------------------------------------------+
         |  0  1  2  3  4  5  6  7  8  9  a  b  c  d  e  f |
+--------+-------------------------------------------------+----------------+
|00000000| 7b 22 61 22 3a 22 74 65 73 74 52 65 73 70 6f 6e |{"a":"testRespon|
|00000010| 73 65 44 61 74 61 22 7d                         |seData"}        |
+--------+-------------------------------------------------+----------------+
2023-09-04 17:45:46.404  INFO [sleuthTest,95ab4dfd5ea0968b,95ab4dfd5ea0968b] 7340 --- [actor-tcp-nio-3] c.e.l.sample.rsocket.RSocketService      : receiveFromRSocket: testResponseData
2023-09-04 17:45:46.404  INFO [sleuthTest,95ab4dfd5ea0968b,95ab4dfd5ea0968b] 7340 --- [actor-tcp-nio-3] c.e.l.sample.webflux.TraceHandler        : traceService() end



// 서버2
2023-09-04 17:45:46.288 DEBUG [,,] 18248 --- [ctor-http-nio-4] io.rsocket.FrameLogger                   : receiving -> 
Frame => Stream ID: 0 Type: SETUP Flags: 0b0 Length: 75
Data:

2023-09-04 17:45:46.315 DEBUG [,,] 18248 --- [ctor-http-nio-4] io.rsocket.FrameLogger                   : receiving -> 
Frame => Stream ID: 1 Type: REQUEST_RESPONSE Flags: 0b100000000 Length: 95
Metadata:
         +-------------------------------------------------+
         |  0  1  2  3  4  5  6  7  8  9  a  b  c  d  e  f |
+--------+-------------------------------------------------+----------------+
|00000000| fe 00 00 06 05 2f 74 65 73 74 fd 00 00 19 94 95 |...../test......|
|00000010| ab 4d fd 5e a0 96 8b 1f 0e e7 1a 2e 31 9c ce 95 |.M.^........1...|
|00000020| ab 4d fd 5e a0 96 8b 01 62 33 00 00 23 39 35 61 |.M.^....b3..#95a|
|00000030| 62 34 64 66 64 35 65 61 30 39 36 38 62 2d 31 66 |b4dfd5ea0968b-1f|
|00000040| 30 65 65 37 31 61 32 65 33 31 39 63 63 65 2d 30 |0ee71a2e319cce-0|
+--------+-------------------------------------------------+----------------+
Data:
         +-------------------------------------------------+
         |  0  1  2  3  4  5  6  7  8  9  a  b  c  d  e  f |
+--------+-------------------------------------------------+----------------+
|00000000| 71 77 65 61 73 64                               |qweasd          |
+--------+-------------------------------------------------+----------------+
2023-09-04 17:45:46.387 DEBUG [,95ab4dfd5ea0968b,acab5cb6dc4c8625] 18248 --- [ctor-http-nio-4] io.rsocket.FrameLogger                   : sending -> 
Frame => Stream ID: 1 Type: NEXT_COMPLETE Flags: 0b1100000 Length: 30
Data:
         +-------------------------------------------------+
         |  0  1  2  3  4  5  6  7  8  9  a  b  c  d  e  f |
+--------+-------------------------------------------------+----------------+
|00000000| 7b 22 61 22 3a 22 74 65 73 74 52 65 73 70 6f 6e |{"a":"testRespon|
|00000010| 73 65 44 61 74 61 22 7d                         |seData"}        |
+--------+-------------------------------------------------+----------------+

Conclusion

간편하게 tracing 관련 연계를 구성할 수 있다.
설정이 조금 까다롭지만, 스펙도 명확하고, 역할도 명확해서 도입에 문제가 없을 것으로 판단된다.
error 처리 및 tracing의 시각화는 더 조사해 보아야 한다.

REFERENCE

docs
https://docs.spring.io/spring-cloud-sleuth/docs/2.2.9.BUILD-SNAPSHOT/reference/html/#introduction
https://docs.spring.io/spring-cloud-sleuth/docs/current-SNAPSHOT/reference/html/integrations.html
https://docs.spring.io/spring-cloud-sleuth/docs/2.2.9.BUILD-SNAPSHOT/reference/html/appendix.html

netty example
https://github.com/btkelly/Sleuth-Netty-Example/blob/master/build.gradle
producer example
https://github.com/spring-cloud-samples/spring-cloud-sleuth-samples/tree/main/kafka-reactive-producer
consumer example
https://github.com/spring-cloud-samples/spring-cloud-sleuth-samples/tree/main/kafka-reactive-consumer
rsocket
https://github.com/rsocket/rsocket/blob/master/Extensions/WellKnownMimeTypes.md
org.springframework.cloud.sleuth.instrument.rsocket.TracingRSocketConnectorConfigurer
https://micrometer.io/docs/tracing

#2 Session Connector Server 구현

북극곰은콜라 — Thu, 3 Aug 2023 18:00:29 +0900

개요

FlagWar 관련 개발을 한동안 바빠서 소흘했었네요...
이제 슬슬 다시 재개하려 합니다.
이번 구현한 사항은 client와 session을 유지하며, 메시지를 보낼 client를 찾아서 서버 push를 보낼 수 있는 서버입니다.
EX) A, B가 X라는 reference로 서버와 session을 유지하고 있을 때, X로 향하는 메시지가 A, B 모두에게 전달될 수 있어야 함

요구사항 요약

1. 서버는 Client와의 Session을 유지할 수 있어야 한다.
2. 서버에 연결된 Client는 자신을 식별할 수 있는 TAG 정보를 서버에 저장 및 삭제할 수 있어야 한다.
3. 서버는 메시지를 수신하여 TAG 기반으로 Client에게 메시지를 전달 할 수 있어야 한다.
4. 서버는 Scale-out이 용이한 구조를 가진다.

설계

Infra Structure

기본적으로 Server <-> Client는 Nginx를 통해 연결된다.
세션 및 서버 PUSH를 위한 프로토콜은 Websocket을 사용한다.
Client가 Message를 받을 TAG CRUD는 REST, Websocket Message를 사용한다.
Server는 Kafka에서 Message 관련 Topic을 구독한다.
Message 전파를 위해서, Tag를 포함한 Message를 해당 Topic에 Publish 한다.

Kafka를 사용한 이유는 Scale-out에 용이한 구조를 가지기 위함이며, 모든 message 전달은 kafka를 통해서 전달하여 session server는 자신의 session에 해당되는 Tag를 기반으로 메시지를 전달한다.
// kafka 관련 인프라가 이미 구축되어 있기에 다른 메시지 큐 도입은 안하기로 결정

구현

- Kotlin 기반
- Spring Webflux
- Spring Websocket
- Reactor-Kafka

SessionManager: Session을 관리하는 클래스, websocket session을 wrapping한 객체를 가지고 있으며, 해당 객체는 websocket session 외 referenceTag 등을 추가로 가진다.
WebsocketConifig는 StringWebsocketHandler를 등록하며, 해당 handler에서 세션처리 및 메시지 처리를 한다.
SessionController는 REST 인터페이스를 제공
KafkaConsumeManager는 특정 Topic을 Consume 하며, SessionManager를 통해 websocket session에 message를 전달한다.

Session 기능 (Websocket)

@Configuration
@EnableWebSocket
class WebsocketConfig(val stringWebsocketHandler: StringWebsocketHandler): WebSocketConfigurer {
    override fun registerWebSocketHandlers(registry: WebSocketHandlerRegistry) {
        registry
            .addHandler(stringWebsocketHandler, "/connect").setAllowedOrigins("*")
    }
}

Websocket Enable 및 handler, resource 설정
CORS를 위한 origin 설정

override fun afterConnectionEstablished(session: WebSocketSession) {
    val sessionWrapper = SessionWrapper(id = session.id, webSocketSession = session)
    session.uri?.rawQuery?.let { addReferenceTags(it, sessionWrapper) }
    this.sessionManager.addSession(sessionWrapper)
}

override fun afterConnectionClosed(session: WebSocketSession, status: CloseStatus) {
    this.sessionManager.removeSession(session.id)
}

Websocket connection 연결/끊기 관련 코드
establish시 메모리 상 session을 추가
close 시 session 제거

class SessionWrapper(
    val id: String,
    var referenceTagSet: MutableSet<String> = HashSet(),
    val timestamp: Long = Date().time,
    @JsonIgnore
    val webSocketSession: WebSocketSession
)

메모리상의 Session Wrapper 객체
고유 id를 가지며, referenceTag를 Set으로 가지고 있는다.
referenceTag는 중복없는 단순 String 값이다.

Reference 관련 기능

fun addReferenceTag(sessionId: String, referenceTag: String) =
        this.sessionMap[sessionId]?.referenceTagSet?.add(referenceTag)

fun removeReferenceTag(sessionId: String, referenceTag: String) =
    this.sessionMap[sessionId]?.referenceTagSet?.remove(referenceTag)

Reference를 추가/제거하는 메서드
websocket message handle 및 REST Controller에서 호출된다.

SendMessage 기능

fun sendMessage(referenceTags: Set<String>, message: String) {
    val failList = this.getSessionsByReferenceTags(referenceTags)
        .map {
            log.info("send message, id: ${it.id}")
            try {
                it.webSocketSession.sendMessage(TextMessage(message))
                null
            } catch (e: Exception) {
                it
            }
        }
        .filterNotNull()
        .toList()
    failList.forEach { this.removeSession(it.id) }
}

fun getSessionsByReferenceTags(target: Set<String>): Set<SessionWrapper> {
    return this.sessionMap.entries
        .map { it.value }
        .filter { target.intersect(it.referenceTagSet).isNotEmpty() }
        .toSet()
}

message를 전달할 대상은 referenceTag를 기반으로 하며
메모리상의 session들에게서 referenceTag가 매칭되는 객체를 찾아서, websocket session에 메시지를 보낸다.
sendMessage에 실패하는 경우, 비활성화된 세션으로 간주하여, session에서 remove하고, close 처리를 한다.

Consume Kafka Topic

@PostConstruct
fun init() {
    val consumerConfig = HashMap<String, Any>();
    consumerConfig[ConsumerConfig.BOOTSTRAP_SERVERS_CONFIG] = bootstrapServer
    consumerConfig[ConsumerConfig.GROUP_ID_CONFIG] = UUID.randomUUID().toString()
    consumerConfig[ConsumerConfig.KEY_DESERIALIZER_CLASS_CONFIG] = StringDeserializer::class.java
    consumerConfig[ConsumerConfig.VALUE_DESERIALIZER_CLASS_CONFIG] = StringDeserializer::class.java
    consumerConfig[ConsumerConfig.AUTO_OFFSET_RESET_CONFIG] =
        OffsetResetStrategy.LATEST.name.lowercase(Locale.getDefault())
    consumerConfig[ConsumerConfig.MAX_POLL_RECORDS_CONFIG] = 10

    this.receiverOptions = ReceiverOptions.create(consumerConfig)
    this.connectorMessageReceiver = KafkaReceiver
        .create(
            this.receiverOptions
                .commitInterval(Duration.of(10, ChronoUnit.MILLIS))
                .commitBatchSize(1)
                .subscription(listOf("connector.message"))
        )

    this.consumeConnectorMessage()
}

fun consumeConnectorMessage() {
    this.connectorMessageReceiver
        .receiveAutoAck()
        .concatMap { it }
        .onErrorContinue { t, _ -> t.printStackTrace() }
        .subscribe { record ->
            try {
                val commonConnectorMessage = this.gson.fromJson(record.value(), CommonConnectorMessage::class.java)
                this.sessionManager.sendMessage(
                    commonConnectorMessage.referenceTags.toSet(),
                    this.gson.toJson(commonConnectorMessage.message)
                )
            } catch (e: Exception) {
                e.printStackTrace()
            }
        }
}

Server는 상시 message Topic을 구독하고 있으며
유효한 메시지를 기반으로 message 전파를 호출한다.
이미 지나간 메시지는 실시간 메시지 전파와 맞지 않기에, offset 전략은 latest
reactor 설정인 offset commit은 autoAck(비동기)로 설정

마치며

최소 기능만 충족하도록 구현했으며
추후 기능추가 및 리펙토링이 진행될 것으로 예상된다.

지금은 핵심 기능은 게임 엔진 설계에 집중하고 있다.
목표는 기물을 기반으로 한 보드게임을 어느정도 커버할 수 있는 엔진을 만들고
해당 엔진으로 서버 interface를 구성한 뒤
web 또는 app을 구현하려 한다.

API Documentation 정리 (oas,swagger,asyncAPI)

북극곰은콜라 — Wed, 2 Aug 2023 18:18:28 +0900

개요

개발 문서 중 API Document를 작성할 방안에 대한 조사 진행
목표는 신뢰성 있으며, 유지보수에 용이한 API 문서 작성이다.
Target API 프로토콜로 REST, RSocket, Kafka Message, Websocket Message 이다.

신뢰성: 문서와 실제 구현상의 간극이 최소화 되는 것을 말함
유지보수 용이: Document 작성을 위한 시간을 최소화 하여, 생산성을 높이는 것, 또한 여러 타입의 문서로 재생산 가능한 것도 포함한다.

OpenAPI Specification 이란

OAS란 OpenAPI Specification의 약자로 REST API를 json 또는 yaml로 표현하는 방식에 대한 스펙을 의미한다.
2010년대 초 Tam Wordnik이 개발할 당시에는 Swagger 스펙으로 불리었지만
2015년 즈음 SmartBear에 인수되고, OpenAPI Initiative에 기부되면서 OpenAPI Specification으로 변경 됨

OpenAPI: REST를 정의할 수 있는 스펙
Swagger: OpenAPI 문서를 만들 수 있는 툴 (자동화 목적)

특징

REST API를 문서로 정의 및 생성 할 수 있다.
방대한 생태계 서포트를 통해, REST 문서 관리에 이점이 있다.
스펙 작성을 위한 공식 툴이 존재한다.
스펙을 기반으로 SDK / 코드 생성이 가능한다.
스펙을 기반으로 API 테스트도 가능하다.
오픈 라이센스이다.

OAS 생태계

Swagger UI: OAS를 Web UI로 볼 수 있는 어플리케이션
Swagger Editor: OAS 스펙 편집기, 브라우저 기반
Swagger Codegen: OAS를 기반으로 Server, Client Code 생성
Swagger Spring Integration: Spring 코드에서 OAS 문서를 생성해주는 라이브러리
OpenAPI IDE Plugins: OAS를 위한 IDE 서포트
Swagger Hub: OAS Document를 통한 협업을 손쉽게 진행할 수 있는 서비스
…

주요 스펙 설명

전체 스펙: https://swagger.io/specification/

OpenAPI Specification - Version 3.0.3 | Swagger

OpenAPI Specification Version 3.1.0 The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED", "NOT RECOMMENDED", "MAY", and "OPTIONAL" in this document are to be interpreted as described in BCP 14 RFC2119 RF

swagger.io

Field Name	Type	Description
openapi	string	REQUIRED. OAS의 스펙 버전, 문서 파싱할 때 참조하기 위한 값
info	Info Object	REQUIRED. 본 문서를 설명하는 metadata
servers	[Server Object]	테스트가 가능한 서버에 대한 정의
paths	Paths Object	REST Spec에 대한 정의
webhooks	Map[string, Path Item Object \| Reference Object] ]	콜백을 정의 할 수 있는 파트
components	Components Object	REST Spec에서 참조하는 객체 정의
security	[Security Requirement Object]	인증 및 보안에 관한 스펙
tags	[Tag Object]	API를 묶을 수 있는 tag를 정의
externalDocs	External Documentation Object	외부 문서 링크 등

paths Example

paths:
  /pet/findByStatus:
    get:
      tags:
        - pet
      summary: Finds Pets by status
      description: Multiple status values can be provided with comma separated strings
      operationId: findPetsByStatus
      parameters:
        - name: status
          in: query
          description: Status values that need to be considered for filter
          required: false
          explode: true
          schema:
            type: string
            default: available
            enum:
              - available
              - pending
              - sold
      responses:
        '200':
          description: successful operation
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/Pet'          
            application/xml:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/Pet'
        '400':
          description: Invalid status value
      security:
        - petstore_auth:
            - write:pets
            - read:pets

paths:
  /pet:
    post:
      tags:
        - pet
      summary: Add a new pet to the store
      description: Add a new pet to the store
      operationId: addPet
      requestBody:
        description: Create a new pet in the store
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/Pet'
          application/xml:
            schema:
              $ref: '#/components/schemas/Pet'
          application/x-www-form-urlencoded:
            schema:
              $ref: '#/components/schemas/Pet'
        required: true
      responses:
        '200':
          description: Successful operation
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Pet'          
            application/xml:
              schema:
                $ref: '#/components/schemas/Pet'
        '405':
          description: Invalid input
      security:
        - petstore_auth:
            - write:pets
            - read:pets

Components Example

components:
  schemas:
    Pet:
      required:
        - name
        - photoUrls
      type: object
      properties:
        id:
          type: integer
          format: int64
          example: 10
        name:
          type: string
          example: doggie
        category:
          $ref: '#/components/schemas/Category'
        photoUrls:
          type: array
          xml:
            wrapped: true
          items:
            type: string
            xml:
              name: photoUrl
        tags:
          type: array
          xml:
            wrapped: true
          items:
            $ref: '#/components/schemas/Tag'
        status:
          type: string
          description: pet status in the store
          enum:
            - available
            - pending
            - sold
      xml:
        name: pet

Spring With Swagger (OAS)

Spring 프로젝트에서 OAS 문서를 만들어 주는 서포트 라이브러리가 있다.
org.springdoc:springdoc-openapi-ui

Sample Code

@Configuration
public class Config {
    @Bean
    public OpenAPI openAPI() {
        return new OpenAPI()
                .info(new Info()
                  .title("...")
                  .description("...")
                  .externalDocs(new ExternalDocumentation()
                    .description("....")
                    .url("http://..."));
    }
}

@OpenAPIDefinition(info = @io.swagger.v3.oas.annotations.info.Info(title = "TEST API", version = "v1"))
@SecurityScheme(
        name = "bearerAuth",
        type = SecuritySchemeType.HTTP,
        bearerFormat = "JWT",
        scheme = "bearer"
)

@Tag(name = "TestAPI", description = "test")

@Operation(summary =  "테스트 기능1, 인증 필요", security = @SecurityRequirement(name = "bearerAuth"))

OAS 시각화

Swagger UI

Swagger to Postman

Swagger to Confluence

Swagger2Markup

AsyncAPI

OAS와 유사한 이벤트 드리븐 시스템을 위한 API 스펙
YAML 기반 API Describe 문서
이벤트 드리븐 아키텍쳐를 설명하기 위한 스펙이다.
Protocol에 종속적이지 않다.
Pub / Sub 구조를 정의하기 적합한 스펙

Library Support

Springwolf

// Consumer
@KafkaListener
@AsyncListener(operation = @AsyncOperation(
        channelName = "example-consumer-topic",
        description = "Optional. Customer uploaded an example payload",
        headers = @AsyncOperation.Headers(
                schemaName = "SpringKafkaDefaultHeaders",
                values = {
                        @AsyncOperation.Headers.Header(
                                name = DEFAULT_CLASSID_FIELD_NAME,
                                description = "Spring Type Id Header",
                                value = "io.github.stavshamir.springwolf.example.dtos.ExamplePayloadDto"
                        ),
                }
        )
))
@KafkaAsyncOperationBinding
public void receiveMessage(ExamplePayloadDto msg) {
    // process
}

// Producer
@AsyncPublisher(operation = @AsyncOperation(
        channelName = "example-producer-topic",
        description = "Optional. Customer uploaded an example payload",
        headers = @AsyncOperation.Headers(
                schemaName = "SpringKafkaDefaultHeaders",
                values = {
                        @AsyncOperation.Headers.Header(
                                name = DEFAULT_CLASSID_FIELD_NAME,
                                description = "Spring Type Id Header",
                                value = "io.github.stavshamir.springwolf.example.dtos.ExamplePayloadDto"
                        ),
                }
        )
))
@KafkaAsyncOperationBinding
public void sendMessage(ExamplePayloadDto msg) {
    // send
}

// Message
@AsyncPublisher(operation = @AsyncOperation(
        channelName = "example-producer-topic",
        description = "Optional. Customer uploaded an example payload",
        message = @AsyncMessage(
                messageId = "my-unique-id",
                name = "ExamplePayloadDto",
                schemaFormat = "application/schema+json;version=draft-07",
                description = "Example payload model for sending messages"
        )
))
public void sendMessage(ExamplePayloadDto msg) {
    // send
}

요약

1. OpenAPI Specification, Swagger는 REST 프로토콜에 종속적인 API Document 스펙이다.
2. OAS는 REST 프로토콜을 정의하고 활용하기에 좋은 생태계를 가지고 있다.
3. AsyncAPI는 Event-Driven 시스템을 정의할 수 있는 스펙이다.
4. 문서 자동화를 달성 위해서는 파일 기반 Documentation이 효과적이다.
5. json, yaml로 잘 정의된 스펙은 확장성이 뛰어나다.
6. 문서 신뢰성을 위해서는 테스트 기반 문서 생성 프로세스가 필요하다.

REFERENCE

https://swagger.io/specification/

https://plugins.jetbrains.com/plugin/8433-openapi-generator

https://engineering.linecorp.com/ko/blog/document-engineering-api-documentation

https://tech.kakaopay.com/post/openapi-documentation/

https://rlxuc0ppd.toastcdn.net/presentation/%5BNHN%20FORWARD%202020%5DMSA%20%ED%99%98%EA%B2%BD%EC%97%90%EC%84%9C%20API%20%EB%AC%B8%EC%84%9C%20%EA%B4%80%EB%A6%AC%ED%95%98%EA%B8%B0.pdf

https://www.asyncapi.com/docs/tools/generator/asyncapi-document

https://www.asyncapi.com/tools

https://springwolf.github.io/docs/configuration/documenting-producers/

mysql-connector with mariaDB 버전 호환성 이슈

북극곰은콜라 — Wed, 26 Jul 2023 19:22:05 +0900

개요

보안 이슈로 인하여, OS 버전업을 하게되면서, DB 버전을 올리는 일이 발생했다.
기존 코드는 mysql jdbc connector를 사용하여 mariaDB에 붙고 있었고
mariaDB의 버전이 올라가는 상황이다.
버전 업 과정에서 Connection 생성을 못하는 상황이 발생했으며, 해당 이슈 해결과정을 기록으로 남긴다.

변경 사항

	전	후
mariaDB version	10.1.25	11.0.2
mysql-connector-java version	8.0.21	8.0.21

이슈 분석

예외 발생

Caused by: java.sql.SQLException: Unknown system variable 'transaction_isolation'
	at com.mysql.cj.jdbc.exceptions.SQLError.createSQLException(SQLError.java:129)
	at com.mysql.cj.jdbc.exceptions.SQLError.createSQLException(SQLError.java:97)
	at com.mysql.cj.jdbc.exceptions.SQLExceptionsMapping.translateException(SQLExceptionsMapping.java:122)
	at com.mysql.cj.jdbc.ConnectionImpl.createNewIO(ConnectionImpl.java:836)
	at com.mysql.cj.jdbc.ConnectionImpl.<init>(ConnectionImpl.java:456)
	at com.mysql.cj.jdbc.ConnectionImpl.getInstance(ConnectionImpl.java:246)

transaction_isolation이란 DB의 variable을 찾을 수 없는 예외 발생
해당 예외로 인하여 connectionImpl 인스턴스 생성 불가

DB variable 확인

transaction_isolation이 아닌 tx_isolation이란 variable로 세팅되어있는 상황 확인

원인 파악

// com.mysql.cj.NativeSession 클래스

// public void loadServerVariables(Object syncMutex, String version) 메서드
...
if (!this.versionMeetsMinimum(8, 0, 3) && (!this.versionMeetsMinimum(5, 7, 20) || this.versionMeetsMinimum(8, 0, 0))) {
  queryBuf.append(", @@tx_isolation AS transaction_isolation");
} else {
  queryBuf.append(", @@transaction_isolation AS transaction_isolation");
}
...

mysql-connector:8.0.21 라이브러리의 관련 로직이다
this.versionMeetsMinimum() 메서드의 경우 파라미터보다 낮거나 같으면 true를 반환한다.
런 타임 상 MariaDB의 버전을 11.0.2로 인식을 하기에, mysql의 버전체계와 비교하면 맞지 않게 된다.
최종적으로 구현체에서 transaction_isolation으로 설정 값을 찾아와 한다고 인식
결론적으로 mysql connector 구현체를 통해 mariaDB를 사용하기에 발생한 이슈이다

참고사항: 기존 mariaDB 10.1.25 버전에서는 mariaDB의 버전 추출 값이 5.5.5(MySQL에 대응되는 버전 값)로 파싱이 되기 때문에, 문제가 없었다.

해결 방안 모색

2가지 해결방안이 있을 것으로 판단된다.

1. MariaDB 버전을 11.1 버전 이상으로 업그레이드

mariaDB를 11.1 버전으로 올려서 변수를 transaction_isolation으로 변수를 통일하여 이슈 해결하는 방안

2. mysql-connector 라이브러리 mariaDB-connector로 교체

현 시점 최신버전은 8.0.33 버전은 Mysql 버전 기준으로 버전 파싱 및 비교를 한다.
따라서 mysql-connector의 버전 업이 아닌 mariadb connector로 변경해야 한다.
+ jdbc 구현체 라이브러리가 변경되면서 소스의 드라이버 관련 코드를 모두 변경해야 한다.
→ mariadb-java-client:3.1.4 버전으로 교체 및 코드 변경

// org.mariadb.jdbc
// public class Connection implements java.sql.Connection

...

public int getTransactionIsolation() throws SQLException {
    String sql = "SELECT @@tx_isolation";
    if (!this.client.getContext().getVersion().isMariaDBServer() && (this.client.getContext().getVersion().getMajorVersion() >= 8 && this.client.getContext().getVersion().versionGreaterOrEqual(8, 0, 3) || this.client.getContext().getVersion().getMajorVersion() < 8 && this.client.getContext().getVersion().versionGreaterOrEqual(5, 7, 20))) {
      sql = "SELECT @@transaction_isolation";
    }

...

mariaDB에서 제공하는 jdbc를 보면
mariaDB server인지 확인 후, mysql일 경우 버전 비교를 통해 transaction_isolation을 적용하여 기동하도록 되어있다.
connector 라이브러리는 아직 11.1+버전에서 추가된 transaction_isolation에 대한 부분은 반영하지 못한 것으로 추정된다.

결론

DB와 JDBC를 맞추는 방향이, 사이드 이펙트를 최소화 할 수 있는 방안이며
추후 업데이트되는 측면에서 유리하다고 판단된다.
따라서 해당 해결 방안을 채택해서 적용하였다.

REFERENCE

https://jira.mariadb.org/browse/MDEV-21921

https://mariadb.com/kb/en/server-system-variables/#transaction_isolation

#1 FlagWar 기획

북극곰은콜라 — Wed, 12 Jul 2023 16:58:40 +0900

개요

軍旗(군기)라는 중국 보드 게임이 있습니다.
상대방의 깃발을 뺏는 전략 보드게임으로 상당히 재밌게 했던 기억이 있습니다.
해당 게임을 크로스 플랫폼으로 적절히 번역해서 개발하는것이 목표

요구사항 정리

일반 2인 FlagWar 게임만 구현
1. 기물 세팅 구현 (로컬 캐싱기능만)
2. simple 매칭 시스템 구현 (매칭룰 없음 FIFO)
3. 게임 플레이 관련 구현
게임 resume을 염두한 설계
기능적 확장성 고려
인프라 확장성 및 가용성 고려
반응성 고려
핵심기능만 우선 구현 (추후 기능 추가개발)

게임 룰 정의

보드와 기물

1. 보드

5 X 12 게임판
기물을 배치할 수 있는 위치는 총 60개 이며, 위치는 포인트로 지칭한다. 총 3종류의 포인트가 있다.
기물이 움직이는 경로가 있으며, 경로는 총 2가지 있다.

포인트 설명
- 본진(大本營): 본진의 의미를 가지며, 해당 위치에는 목표물에 해당하는 "깃"이 배치되어야 한다. 해당 위치에 올라간 기물은 움직일 수 없다.
- 거점(行營): 거점의 의미를 가지며, 배치 단계에서 기물을 배치할 수 없다. 게임 시작 후 기물을 거점으로 이동할 수 있으며, 해당 포인트의 기물은 무적이며 적에게 공격당할 수 없다.
- 초소(兵點): 초소의 의미를 가지며, 일반적인 배치 포인트 및 이동 포인트이다.

경로 설명
- 한줄 경로: 일반적인 경로이며, 한턴에 한칸씩 갈 수 있음을 의미한다.
- 2줄경로: 철도를 의미하며, 직선이동을 할 수 있다. 모든 기물은 다른 기물이 막지 않는 범위에서 여러칸 이동을 할 수 있다. 특수 기물인 공병대의 경우 철도로 연결된 모든경로를 대상으로 움직일 수 있다.

2. 기물

총 25개의 기물로 구성된다.
일반 기물과 특수 기물로 나누어지며 각 기물은 고유의 등급, 고유능력을 가진다.
자신보다 등급이 높은 기물에게 잡아먹힌다.
번역보다는 한국 군 체계를 따라서 정의한다.

일반 기물 / 갯 수
- 본부(司令): 1
- 군단(軍長): 1
- 사단(師長): 2
- 여단(旅長): 2
- 연대(團長): 2
- 대대(營長): 2
- 중대(蓮長): 3
- 분대(排長): 3
일반 기물의 등급은 내림차순으로
본부 -> 군단 -> 사단 -> 여단 -> 연대 -> 대대 -> 중대 -> 분대

특수 기물 / 갯 수 / 고유능력
- 깃(軍旗): 1, 게임의 목표가 되는 기물로 항상 본진 포인트에 배치되어야하며, 움직일 수 없다. 지뢰가 3개 모두 제거되면, 기물이 상대방에게 노출된다. 등급은 최하로 모든 기물에게 먹힌다.
- 폭탄(炸彈): 2, 등급은 없으며, 모든 기물과 만나면 같이 죽는 자폭 기물이다. 일반 룰에서는 각 진영의 최 전방 1라인에 배치될 수 없다.
- 지뢰(地雷): 3, 등급은 최상급으로 공병을 제외한 모든 기물을 이긴다. 하지만 배치 후 움직일 수 없다. 일반 룰에서는 최 후방 2 라인에만 배치될 수 있다.
- 공병(工兵): 3, 등급은 최하급으로 오직 지뢰만 제거 가능한 기물이다. 철도가 연결되며 막히지 않은 모든 지점을 이동할 수 있다.

3. 게임 룰 및 진행

배치 단계, 게임 단계로 총 2가지 단계로 구성된다.
배치 단계는 게임 시작 전 기물을 배치하는 단계로 룰에 따라 각 기물들을 배치한다. 모든 기물을 배치하는 것이 원칙이다.
게임 단계는 각 기물을 움직여서 승리 조건을 채우는 단계이다.
턴 방식으로 각 기물을 움직일 수 있다.
상대방 기물과 겹치면, 등급과 능력에 따라서 승패가 결정되며, 승리한 기물이 남고 패배한 기물은 제거된다. 비기면 둘다 사라진다.

승리 조건
- 상대방의 깃을 공격한다.
- 상대방의 모든 기물이 움직일 수 없는 상태로 만든다.

마무리

설계 및 구현 난이도가 쫌 있을것으로 예상되며
유지보수 및 기능 확장이 가능한 구조로 구현하는 것이 목표다

Kafka Consumer #4 Offset Commit Strategy

북극곰은콜라 — Thu, 22 Jun 2023 18:08:42 +0900

개요

Kafka Consumer의 Commit 설정 및 전략에 대한 조사

Kafka Commit Config

name	Desc	Default
enable.auto.commit	Auto-Commit 사용 여부	true
auto.commit.interval.ms	Auto-Commit 사용 시 Commit을 수행할 시간 (ms)	5000

AUTO-Commit

enable.auto.commit : commit 여부
auto.commit.interval.ms : commit interval 시간

public void maybeAutoCommitOffsetsAsync(long now) {
    if (autoCommitEnabled) {
        nextAutoCommitTimer.update(now);
        if (nextAutoCommitTimer.isExpired()) {
            nextAutoCommitTimer.reset(autoCommitIntervalMs);
            autoCommitOffsetsAsync();
        }
    }
}

auto commit이 enable true 인 경우
poll() 호출 시 마다 ConsumerCoordinator의 poll() 이 호출되고
poll() 내부적으로 autoCommit설정 시 동작하는 maybeAutoCommitOffsetsAsync()가 수행된다.

Confluent Client Sample Code

final Consumer<String, DataRecord> consumer = new KafkaConsumer<String, DataRecord>(props);
consumer.subscribe(Arrays.asList(topic));

Long total_count = 0L;

try {
  while (true) {
    ConsumerRecords<String, DataRecord> records = consumer.poll(Duration.ofMillis(100));
    for (ConsumerRecord<String, DataRecord> record : records) {
      String key = record.key();
      DataRecord value = record.value();
      total_count += value.getCount();
      System.out.printf("Consumed record with key %s and value %s, and updated total count to %d%n", key, value, total_count);
    }
  }
} finally {
  consumer.close();
}

일반 Client의 Sample은 Data를 순회하면서 처리한다.

문제:
- 비동기 프로그램으로 record 처리 시, commit에 대한 문제가 발생
- record들이 각각 비동기적으로 처리 될 시, commit 시점에 대한 고려가 필요함

Spring with Kafka (Commit Strategy)

Spring에서 Kafka를 Integration된 library의 interface / configuration 분석

Spring은 내부적으로 Spring Configuration을 통해 KafkaConsumer 객체를 생성 후 관리를 한다.
Spring은 Commit을 AckMode로 불린다.
Spring은 KafkaConsumer를 사용하기 위한 Listener를 제공한다.
Listener는 MessageListener와 BatchMessageListener 2가지를 제공하며, 차이점은 한 번에 처리할 Record가 1개 또는 다수 일지 이다.
자세한 사항은 후술

Spring Kafka AckMode

AckMode	Desc
RECORD	Commit the offset after each record is processed by the listener. 한번에 하나의 처리된 레코드 커밋
BATCH	Commit the offsets of all records returned by the previous poll after they all have been processed by the listener. 이전 poll()된 record가 모두 처리된 후 커밋
TIME	Commit pending offsets after {@link ContainerProperties#setAckTime(long) ackTime} has elapsed. actTime 이후 pending된 record 커밋
COUNT	Commit pending offsets after {@link ContainerProperties#setAckCount(int) ackCount} has been exceeded. AckCount 만큼 record 처리 후 커밋
COUNT_TIME	Commit pending offsets after {@link ContainerProperties#setAckCount(int) ackCount} has been exceeded or after {@link ContainerProperties#setAckTime(long) ackTime} has elapsed. TIME or COUNT 조건 만족 시 커밋
MANUAL	Listener is responsible for acking - use a {@link org.springframework.kafka.listener.AcknowledgingMessageListener}; acks will be queued and offsets will be committed when all the records returned by the previous poll have been processed by the listener. AcknowledgingMessageListener를 통해서 커밋을 큐잉한다. Acknowledgement.acknowledge()가 호출되면 다음번 poll()때 이전 Records들을 commit 한다.
MANUAL_IMMEDIATE	Listener is responsible for acking - use a {@link org.springframework.kafka.listener.AcknowledgingMessageListener}; the commit will be performed immediately if the {@code Acknowledgment} is acknowledged on the calling consumer thread; otherwise, the acks will be queued and offsets will be committed when all the records returned by the previous poll have been processed by the listener; results will be indeterminate if you sometimes acknowledge on the calling thread and sometimes not. AcknowledgingMessageListener를 통해 즉시 커밋을 호출한다.

Quarkus with Kafka (Commit Strategy)

참고:

Quarkus는 MSA를 구성하기 위해 만들어진 Java 기반 Framework이다.
Red-hat의 주도로 만들어졌으며, 주요 이점은 다음과 같다
- 개발자 친화적
- 컨테이너(쿠버네티스)에 Java를 최적화 (GraalVM 최적화)
- common한 framework와 결합
- Reactive한 code flow 지원

Quarkus의 Kafka 비동기 프로그래밍 Commit 전략

Strategy	Desc
Throttled	제한 전략 모든 비동기 처리에 대한 ack를 관리하고 특정 위치의 이전 ack가 모두 성공한 상황에서 commit 실행 영원히 오지 않을 수 있는 ack에 대해서는 별도의 max-age 속성을 통해 시간 체크 후 무시
Ignore	무시 전략 commit에 관여하지 않는다. gracefully shutdown시 또는 rebalance 시에만 commit 동작
Latest	최신 전략 일정 주기로 비동기 처리의 최신 ack의 offset을 commit

Reactive Kafka (Commit Strategy)

ACK Mode Summary

AckMode	Desc
AUTO_ACK	AUTO_ACK 모드로 Flux 생성 시 KafkaConsumer에서 poll()된 records들을 Flux로 받는다 전달받은 Flux (poll 된 records)가 종료되면 자동으로 commit 처리된다. 최대 poll() 된 크기 단위로 Message 중복이 발생할 수 있다.
MANUAL_ACK	수동으로 offset 조작을 하기 위한 모드 전달받은 Record의 offset을 기반으로 하여 수동으로 commit 수행 (내부적으로 commit 된 offset 보다 작으면 무시) offset이 기존보다 크면, commit scheduler에 commit할 offset 등록
ATMOST_ONCE	중복 처리를 방지하는 커밋 모드 poll() 이 후 flux 생성 전 동기적으로 poll()한 record에 대한 commit을 진행 commit이 동기적으로 수행되기에 실제 record를 받는데 비용이 발생 사실 상 record를 받은 시점에서 commit 하는것으로 볼 수 있으며 commit 설정에 따라서 Message 손실이 발생할 수 있다.
EXACTLY_ONCE	consum → process → produce 의 transaction을 보장해주는 모드 produce의 transaction을 받아서 commit()을 실행한다.

AUTO_ACK vs ATMOST_ONCE 성능

AUTO_ACK 모드는 asyncCommit()을 이용하기 때문에, commit 메시지가 유실될 수 있어, 메시지 중복처리가 발생할 수 있다.
ATMOST_ONCE는 syncCommit()을 이용하기 때문에, commit 메시지가 유실되지 않으며, 미리 commit하기 때문에 중복처리가 없지만, 손실이 발생할 수 있다.
따라서 성능적으로 asyncCommit()을 사용하는 AUTO_ACK 모드가 syncCommit()을 사용하는 ATMOST_ONCE보다 좋다

Reactive Kafka Commit Config

Map<String, Object> consumerConfig = new HashMap<>();
consumerConfig.put(ConsumerConfig.BOOTSTRAP_SERVERS_CONFIG, "192.168.2.89:29091");
consumerConfig.put(ConsumerConfig.GROUP_ID_CONFIG, "test-1");
consumerConfig.put(ConsumerConfig.KEY_DESERIALIZER_CLASS_CONFIG, StringDeserializer.class);
consumerConfig.put(ConsumerConfig.VALUE_DESERIALIZER_CLASS_CONFIG, StringDeserializer.class);
consumerConfig.put(ConsumerConfig.AUTO_OFFSET_RESET_CONFIG, OffsetResetStrategy.EARLIEST.name().toLowerCase());
consumerConfig.put(ConsumerConfig.MAX_POLL_RECORDS_CONFIG, 10);
consumerConfig.put(ConsumerConfig.INTERCEPTOR_CLASSES_CONFIG, List.of("LoggingCommitInterceptor"));

ReceiverOptions<String, String> receiverOptions = ReceiverOptions.create(consumerConfig);

this.kafkaReceiver = KafkaReceiver
    .create(receiverOptions
        .commitInterval(Duration.ZERO)
        .commitBatchSize(1)
        .subscription(List.of("commit-test-1")));

ConsumerConfig (Kafka Client Config)를 기반으로 ReceiverOptions 생성 후
Reactive에서 정의된 option들을 추가적으로 설정한다.
KafkaReceiver는 ReceiverOptions 기반으로 생성한다.
내부적으로 KafkaClient는 ConsumerConfig를 기반으로 동작하고, ConsumerHandler가 전체적인 Config를 종합하여 동작한다.
※ KafkaReceiver는 기본적으로 Commit을 ACK_MODE에 따라서 자체적으로 관리한다. 따라서 ConsumerConfig의 Auto-commit 옵션은 무시된다고 보면 된다.

name	Desc
commitInterval(Duration commitInterval)	Commit의 interval 시간 값 설정 시 · batchSize에 도달 안해도 시간에 따라서 commit 요청 0으로 설정 시 · batchSize가 설정 되어있을 시 batchSize 설정 만으로 commit 동작 · batchSzie도 0일 시 수동으로 commit에 대한 handling 필요 (ReceiverOffset.commit())
commitBatchSize(int commitBatchSize)	commit시 필요한 record의 최소 단위 설정 값 설정시 · 값에 도달하면 commit 0으로 설정 시 · interval 설정에 의해서만 commit 동작 · interval 또한 0이면 수동으로 commit에 대한 handling 필요 (ReceiverOffset.commit())
atmostOnceCommitAheadSize(int commitAheadSize)	ATMOST_ONCE에서 보장하는 최대로 손실될 size 값 설정시 · 매번 record 발행 전 commit을 확인하여 발행할 records가 현재 commit을 넘으면, size + 1 만큼 syncCommit()을 한다. · 따라서 최대로 손실 될 수 있는 message 갯수는 size + 1 이다. 0으로 설정 시 · record 발행 시마다 미리 syncCommit()을 한다.
maxCommitAttempts(int maxAttempts)	commit 최대 시도 횟수
commitRetryInterval(Duration commitRetryInterval)	commit retry 시간
maxDeferredCommits(int maxDeferred)	지연된 commit의 최대 갯수

AUTO_ACK

default Flux<Flux<ConsumerRecord<K, V>>> receiveAutoAck() {
    return receiveAutoAck(null);
}

poll() 된 records단위로 flux가 생성된다.
flux 단위로 commit이 처리된다.
따라서, 서버가 갑자기 다운되는 경우 마지막으로 처리된 poll() records가 commit 되어있어 중복 처리가 발생

this.kafkaReceiver = KafkaReceiver
    .create(receiverOptions
        .commitInterval(Duration.of(10, ChronoUnit.MILLIS))
        .commitBatchSize(1)
        .subscription(List.of("commit-test-1")));

...

private static void subscribeAutoAck() {
  KafkaReceiverManager kafkaReceiverManager = new KafkaReceiverManager();

  kafkaReceiverManager.getReceiver()
      .receiveAutoAck()
      .concatMap(r -> r)
      .doOnNext(record -> errorByPrefix("55", record.value()))
      .onErrorContinue((e, o) -> {
        log.error("error on consume", e);
        System.exit(1);
      })
      .subscribe(record -> log.info("key: {}, value: {}", record.key(), record.value()));
}

// concatMap

Test log

// 10개 씩 records Poll()
14:15:46.014 [reactive-kafka-test-1-1] INFO LoggingCommitInterceptor -- onConsume: commit-test-1-0-2740,commit-test-1-0-2741,commit-test-1-0-2742,commit-test-1-0-2743,commit-test-1-0-2744,commit-test-1-0-2745,commit-test-1-0-2746,commit-test-1-0-2747,commit-test-1-0-2748,commit-test-1-0-2749

// Emit
14:15:46.014 [reactive-kafka-test-1-1] DEBUG reactor.kafka.receiver.internals.ConsumerEventLoop -- Emitting 10 records, requested now 0

// 10개 정상 처리
14:15:46.014 [reactive-kafka-test-1-1] INFO TestMain -- key: null, value: 41-1260010f-ded8-4c5e-b8db-8006d2491bff
14:15:46.014 [reactive-kafka-test-1-1] INFO TestMain -- key: null, value: 42-04dbe9e7-b21f-445e-8d3f-09a582dbe3b9
14:15:46.014 [reactive-kafka-test-1-1] INFO TestMain -- key: null, value: 43-14d5c8e4-e1b5-4610-be9d-edac51cf9f6c
14:15:46.014 [reactive-kafka-test-1-1] INFO TestMain -- key: null, value: 44-161c3aae-6d60-49bd-bc4a-95a811988d57
14:15:46.014 [reactive-kafka-test-1-1] INFO TestMain -- key: null, value: 45-c7690625-9ae5-4987-9519-e8b6dfb82831
14:15:46.014 [reactive-kafka-test-1-1] INFO TestMain -- key: null, value: 46-9f9e68b5-a199-4b25-abca-263742e6cb33
14:15:46.014 [reactive-kafka-test-1-1] INFO TestMain -- key: null, value: 47-474d1bfa-c755-4ca8-ab57-771cb4d718e2
14:15:46.014 [reactive-kafka-test-1-1] INFO TestMain -- key: null, value: 48-0ab63698-8ff2-4369-bc93-e9c763c4b152
14:15:46.014 [reactive-kafka-test-1-1] INFO TestMain -- key: null, value: 49-cb46f2a2-79a7-4949-bda3-8c62719113da
14:15:46.014 [reactive-kafka-test-1-1] INFO TestMain -- key: null, value: 50-7bc420c8-1a00-4c41-9f63-599bf49a80d0
14:15:46.014 [reactive-kafka-test-1-1] DEBUG reactor.kafka.receiver.internals.ConsumerEventLoop -- onRequest.toAdd 1, paused false

// Async Commit (check by ConsumerEventLoop)
14:15:46.014 [reactive-kafka-test-1-1] DEBUG reactor.kafka.receiver.internals.ConsumerEventLoop -- Async committing: {commit-test-1-0=OffsetAndMetadata{offset=2750, leaderEpoch=null, metadata=''}}

// KafkaConsumer로 commit 호출
14:15:46.014 [reactive-kafka-test-1-1] DEBUG org.apache.kafka.clients.consumer.KafkaConsumer -- [Consumer clientId=consumer-test-1-1, groupId=test-1] Committing offsets: {commit-test-1-0=OffsetAndMetadata{offset=2750, leaderEpoch=null, metadata=''}}

// NetworkClient로 commit 호출, Get Reponse From Broker
14:15:46.014 [reactive-kafka-test-1-1] DEBUG org.apache.kafka.clients.NetworkClient -- [Consumer clientId=consumer-test-1-1, groupId=test-1] Sending OFFSET_COMMIT request with header RequestHeader(apiKey=OFFSET_COMMIT, apiVersion=8, clientId=consumer-test-1-1, correlationId=35) and timeout 30000 to node 2147483646: OffsetCommitRequestData(groupId='test-1', generationId=90, memberId='consumer-test-1-1-97557ddd-e091-4e03-9db5-c687955bd175', groupInstanceId=null, retentionTimeMs=-1, topics=[OffsetCommitRequestTopic(name='commit-test-1', partitions=[OffsetCommitRequestPartition(partitionIndex=0, committedOffset=2750, committedLeaderEpoch=-1, commitTimestamp=-1, committedMetadata='')])])
14:15:46.015 [reactive-kafka-test-1-1] DEBUG org.apache.kafka.clients.NetworkClient -- [Consumer clientId=consumer-test-1-1, groupId=test-1] Received OFFSET_COMMIT response from node 2147483646 for request with header RequestHeader(apiKey=OFFSET_COMMIT, apiVersion=8, clientId=consumer-test-1-1, correlationId=33): OffsetCommitResponseData(throttleTimeMs=0, topics=[OffsetCommitResponseTopic(name='commit-test-1', partitions=[OffsetCommitResponsePartition(partitionIndex=0, errorCode=0)])])

// 10개 씩 Poll()
14:15:46.015 [reactive-kafka-test-1-1] INFO LoggingCommitInterceptor -- onConsume: commit-test-1-0-2750,commit-test-1-0-2751,commit-test-1-0-2752,commit-test-1-0-2753,commit-test-1-0-2754,commit-test-1-0-2755,commit-test-1-0-2756,commit-test-1-0-2757,commit-test-1-0-2758,commit-test-1-0-2759

// Emit
14:15:46.015 [reactive-kafka-test-1-1] DEBUG reactor.kafka.receiver.internals.ConsumerEventLoop -- Emitting 10 records, requested now 0

// 54까지 정상, 55에서 Error, System.exit(1)
14:15:46.015 [reactive-kafka-test-1-1] INFO TestMain -- key: null, value: 51-22044176-c4bf-4f77-bbfa-1ba66f638db6
14:15:46.015 [reactive-kafka-test-1-1] INFO TestMain -- key: null, value: 52-c830bc30-c4b1-4155-9916-982c8d2fba6d
14:15:46.015 [reactive-kafka-test-1-1] INFO TestMain -- key: null, value: 53-aefd0b98-9309-440c-998f-c2f6c27acb92
14:15:46.015 [reactive-kafka-test-1-1] INFO TestMain -- key: null, value: 54-4262041c-9ace-45ea-b87d-cb993c10922c
14:15:46.017 [reactive-kafka-test-1-1] ERROR TestMain -- error on consume
java.lang.RuntimeException: prefix error !!
	at TestMain.errorByPrefix(TestMain.java:40)
	at TestMain.lambda$subscribeAutoAck$1(TestMain.java:22)
...

기본적으로 polling된 Records의 단위로 동작을 하기 때문에, 메시지의 중복 처리가 발생할 수 있다.
Commit이 별도의 Async로 동작하기에, CommitInterval 설정과 BatchSize를 적절하게 세팅해야한다.
경우에 따라서 중복 처리되는 메시지가 늘어날 수 있다.
- commitAsync 요청이 NetworkClient 안에서 큐잉이 발생했을 때 Application이 강제 종료되면 마지막으로 보내진 Commit 이후 메시지들이 중복처리됨

ATMOST_ONCE

default Flux<ConsumerRecord<K, V>> receiveAtmostOnce() {
    return receiveAtmostOnce(null);
}

this.kafkaReceiver = KafkaReceiver
        .create(receiverOptions
            .atmostOnceCommitAheadSize(20)
            .subscription(List.of("commit-test-1")));

private static void subscribeAtMostOnce() {
  KafkaReceiverManager kafkaReceiverManager = new KafkaReceiverManager();

  kafkaReceiverManager.getReceiver()
      .receiveAtmostOnce()
      .doOnNext(record -> errorByPrefix("55", record.value()))
      .onErrorContinue((e, o) -> {
        log.error("error on consume", e);
        System.exit(1);
      })
      .subscribe(record -> {
        log.info("key: {}, value: {}", record.key(), record.value());
      });
}

Test Log

size = 0

...
16:29:08.387 [reactive-kafka-test-1-1] INFO TestMain -- key: null, value: 52-9f1921f1-9eee-4d50-a42d-f008687aada2
16:29:08.387 [reactive-kafka-test-1-1] DEBUG reactor.kafka.receiver.internals.ConsumerEventLoop -- Sync committing: {commit-test-1-0=OffsetAndMetadata{offset=2953, leaderEpoch=null, metadata=''}}
16:29:08.387 [reactive-kafka-test-1-1] DEBUG org.apache.kafka.clients.NetworkClient -- [Consumer clientId=consumer-test-1-1, groupId=test-1] Sending OFFSET_COMMIT request with header RequestHeader(apiKey=OFFSET_COMMIT, apiVersion=8, clientId=consumer-test-1-1, correlationId=62) and timeout 30000 to node 2147483646: OffsetCommitRequestData(groupId='test-1', generationId=94, memberId='consumer-test-1-1-2c2a4598-c0ca-463a-a31a-40c591c40daa', groupInstanceId=null, retentionTimeMs=-1, topics=[OffsetCommitRequestTopic(name='commit-test-1', partitions=[OffsetCommitRequestPartition(partitionIndex=0, committedOffset=2953, committedLeaderEpoch=-1, commitTimestamp=-1, committedMetadata='')])])
16:29:08.388 [reactive-kafka-test-1-1] DEBUG org.apache.kafka.clients.NetworkClient -- [Consumer clientId=consumer-test-1-1, groupId=test-1] Received OFFSET_COMMIT response from node 2147483646 for request with header RequestHeader(apiKey=OFFSET_COMMIT, apiVersion=8, clientId=consumer-test-1-1, correlationId=62): OffsetCommitResponseData(throttleTimeMs=0, topics=[OffsetCommitResponseTopic(name='commit-test-1', partitions=[OffsetCommitResponsePartition(partitionIndex=0, errorCode=0)])])
16:29:08.389 [reactive-kafka-test-1-1] DEBUG org.apache.kafka.clients.consumer.internals.ConsumerCoordinator -- [Consumer clientId=consumer-test-1-1, groupId=test-1] Committed offset 2953 for partition commit-test-1-0
16:29:08.389 [reactive-kafka-test-1-1] INFO LoggingCommitInterceptor -- onCommit: commit-test-1-0-2953
16:29:08.389 [reactive-kafka-test-1-1] INFO TestMain -- key: null, value: 53-fd5794b0-0252-4345-a110-cd1e5eab7dbc
16:29:08.389 [reactive-kafka-test-1-1] INFO LoggingCommitInterceptor -- onConsume: commit-test-1-0-2990,commit-test-1-0-2991,commit-test-1-0-2992,commit-test-1-0-2993,commit-test-1-0-2994,commit-test-1-0-2995,commit-test-1-0-2996,commit-test-1-0-2997,commit-test-1-0-2998,commit-test-1-0-2999
16:29:08.389 [reactive-kafka-test-1-1] DEBUG reactor.kafka.receiver.internals.ConsumerEventLoop -- Emitting 10 records, requested now 10
16:29:08.389 [reactive-kafka-test-1-1] DEBUG reactor.kafka.receiver.internals.ConsumerEventLoop -- Sync committing: {commit-test-1-0=OffsetAndMetadata{offset=2954, leaderEpoch=null, metadata=''}}
16:29:08.389 [reactive-kafka-test-1-1] DEBUG org.apache.kafka.clients.NetworkClient -- [Consumer clientId=consumer-test-1-1, groupId=test-1] Sending OFFSET_COMMIT request with header RequestHeader(apiKey=OFFSET_COMMIT, apiVersion=8, clientId=consumer-test-1-1, correlationId=63) and timeout 30000 to node 2147483646: OffsetCommitRequestData(groupId='test-1', generationId=94, memberId='consumer-test-1-1-2c2a4598-c0ca-463a-a31a-40c591c40daa', groupInstanceId=null, retentionTimeMs=-1, topics=[OffsetCommitRequestTopic(name='commit-test-1', partitions=[OffsetCommitRequestPartition(partitionIndex=0, committedOffset=2954, committedLeaderEpoch=-1, commitTimestamp=-1, committedMetadata='')])])
16:29:08.390 [reactive-kafka-test-1-1] DEBUG org.apache.kafka.clients.NetworkClient -- [Consumer clientId=consumer-test-1-1, groupId=test-1] Received OFFSET_COMMIT response from node 2147483646 for request with header RequestHeader(apiKey=OFFSET_COMMIT, apiVersion=8, clientId=consumer-test-1-1, correlationId=63): OffsetCommitResponseData(throttleTimeMs=0, topics=[OffsetCommitResponseTopic(name='commit-test-1', partitions=[OffsetCommitResponsePartition(partitionIndex=0, errorCode=0)])])
16:29:08.391 [reactive-kafka-test-1-1] DEBUG org.apache.kafka.clients.consumer.internals.ConsumerCoordinator -- [Consumer clientId=consumer-test-1-1, groupId=test-1] Committed offset 2954 for partition commit-test-1-0
16:29:08.391 [reactive-kafka-test-1-1] INFO LoggingCommitInterceptor -- onCommit: commit-test-1-0-2954
16:29:08.391 [reactive-kafka-test-1-1] INFO TestMain -- key: null, value: 54-d5942adc-529f-4af9-99d7-5c8df55bb1aa
16:29:08.391 [reactive-kafka-test-1-1] DEBUG reactor.kafka.receiver.internals.ConsumerEventLoop -- Sync committing: {commit-test-1-0=OffsetAndMetadata{offset=2955, leaderEpoch=null, metadata=''}}
16:29:08.391 [reactive-kafka-test-1-1] DEBUG org.apache.kafka.clients.NetworkClient -- [Consumer clientId=consumer-test-1-1, groupId=test-1] Sending OFFSET_COMMIT request with header RequestHeader(apiKey=OFFSET_COMMIT, apiVersion=8, clientId=consumer-test-1-1, correlationId=64) and timeout 30000 to node 2147483646: OffsetCommitRequestData(groupId='test-1', generationId=94, memberId='consumer-test-1-1-2c2a4598-c0ca-463a-a31a-40c591c40daa', groupInstanceId=null, retentionTimeMs=-1, topics=[OffsetCommitRequestTopic(name='commit-test-1', partitions=[OffsetCommitRequestPartition(partitionIndex=0, committedOffset=2955, committedLeaderEpoch=-1, commitTimestamp=-1, committedMetadata='')])])
16:29:08.392 [reactive-kafka-test-1-1] DEBUG org.apache.kafka.clients.NetworkClient -- [Consumer clientId=consumer-test-1-1, groupId=test-1] Received OFFSET_COMMIT response from node 2147483646 for request with header RequestHeader(apiKey=OFFSET_COMMIT, apiVersion=8, clientId=consumer-test-1-1, correlationId=64): OffsetCommitResponseData(throttleTimeMs=0, topics=[OffsetCommitResponseTopic(name='commit-test-1', partitions=[OffsetCommitResponsePartition(partitionIndex=0, errorCode=0)])])
16:29:08.392 [reactive-kafka-test-1-1] DEBUG org.apache.kafka.clients.consumer.internals.ConsumerCoordinator -- [Consumer clientId=consumer-test-1-1, groupId=test-1] Committed offset 2955 for partition commit-test-1-0
16:29:08.392 [reactive-kafka-test-1-1] INFO LoggingCommitInterceptor -- onCommit: commit-test-1-0-2955
16:29:08.395 [reactive-kafka-test-1-1] ERROR TestMain -- error on consume
java.lang.RuntimeException: prefix error !!
	at TestMain.errorByPrefix(TestMain.java:51)
...

size = 20

...
// poll 10
08:36:58.748 [reactive-kafka-test-1-1] INFO LoggingCommitInterceptor -- onConsume: commit-test-1-0-3800,commit-test-1-0-3801,commit-test-1-0-3802,commit-test-1-0-3803,commit-test-1-0-3804,commit-test-1-0-3805,commit-test-1-0-3806,commit-test-1-0-3807,commit-test-1-0-3808,commit-test-1-0-3809
...
// poll: 10, commit: 0 -> commit: 21
08:36:58.757 [reactive-kafka-test-1-1] INFO LoggingCommitInterceptor -- onCommit: commit-test-1-0-3821
08:36:58.757 [reactive-kafka-test-1-1] INFO TestMain -- key: null, value: 1-99908b38-4cce-43c9-8e1e-2bdadfc8918a
// poll: 10, commit: 21 -> poll: 20
08:36:58.758 [reactive-kafka-test-1-1] INFO LoggingCommitInterceptor -- onConsume: commit-test-1-0-3810,commit-test-1-0-3811,commit-test-1-0-3812,commit-test-1-0-3813,commit-test-1-0-3814,commit-test-1-0-3815,commit-test-1-0-3816,commit-test-1-0-3817,commit-test-1-0-3818,commit-test-1-0-3819
...
// poll: 20, commit: 21 -> commit: 22
08:36:58.760 [reactive-kafka-test-1-1] INFO LoggingCommitInterceptor -- onCommit: commit-test-1-0-3822
08:36:58.760 [reactive-kafka-test-1-1] INFO TestMain -- key: null, value: 2-f156abbd-16b5-4f5e-a951-1936df768fff
...
08:36:58.761 [reactive-kafka-test-1-1] INFO TestMain -- key: null, value: 10-46020f53-66bb-4c4e-9a8a-00d646d781d0
08:36:58.761 [reactive-kafka-test-1-1] INFO TestMain -- key: null, value: 11-6000179f-5bea-44ba-86ff-c1dcb044cbb3
...
08:36:58.762 [reactive-kafka-test-1-1] INFO TestMain -- key: null, value: 20-ab35889b-aa01-4b71-a47c-42389d5f3173
...
// poll: 20, commit:22 -> commit: 32
08:36:58.764 [reactive-kafka-test-1-1] INFO LoggingCommitInterceptor -- onCommit: commit-test-1-0-3832
// poll: 20, commit:32 -> poll: 30
08:36:58.765 [reactive-kafka-test-1-1] INFO LoggingCommitInterceptor -- onConsume: commit-test-1-0-3820,commit-test-1-0-3821,commit-test-1-0-3822,commit-test-1-0-3823,commit-test-1-0-3824,commit-test-1-0-3825,commit-test-1-0-3826,commit-test-1-0-3827,commit-test-1-0-3828,commit-test-1-0-3829
08:36:58.765 [reactive-kafka-test-1-1] DEBUG reactor.kafka.receiver.internals.ConsumerEventLoop -- Emitting 10 records, requested now 0
08:36:58.765 [reactive-kafka-test-1-1] INFO TestMain -- key: null, value: 21-e78a711a-02d3-4615-88a4-46a9fc4e001f
...
08:36:58.765 [reactive-kafka-test-1-1] INFO TestMain -- key: null, value: 30-1af38ef1-1ea5-4147-874a-465aa9a49151
...
// poll: 30, commit: 32 -> commit: 43
08:36:58.767 [reactive-kafka-test-1-1] INFO LoggingCommitInterceptor -- onCommit: commit-test-1-0-3843
// poll:30, commit: 43 -> poll: 40
08:36:58.767 [reactive-kafka-test-1-1] INFO LoggingCommitInterceptor -- onConsume: commit-test-1-0-3830,commit-test-1-0-3831,commit-test-1-0-3832,commit-test-1-0-3833,commit-test-1-0-3834,commit-test-1-0-3835,commit-test-1-0-3836,commit-test-1-0-3837,commit-test-1-0-3838,commit-test-1-0-3839
08:36:58.767 [reactive-kafka-test-1-1] DEBUG reactor.kafka.receiver.internals.ConsumerEventLoop -- Emitting 10 records, requested now 0
08:36:58.768 [reactive-kafka-test-1-1] INFO TestMain -- key: null, value: 31-7a4b04d2-eb7c-4b59-a241-ca5d4055b2b4
...
08:36:58.768 [reactive-kafka-test-1-1] INFO TestMain -- key: null, value: 40-3b6b0504-695f-44c3-9182-8daa1b3406c3
...
// poll: 40, commit: 43 -> commit: 54
08:36:58.770 [reactive-kafka-test-1-1] INFO LoggingCommitInterceptor -- onCommit: commit-test-1-0-3854
// poll: 40, commit: 54 -> commit: 50
08:36:58.770 [reactive-kafka-test-1-1] INFO LoggingCommitInterceptor -- onConsume: commit-test-1-0-3840,commit-test-1-0-3841,commit-test-1-0-3842,commit-test-1-0-3843,commit-test-1-0-3844,commit-test-1-0-3845,commit-test-1-0-3846,commit-test-1-0-3847,commit-test-1-0-3848,commit-test-1-0-3849
08:36:58.770 [reactive-kafka-test-1-1] DEBUG reactor.kafka.receiver.internals.ConsumerEventLoop -- Emitting 10 records, requested now 0
08:36:58.770 [reactive-kafka-test-1-1] DEBUG reactor.kafka.receiver.internals.ConsumerEventLoop -- onRequest.toAdd 1, paused false
08:36:58.770 [reactive-kafka-test-1-1] INFO TestMain -- key: null, value: 41-7dbe2748-ff08-4035-bd4f-c183f3e15018
...
08:36:58.771 [reactive-kafka-test-1-1] INFO TestMain -- key: null, value: 50-f350dc4b-70b6-4746-b625-653103dfd6f6
...
// poll: 50, commit: 54 -> commit: 65
08:36:58.772 [reactive-kafka-test-1-1] INFO LoggingCommitInterceptor -- onCommit: commit-test-1-0-3865
// poll: 50, commit: 65 -> poll: 60
08:36:58.773 [reactive-kafka-test-1-1] INFO LoggingCommitInterceptor -- onConsume: commit-test-1-0-3850,commit-test-1-0-3851,commit-test-1-0-3852,commit-test-1-0-3853,commit-test-1-0-3854,commit-test-1-0-3855,commit-test-1-0-3856,commit-test-1-0-3857,commit-test-1-0-3858,commit-test-1-0-3859
08:36:58.773 [reactive-kafka-test-1-1] DEBUG reactor.kafka.receiver.internals.ConsumerEventLoop -- Emitting 10 records, requested now 0
08:36:58.773 [reactive-kafka-test-1-1] DEBUG reactor.kafka.receiver.internals.ConsumerEventLoop -- onRequest.toAdd 1, paused false
08:36:58.773 [reactive-kafka-test-1-1] INFO TestMain -- key: null, value: 51-3aabfb11-860a-419e-b712-88fd9d268e73
08:36:58.773 [reactive-kafka-test-1-1] INFO TestMain -- key: null, value: 52-0257c5c5-5d9f-4f09-a49f-7a9e71fd6bff
08:36:58.773 [reactive-kafka-test-1-1] INFO TestMain -- key: null, value: 53-a28607e5-bf88-4434-b41a-273335ad257c
08:36:58.773 [reactive-kafka-test-1-1] INFO TestMain -- key: null, value: 54-9d74c852-2a00-41d4-82c8-78565b1d52fb
08:36:58.775 [reactive-kafka-test-1-1] ERROR TestMain -- error on consume
java.lang.RuntimeException: prefix error !!
	at TestMain.errorByPrefix(TestMain.java:51)
	at TestMain.lambda$subscribeAtMostOnce$4(TestMain.java:39)
...

REFERENCE

https://github.com/apache/kafka/tree/3.4

Kafka Consumer #3 Consume 로직

북극곰은콜라 — Wed, 21 Jun 2023 18:15:41 +0900

개요

Consum 과정은 polling(fetch) + commit offset으로 볼 수 있다.
Broker로부터 Date를 가져와서 처리 후 처리된 offset만큼 commit하는 과정이다.
- kafkaConsumer가 initialize 하면서 Broker로 부터 커밋된 offset 정보를 받아온다.
- polling을 통해 Data를 받는다.
- commit을 통해 offset을 올린다.

1. Fetch Offset

1. poll 호출을 받으면 우선 모든 구독된 토픽/파티션에 offset이 있는지 확인한다.
2. 만약 하나라도 offset 정보가 없다면 resfresh offset 로직이 동작한다.
3. ConsumerCoordinator는 OffsetFetch Reuqest를 만들고, future에 대한 handler를 등록한다.
4. Request 객체로 ConsumerNetworkClient에게 send 요청을 한다.
5. 그 후 ConsumerCoordinator에게 리턴하고, ConsumerCoordinator는 NetworkClient의 response가 올 때 까지 block 됩니다.
6. networkClient는 Broker와 통신을 하고 응답을 등록된 handler를 통해 future 객체에 offset을 세팅합니다.
7. coordinator는 future에서 offset을 받아서 구독 정보에 해당 offset 정보를 세팅하고 리턴합니다.
8. 이후 polling 프로세스로 넘어갑니다.

OffsetFetchRequestData (SCHEMA_8)

name	type	Desc
groups	List<Group>	Each group we would like to fetch offsets for
group.group_id	String	The group ID.
group.topics	List<Topic>	Each topic we would like to fetch offsets for, or null to fetch offsets for all topics.
Topic.name	String	The topic name.
Topic.partition_indexes	List<Integer>	The partition indexes we would like to fetch offsets for.
require_stable	boolean	Whether broker should hold on returning unstable offsets but set a retriable error code for the partitions.

2-1. Polling

1. kafkaConsumer는 poll이 호출되면, Fetcher에게 Fetch된 데이터를 달라고 한다.
2. Fetcher는 이미 Fetch 된 데이터를 maxPollRecords 만큼 반환한다.
- 부족하거나 없다면 Empty 반환
3. kafkaConsumer는 리턴된 Fetch를 확인하여, empty인 경우 Fetcher에게 Fetch(sendFetch)를 호출한다.
4. Fetcher는 sendFetch가 호출되면, 설정 및 파티션 할당 정보로 Fetch Reuquest를 구성하여 ConsumernetworkClient의 send()를 호출
- Fetcher는 send()호출을 하면서, future에 success 및 fail응답에 대한 listener를 작성
- KafkaConsumer는 ConsumerNetworkClient에게 poll()을 호출하여, 응답을 받을 때 까지 Block
5. ConsumerNetworkClient는 Broker에게 Fetch request 요청
- ConsumerNetworkClient는 요청 후 fetchRequest(network)가 실행되는 쓰레드가 block 됨
6. Broker에게 응답을 받으면, Fetcher가 작성한 handler가 실행 됨

2-2. Fetch

주요 옵션

Option	Desc
fetch.min.bytes	fetch 시 브로커에게 최소한 fetch.min.bytes 값만큼 데이터를 요청 반환할 만큼 데이터가 충분하지 않다면 브로커는 데이터가 누적되길 기다린다. default 1
fetch.max.wait.ms	브로커가 Fetch API 요청을 받았을 때 fetch.min.bytes 값만큼 데이터가 없는 경우 응답을 주기까지 최대로 기다릴 시간 default 500ms
fetch.max.bytes	Fetch API 요청에 대해 브로커가 반환해야 하는 최대 데이터 크기이다. 다만 첫 번째 파티션의 첫 번째 메시지가 이 값보다 크다면 컨슈머가 계속 진행될 수 있도록 데이터가 반환된다. 브로커가 허용하는 최대 메시지 크기는 message.max.bytes와 max.message.bytes를 통해 설정한다. default 52428800(50MiB)

FetchRequestData (SCHEMA_13)

name	type	Desc
cluster_id	COMPACT_NULLABLE_STRING	The clusterId if known. This is used to validate metadata fetches prior to broker registration.
replica_id	INT32	The broker ID of the follower, of -1 if this request is from a consumer.
max_wait_ms	INT32	The maximum time in milliseconds to wait for the response.
min_bytes	INT32	The minimum bytes to accumulate in the response.
max_bytes	INT32	The maximum bytes to fetch. See KIP-74 for cases where this limit may not be honored.
isolation_level	INT8	This setting controls the visibility of transactional records. Using READ_UNCOMMITTED (isolation_level = 0) makes all records visible. With READ_COMMITTED (isolation_level = 1), non-transactional and COMMITTED transactional records are visible. To be more concrete, READ_COMMITTED returns all data from offsets smaller than the current LSO (last stable offset), and enables the inclusion of the list of aborted transactions in the result, which allows consumers to discard ABORTED transactional records
session_id	INT32	The fetch session ID.
session_epoch	INT32	The fetch session epoch
topics	[{topic_id, partitionDatas}, …]	The topics to fetch.
forgotten_topics_data	[{topic_id, partitionDatas}, …]	In an incremental fetch request the partitions to remove.
rack_id	COMPACT_STRING	Rack ID of the consumer making this request
partitionData.partition	INT32	The partition index.
partitionData.current_leader_epoch	INT32	The current leader epoch of the partition.
partitionData.fetch_offset	INT64	The message offset.
partitionData.last_fetched_epoch	INT32	The epoch of the last fetched record or -1 if there is none
partitionData.log_start_offset	INT64	The earliest available offset of the follower replica. The field is only used when the request is sent by the follower.
partitionData.partition_max_bytes	INT32	The maximum bytes to fetch from this partition. See KIP-74 for cases where this limit may not be honored.

FetchResponseData (SCHEMA_13)

name	type	Desc
throttle_time_ms	INT32	The duration in milliseconds for which the request was throttled due to a quota violation, or zero if the request did not violate any quota.
error_code	INT16	The top level response error code.
session_id	INT32	The fetch session ID, or 0 if this is not part of a fetch session.
responses	[{topic_id, partitionDatas}, …]	The response topics.

partitionData에 Records 가 있다.

3. Commit Offset

1. commit 발생 시 ConsumerCoordinator의 commitOffset()을 호출 한다.
2. ComsumerCoordinator는 request 객체를 생성하고, response에 대한 handler를 등록한다.
3. ComsumerCoordinaor는 ConsumerNetworkClient의 send()를 호출하고, poll()을 통해 Broker response가 올 때 까지 Block 된다.
4. Response가 오면, handler를 통해 offset이 extract하고 interceptors의 onCommit()을 실행한다.

SyncCommit vs AsyncCommit

Sync는 실패시 기본적으로 retry정책에 따라 retry 수행
Async는 retry 정책을 onFailure에 직접 구현해야 함

OffsetCommitRequestData (SCHEMA_8)

name	type	Desc
group_id	String	The unique group identifier.
generation_id	int	The generation of the group.
member_id	String	The member ID assigned by the group coordinator.
group_instance_id	String	The unique identifier of the consumer instance provided by end user.
topics	List<Topic>	The topics to commit offsets for.
name	String	The topic name.
partitions	List<Partitions>	Each partition to commit offsets for.
partition_index	int	The partition index.
committed_offset	int	The message offset to be committed.
committed_leader_epoch	int	The leader epoch of this partition.
committed_metadata	String	Any associated metadata the client wants to keep.

REFERENCE

#2 EasyCalendar Flutter 구현

북극곰은콜라 — Tue, 20 Jun 2023 18:31:30 +0900

짤막 흥보: 호구홍시 조대봉 (인스타 툰)

개요

Flutter로 구현한 Client Web 관련 리뷰
개발 중 이슈사항 리뷰

Project Structure

main: main class
main_state_page: 시작페이지, 로그인 체크
calendar_page: 일정 확인 / 등록 페이지
main_exception: custom exception
network_client: REST 요청 관련 모듈

리뷰

1. main class를 분리하는 의미가 없는듯하다.
2. main_state_page의 의미가 많이 퇴색되었다. Google 인증도 main_state_page에 넣었어야 했다.
3. 구현해 보니, 각 page에는 widget 생성 관련 로직만 넣고, 비즈니스? 로직은 외부로 빼는 것이 좋을 것 같다.

Library

flex_color_scheme: 7.0.4
getwidget: 3.1.1
flutter_secure_storage: ^8.0.0
dio: 5.1.1
flutter_web_auth: 0.5.0

리뷰

flex_color_scheme를 통해 스킨색에 대한 컨트롤은 어느정도 구현되었다.
getwidget으로 UI 컴포넌트를 만들었는데, 딱히 이쁘진 않음...
flutter_secure_storage는 토큰정보를 저장하기 위해 도입했으며, 적절
dio는 REST 요청 등 활용되는 Library인데, 기본 모듈보다 좋은 점은 찾지 못함
flutter_web_auth는 OAuth2.0 Client를 구성하기 위해서 도입했으며, 가장 간단하게 client 연동을 구현했다.

이슈

1. OAuth2.0 Client Library 선정

Flutter는 기본적으로 Native App을 위한 크로스 플랫폼 프레임워크이다.
많은 라이브러리가 App을 위해 개발되었으며, Web은 아니다.
OAuth2.0 Library 또한 대부분 Web을 제대로 지원하지 않았다. (WebView가 Web에 없기 때문)
선정된 라이브러리는 Web에서 사용가능한 우회방식을 제시해준다.

사용 예

// API 사용
Future<String> getMainAuthorizationToken() async {
    return await FlutterWebAuth.authenticate(
        url: '$_loginPageUrl?$_loginPageQueryParams',
        callbackUrlScheme: _callbackUrlScheme);
}

// redirect 된 access_token parameter 추출
var accessToken = Uri.parse(result).queryParameters['access_token'];

redirect 경로에 auth.html 추가

<!DOCTYPE html>
<html lang="kr">
<head>
  <meta charset="UTF-8">
    <title>Authentication complete</title>
    <p>Authentication is complete. If this does not happen automatically, please close the window.</p>
</head>
<body>

<script>
    window.opener.postMessage({
        'flutter-web-auth': window.location.href
    }, window.location.origin);
    window.close();
</script>
</body>
</html>

redirect 되면 auth.html로 오게 만들고, 해당 페이지에서 기존 페이지로 돌아오게 하며, 라이브러리 사용법에 따라서 parameter를 받아서 사용한다.

2. Dynamic Widget 생성

Future<List<Widget>> _createCalendarEvent() async {
    _selectedCalendarId = await networkClient.getCalendarId();
    List<dynamic> res = await networkClient.getCalendarEvents(_selectedCalendarId);
    res.sort((a, b) => _compareStartTime(a, b));
    final targetEvents = res.sublist(0, 4);
    for (Map<String, dynamic> event in targetEvents) {
      Map<String, String> start = Map.from(event["start"]);
      _addCalendarEvent(event["id"], start["dateTime"]!, event["summary"]);
    }

    return eventList.values.toList();
}

위와 같이 Future로 Widget이 생성되는 경우, Widget 생성 또한 이에 대응해야 한다.

FutureBuilder(
  future: _createCalendarEvent(),
  initialData: const [Text("data loading 중")],
  builder: (context, snapshot) {
    return Column(
      key: UniqueKey(),
      mainAxisAlignment: MainAxisAlignment.start,
      children: snapshot.requireData,
    );
  },
),

FutureBuilder를 통해 Future를 받을 때 Widget을 구성해주는 Widget이 있다.

3. Web build with prefix

배포되는 환경에서는, url에 prefix가 붙어야 했다.
flutter navigate시 prefix가 붙어서 할 수 있도록 build 시 args를 추가했다.

flutter build web --base-href "/easycal/"

총평

첫 Flutter 프로젝트여서, 기능구현에 초점을 맞췄다.
내부 구현 구조가 대규모로 변경되는 사항이 많아서, 프로젝트는 유지보수에 어려움이 있을 것으로 예상된다.
특히 계산로직과 widget 생성 로직 등이 뒤섞여있는 부분이 안타깝다.
front 단 코딩에 쫌 더 생각을 해보고 진행해야겠다.

Kafka Consumer #2 Partition Assignor Strategy

북극곰은콜라 — Thu, 15 Jun 2023 19:37:01 +0900

개요

Kafka Consumer에 대한 세부 조사
#1 글에 이어서

Consumer Partition Assignor

파티션을 할당하기 위한 Interface
consumer 설정의 partition.assingment.strategy 로 구현체를 세팅할 수 있다.
ConsumerGroup의 정보와, Topic의 Partition 정보를 받아서, 배분한다.
5개 정도의 구현체가 있다.
Custom한 전략도 구현 가능하다.

Consumer Rebalancing 전략은 Broker의 Coordinator가 아닌 Consumer들이 정한다.
따라서 Rebalance에서 발생하는 모든 오퍼레이션은 Consumer (Leader)가 관장하여, coordinator는 leader가 오퍼레이션 하기 위한 브로커 역할을 한다.

Range Assignor

기본 partition Assignor
파티션과 컨슈머를 사전순으로 정렬하고 파티션을 컨슈머에게 순차적으로 할당하는 방식
토픽별로 배분 한다.

RoundRobin Assignor

파티션을 전체적으로 sort하고 컨슈머를 번갈아가면서 매핑
Reassign 후 Consumer ↔︎ Partition 간의 매핑이 달라질 수 있다.
Consumer Group내 Consumer들이 같은 토픽들을 subscribe 할 때 효율적

Sticky Assignor

기본 배분 로직은 RoundRobin과 같음

init:

RoundRobin After Consumer1 Dead

Sticky After Consumer1 Dead

최대한 균등한 할당을 보장 (Consumer의 Partition 수의 차이는 최대 1)
가본적으로 Round Robin
→ A +2 <= B 인경우 A의 Topic의 남은 Partition은 B에 할당 불가
Reassign시 최대한 기존 할당을 유지
우선순위: 1. 균등 2. 기존 유지

CooperativeStickyAssignor (Kafka ver >= 2.4, stable in 2.5)

동작은 StickyAssignor와 동일하지만
위 3가지에 사용되는 EAGER rebalance을 사용 안함.
목적은 Consumer의 다운타임 최소화
STW 관련 설명은 후술

EAGER rebalance

1. Consumer의 변동 감지
2. 모든 파티션의 할당을 취소한다.
3. 파티션 재할당 전략을 통해 재 할당

Cooperative reablance

1. Consumer의 변동 감지
2. 모든 Comsumer는 자신의 구독정보 및 선호도(이전 할당 이력 등)를 그룹 코디네이터로 전송
3. 그룹 코디네이터는 정보를 조합해 consumer 리더에게 전송
4. 리더는 현 파티션 정보를 고려해 할당 정보를 생성한다.
5. 재할당 전략으로 불필요한 재할당 (Sticky) 및 선호도 (이전 할당 이력)을 최대한 반영

StreamsPartitionAssignor

Kafka Streams 에서 사용하는 할당 전략
자세한 사항은 추후 조사

Rebalance와 STW

기본 Reablance 상황의 STW

Consumer 3가 join 하는 상황이다.
1. consumer → coordinator: 참가 요청
2. coordinator → 기존 consumers: heartbeat 또는 offsetFetch(consume) 의 response로 rebalance 시작을 noti
3. rebalance를 수신받은 consumer1, 2 는 STW
4. consumers → coordinator: joinGroupRequest
5. coordinator → consumers: leader에게 전체 정보, 각 컨슈머에게 memberId 정보를 response로 전달
6. consumer ↔︎ coordinator: 지속적으로 Sync Group을 진행하면서, rebalancing 완료를 기다림
7. Rebalance 종료 후 STW 해제

Rebalance 불합리

위 상황에서 Consumer 1,2의 p0, p1는 rebalance 전후로 변화가 없다.
따라서 p0의 경우 STW에서 제외하는 것이 효율적이다.
또한 Range, RoundRobin Assignor에서는 p0의 state 또한 재구성하는 오버헤드가 있다.

CooperativeStickyAssignor를 통한 STW 최소화

Step 1

신규 Consumer 3가 Join하는 상황이다.
기존 Consumer 1,2는 join → sync를 수행하지만, STW는 하지 않는다.
Sync를 통해서 자신이 제외해야할 파티션을 결정한다.

Step 2

Step 1에서 결정된 제외할 파티션을 revoke 한다.
다시 Join, Sync 프로세스를 통해 Consumer3가 p2를 할당 받으면서 합류합니다.

REFERENCE

Kafka Consumer #1 Startup / Rebalance Flow

북극곰은콜라 — Wed, 14 Jun 2023 19:22:47 +0900

개요

Kafka Consumer에 대한 세부 조사
Kafka Client와 Kafka Broker의 rebalance flow 및 requset / response data 조사
Kafka Consumer Assignor 관련 조사
Kafka Consumer STW 관련 조사

Consumer Startup

Group Coordinator 란

Kafka Broker에서 Consumer Group을 관리하기 위한 컴포넌트
기본적으로 Consumer Group 별로 존재
Cluster내 임의의 broker에 생성 됨
Consumer Group내 member의 변동을 감지하고 Rebalance를 관장
kafka topic을 이용해서 group의 metadata를 유지

총 3가지 단계로 coordinator와 consumer간의 협상이 일어난다.
1. start group: coordinator를 찾는 단계
2. join group: coordinator를 통해 consumer가 group에 join 하는 단계
3. sync group: join된 group에서 토픽 / 파티션을 sync하는 단계

1. Start Group

일반적으로 Consumer가 Startup 할 시 group.id 를 기반으로 findCoordinator 요청을 한다.
broker는 group.id를 기반으로 group coordinator를 생성할 브로커를 선정 및 생성하고 해당 coordinator의 endpoint를 응답

findCoordinatorRequestData (SCHEMA_4)

name	type	Desc
key_type	INT8	The coordinator key type. (Group, transaction, etc.)
coordinator_keys	String	The coordinator keys.

findCoordinatorResponseData (SCHEMA_4)

name	type	Desc
throttle_time_ms	INT32	The duration in milliseconds for which the request was throttled due to a quota violation, or zero if the request did not violate any quota.
coordinators	list	Each coordinator result in the response
coordinatorData.key	String	The coordinator key.
coordinatorData.node_id	INT32	The node id.
coordinatorData.host	String	The host name.
coordinatorData.port	INT32	The port.
coordinatorData.error_code	INT16	The error code, or 0 if there was no error.
coordinatorData.error_message	String	The error message, or null if there was no error.

2. Join Group

consumer들은 group coordinator로 join 요청 (구독 정보 포함)
group coordinator는 그룹에서 최초로 join 요청을 보낸 consumer를 leader로 선정
(최초 생성 시) Consumer Group의 offset 정보 등 group 관련 데이터 생성
consumer에게 memberId를 응답, leader에게는 memberList 및 subscription 정보 전달

JoinGroupRequestData (SCHEMA_8)

name	type	Desc
group_id	String	The group identifier.
session_timeout_ms	int	The coordinator considers the consumer dead if it receives no heartbeat after this timeout in milliseconds.
rebalance_timeout_ms	int	The maximum time in milliseconds that the coordinator will wait for each member to rejoin when rebalancing the group.
member_id	String	The member id assigned by the group coordinator.
group_instance_id	String	The unique identifier of the consumer instance provided by end user.
protocol_type	String	The unique name the for class of protocols implemented by the group we want to join. (consumer, connect)
reason	String	The reason why the member (re-)joins the group.
protocols	list<Protocol>	The list of protocols that the member supports. (Partition Assignment)
protocol.name	String	The protocol name. (Assigner Name)
protocol.metadata	bytes	The protocol metadata. (Subscription 객체를 serialize)

JoinGroupResponseData (SCHEMA_9)

name	type	Desc
throttle_time_ms	int	The duration in milliseconds for which the request was throttled due to a quota violation, or zero if the request did not violate any quota.
error_code	int	The error code, or 0 if there was no error.
generation_id	int	The generation ID of the group.
protocol_type	String	The group protocol name.
protocol_name	String	The group protocol selected by the coordinator.
leader	String	The leader of the group.
skip_assignment	boolean	True if the leader must skip running the assignment.
member_id	String	The member ID assigned by the group coordinator.
members	List<Member>
member.member_id	String	The group member ID.
member.group_instance_id	String	The unique identifier of the consumer instance provided by end user.
member.metadata	bytes	The group member metadata.

3. SyncGroup

Consumer Group Leader는 구독할 파티션에 대한 전략을 수행
각 consumer member가 구독할 파티션 정보를 coordinator로 전달
다른 consumer들은 coordinator로 지속적으로 자신이 구독할 파티션에 대한 sync 요청을 보냄
consumer partition assign 전략은 다음편에 자세히 설명

SyncGroupRequestData (SCHEMA_5)

name	type	Desc
group_id	String	The unique group identifier.
generation_id	int	The generation of the group.
member_id	String	The member ID assigned by the group.
group_instance_id	String	The unique identifier of the consumer instance provided by end user.
protocol_type	String	The group protocol type.
protocol_name	String	The group protocol name.
assignments	List	Each assignment. (각 member 별 assign 된 결과 리스트)
assignments.member_id	Strring	The ID of the member to assign.
assignments.assignment	bytes	The member assignment. (assignment 결과를 serialize)

SyncGroupResponseData (SCHEMA_5)

name	type	Desc
throttle_time_ms	int	The duration in milliseconds for which the request was throttled due to a quota violation, or zero if the request did not violate any quota.
error_code	int	The error code, or 0 if there was no error.
protocol_type	String	The group protocol type. (consumer, connect)
protocol_name	String	The group protocol name. = assignment.getName()
assignment	bytes	The member assignment.

Consumer Rebalance

Rebalancing 조건

1. 인스턴스가 timeout안에 heartbeat 실패하여 group에서 제외 되었을 때
2. 인스턴스가 group에 추가되었을 때
3. 구독중인 토픽에 파티션이 추가 되었을 때
4. *로 topic을 subscribe 중에, 조건에 맞는 topic이 추가되었을 때
5. consumer group이 시작 될 때

Rebalance noti

heartbeat response 또는 offsetFetch response를 통해 consumer에게 notify한다.

REFERENCE

Expand Kafka Cluster

북극곰은콜라 — Tue, 13 Jun 2023 19:12:59 +0900

개요

Kafka Cluster를 확장할 시 발생하는 이펙트에 대한 조사

Broker Data Reassignment Strategy

단순 Broker Add

기본적으로 Broker가 추가되는 경우 기존 topic 및 Data에 대해서는 아무런 작업을 진행하지 않는다. 앞으로 추가되는 topic에 대해서 신규 브로커가 포함된 형태로 Cluster가 동작한다.

Migrate data to new Broker

수동적으로 트리거링하여 기존 데이터를 새 Broker에 마이그레이션 할 수 있다.
시스템 중단 없이 작업 가능한 방법
내부적으로 다음 프로세스를 적용하여 마이그레이션이 진행됩니다.
1. 신규 Broker를 기존 파티션의 follower로 지정
2. 신규 Broker는 기존 파티션의 모든 Data를 replicate
3. replication 완료 후 신규 브로커는 해당 topic의 ISR (In-Sync-Replica)로 편입
3. ISR중 누군가는 해당 topic의 replication을 delete

Data Migration Tool

파티션재할당을 위해서는 Reassignment Tool을 활용 (kafka-reassign-partitions.sh)
모든 작업은 관리자가 수동으로 진행
Tool의 3가지 옵션 (단계)
1. --generate: Topic과 Broker list를 지정하여, target Broker들에 Topic들을 재할당 합니다.
2. --execute: reassignment-json-file을 통해 계획에 따라 재할당 진행
3. --verify: execute의 진행 상황을 확인
generate를 통해 토픽과 브로커의 리스트를 지정하면, kafka tool이 execute plan을 생성합니다.

reassign topics 선정

> cat topics-to-move.json
{"topics": [{"topic": "foo1"},
            {"topic": "foo2"}],
"version":1
}

reassign 계획 생성

> bin/kafka-reassign-partitions.sh --bootstrap-server localhost:9092 --topics-to-move-json-file topics-to-move.json --broker-list "5,6" --generate
Current partition replica assignment

{"version":1,
"partitions":[{"topic":"foo1","partition":0,"replicas":[2,1]},
              {"topic":"foo1","partition":1,"replicas":[1,3]},
              {"topic":"foo1","partition":2,"replicas":[3,4]},
              {"topic":"foo2","partition":0,"replicas":[4,2]},
              {"topic":"foo2","partition":1,"replicas":[2,1]},
              {"topic":"foo2","partition":2,"replicas":[1,3]}]
}

Proposed partition reassignment configuration

{"version":1,
"partitions":[{"topic":"foo1","partition":0,"replicas":[6,5]},
              {"topic":"foo1","partition":1,"replicas":[5,6]},
              {"topic":"foo1","partition":2,"replicas":[6,5]},
              {"topic":"foo2","partition":0,"replicas":[5,6]},
              {"topic":"foo2","partition":1,"replicas":[6,5]},
              {"topic":"foo2","partition":2,"replicas":[5,6]}]
}

execute

> bin/kafka-reassign-partitions.sh --bootstrap-server localhost:9092 --reassignment-json-file expand-cluster-reassignment.json --execute
Current partition replica assignment

{"version":1,
"partitions":[{"topic":"foo1","partition":0,"replicas":[2,1]},
              {"topic":"foo1","partition":1,"replicas":[1,3]},
              {"topic":"foo1","partition":2,"replicas":[3,4]},
              {"topic":"foo2","partition":0,"replicas":[4,2]},
              {"topic":"foo2","partition":1,"replicas":[2,1]},
              {"topic":"foo2","partition":2,"replicas":[1,3]}]
}

Save this to use as the --reassignment-json-file option during rollback
Successfully started partition reassignments for foo1-0,foo1-1,foo1-2,foo2-0,foo2-1,foo2-2

verify

> bin/kafka-reassign-partitions.sh --bootstrap-server localhost:9092 --reassignment-json-file expand-cluster-reassignment.json --verify
Status of partition reassignment:
Reassignment of partition [foo1,0] is completed
Reassignment of partition [foo1,1] is still in progress
Reassignment of partition [foo1,2] is still in progress
Reassignment of partition [foo2,0] is completed
Reassignment of partition [foo2,1] is completed
Reassignment of partition [foo2,2] is completed

REFERENCE

- https://kafka.apache.org/documentation/#basic_ops_cluster_expansion

Webclient 동작 원리 및 Configuration

북극곰은콜라 — Tue, 30 May 2023 13:21:21 +0900

개요

Webclient는 Spring Webflux에 포함된 외부 요청 / 응답에 대한 Handling을 담당하는 모듈이다.
기존 RestTemplate의 요청 <-> 응답 사이의 동기성을 해결하고, 보다 효과적으로 서버 리소스를 사용하기 위해 등장했다.
내부적으로 비동기적으로 구성되어 있으며, 구현은 Spring Webflux를 활용했다.

WebClient 사용 분석

WebClient는 총 4단계로 요청 -> 응답 처리를 추상화하였다.
Http Config → Reqeust Config → Exchange → Response Handling
각각
- http 기본 설정 (socket 설정 포함)
- 요청 정의
- 발송
- 응답 처리

1. Build with Config

WebClient.builder()
  ....
  .build()

DefaultWebClientBuilder

public WebClient build() {
  ClientHttpConnector connectorToUse = this.connector != null ? this.connector : this.initConnector();
  ExchangeFunction exchange = this.exchangeFunction == null ? ExchangeFunctions.create(connectorToUse, this.initExchangeStrategies()) : this.exchangeFunction;
  ExchangeFunction filteredExchange = this.filters != null ? (ExchangeFunction)this.filters.stream().reduce(ExchangeFilterFunction::andThen).map((filter) -> {
    return filter.apply(exchange);
  }).orElse(exchange) : exchange;
  HttpHeaders defaultHeaders = this.copyDefaultHeaders();
  MultiValueMap<String, String> defaultCookies = this.copyDefaultCookies();
  return new DefaultWebClient(filteredExchange, this.initUriBuilderFactory(), defaultHeaders, defaultCookies, this.defaultRequest, new DefaultWebClientBuilder(this));
}

사실상 Req ↔︎ Res 전 구간의 설정 및 설정 구현체의 reference를 가지고 있다.
구현체 내부적으로 Config를 가지고 있으며,
Config를 통해 동일한 설정을 가진 webclient builder를 만들 수 있다. (mutate)
기본적으로 동작할 설정을 가진 구현체를 생성하여, 재활용한다.
(WebClient는 builder를 멤버 가지고 있으며 mutate 시 해당 builder를 리턴해서 재사용성을 높였다)

2. Request 준비

Request를 생성하기 위한 각종 정보를 세팅하는 작업
Uri, Header, Body 등 Request에 필요한 정보를 interface 형태로 spec을 정의하고, 최종 구현체가 모든 정보를 가지고 전달할 수 있게 한다.

3. Exchange to get ResponseSpec

public WebClient.ResponseSpec retrieve() {
  return new DefaultResponseSpec(this.exchange(), this::createRequest);
}

public Mono<ClientResponse> exchange() {
  ClientRequest request = this.inserter != null ? this.initRequestBuilder().body(this.inserter).build() : this.initRequestBuilder().build();
  return Mono.defer(() -> {
    Mono<ClientResponse> responseMono = DefaultWebClient.this.exchangeFunction.exchange(request).checkpoint("Request to " + this.httpMethod.name() + " " + this.uri + " [DefaultWebClient]").switchIfEmpty(DefaultWebClient.NO_HTTP_CLIENT_RESPONSE_ERROR);
    if (this.contextModifier != null) {
      responseMono = responseMono.contextWrite(this.contextModifier);
    }

    return responseMono;
  });
}

private HttpRequest createRequest() {
      return new HttpRequest() {
        private final URI uri = DefaultRequestBodyUriSpec.this.initUri();
        private final HttpHeaders headers = DefaultRequestBodyUriSpec.this.initHeaders();

        public HttpMethod getMethod() {
          return DefaultRequestBodyUriSpec.this.httpMethod;
        }

        public String getMethodValue() {
          return DefaultRequestBodyUriSpec.this.httpMethod.name();
        }

        public URI getURI() {
          return this.uri;
        }

        public HttpHeaders getHeaders() {
          return this.headers;
        }
      };
    }

ClientResponse을 받는 메서드
1. Request Spec으로부터 정보를 받아 ClientRequest를 생성
2. ExchangeFuction을 통해 exchange 수행 (ExchangeFuction은 후술)
3. ResponseSpec 생성 (Exchange 결과(Mono) + Request 객체)

4. Response Handling

ClientResponse를 처리할 수 있는 메서드를 지원한다.

Configuration

Builder Method	Desc	Example
baseUrl(String baseUrl)	기본 Url 세팅	.baseUrl("http://localhost")
defaultUriVariables(Map<String, ?> defaultUriVariables)	기본 Uri 변수 세팅 최종 URL의 {}값을 치환	.defaultUriVariables(Map.of("path1", "값1", "query1", "값2"))
uriBuilderFactory(UriBuilderFactory uriBuilderFactory)	내부적으로 사용되는 BuilderFactory를 customize	.uriBuilderFactory(new DefaultUriBuilderFactory())
defaultHeader(String header, String... values)	기본 Header 세팅	.defaultHeader(HttpHeaders.CONTENT_TYPE, MediaType.APPLICATION_JSON_VALUE)
defaultHeaders(Consumer<HttpHeaders> headersConsumer)	Consumer를 accept(this.initHeaders())	Consumer<HttpHeaders> headersConsumer = httpHeaders -> httpHeaders.setContentType(MediaType.APPLICATION_JSON); WebClient.builder() .defaultHeaders(headersConsumer)
defaultCookie(String cookie, String... values)	기본 Cookie 세팅	.defaultCookie("cookie_key", "cookie_value")
defaultCookies(Consumer<MultiValueMap<String, String>> cookiesConsumer)	cookiesConsumer.accept(this.initCookies());	Consumer<MultiValueMap<String,String>> cookiesConsumer = map -> map.add("defaultCookie", "value"); WebClient.builder() .defaultCookies(cookiesConsumer)
defaultRequest(Consumer<RequestHeadersSpec<?>> defaultRequest)	defaultRequest가 있으면 andThen으로 추가 없으면 defaultRequest로 세팅	Consumer<WebClient.RequestHeadersSpec<?>> defaultRequest = requestHeadersSpec -> requestHeadersSpec.attribute("test", "q"); WebClient.builder() .defaultRequest(defaultRequest)
filter(ExchangeFilterFunction filter)	webClient용 filter 추가 request / response handling	.filter(ExchangeFilterFunction.ofRequestProcessor(this::loggingRequestInfo)) // 로깅용 필터를 구현하여 add
filters(Consumer<List<ExchangeFilterFunction>> filtersConsumer)	Filter Consumer를 accept(this.initFilters())
clientConnector(ClientHttpConnector connector)	ClientHttpConnector 세팅 자세한 사항은 후술	.clientConnector(new ReactorClientHttpConnector(HttpClient.create()))
codecs(Consumer<ClientCodecConfigurer> configurer)	configure Encoding / Decoding clientCodecConfigurer를 통해 register 자세한 사항은 후술	.codecs( clientCodecConfigurer -> { clientCodecConfigurer.customCodecs().register(new Jackson2JsonDecoder()); clientCodecConfigurer.customCodecs().register(new Jackson2JsonEncoder()); }
exchangeStrategies(ExchangeStrategies strategies)	exchange의 stratege를 세팅 자세한 사항은 후술
@Deprecated exchangeStrategies(Consumer<ExchangeStrategies.Builder> configurer)	deprecate
exchangeFunction(ExchangeFunction exchangeFunction)	connector와 strategies를 가진 ExchangeFuction을 세팅 자세한 사항은 후술
apply(Consumer<Builder> builderConsumer)	Consumer를 accept(this)	Consumer<WebClient.Builder> baseUrlToB = builder -> builder.baseUrl("b.com"); WebClient.builder() .baseUrl("a.com") .apply(baseUrlToB);

WebClient Components 분석

ClientConnector

public interface ClientHttpConnector {
  Mono<ClientHttpResponse> connect(HttpMethod method, URI uri, Function<? super ClientHttpRequest, Mono<Void>> requestCallback);
}

request 정보 + Callback Function을 받아서 Mono로 Response를 전달하는 method를 가진 interface
HTTP 통신의 최종 목적이 되는 메서드이다.

구현체들

구현체들 마다 차이가 있지만, 대부분 비슷한 로직을 가졌으며, 내부적으로 HttpClient 구현체가 다르다.
ex) ReactorClientHttpConnector → Netty의 HttpClient,
JettyClientHttpConnector → jetty.client의 HttpClient를 가진다

ClientCodecConfigurer

Encoder 및 Decoder를 세팅하기 위한 Config Interface
핵심은 추상클래스의 BaseCodecConfigurer의 멤버인 BaseDefaultCodecs, DefaultCustomCodecs를 Config 하는 기능 제공

세팅된 Reader와 Writer를 제공해 주는 핵심 메서드
모양을 보면 defaultCodec에 customCodec을 apply 해서 제공한다.

BaseDefaultCodecs

기본적으로 지원하는 코덱에 대한 세팅이 되어있는 클래스
특히 jackson2JsonDecoder, Encoder를 많이 사용하게 된다.

추가적으로 코덱 단에서 설정할 수 있는 부분이 있는데
maxInMemorySize(int size)
- Encode, Decode시의 Message의 최대크기를 정할 수 있다.
- default: 256KB
enableLoggingRequestDetails(boolean var1)
- Requset / Response에 대한 상세로깅을 활성화할 수 있음
- 기본적으로 Authorization Header 등 민감 정보가 올 수 있는 부분 때문에, default = false

DefaultCustomCodecs

BaseCodecConfigurer가 가진 내부 final 클래스
customCodec을 apply 하기 위해 일종의 custom encoder, decoder의 홀더 역할을 한다.
핵심 메서드인 private void addCodec(Object codec, boolean applyDefaultConfig)을 통해 readers와 writers를 세팅한다.

ExchangeFunction

ExchangeFunction interface

Request를 받아서 Response를 받아오는 작업의 interface
filter apply 메서드와 함께 구현해야 함

ExchangeFunctions

ExchangeFunction을 생성할 수 있는 Util 클래스
내부적으로 ExchangeFunction을 구현한 DefaultExchangeFunction을 가지고 있다.

DefaultExchangeFunction

Connector와 ExchangeStrategies를 가지고 있다.
connector를 통해 connect를 수행하고, exchangeStrategies를 통해 message read / write를 수행한다.
default로 logging이 false인데, strategies가 들어오면 전략에 동봉된 코덱을 확인

public Mono<ClientResponse> exchange(ClientRequest clientRequest) {
  Assert.notNull(clientRequest, "ClientRequest must not be null");
  HttpMethod httpMethod = clientRequest.method();
  URI url = clientRequest.url();
  return this.connector.connect(httpMethod, url, (httpRequest) -> {
    return clientRequest.writeTo(httpRequest, this.strategies);
  }).doOnRequest((n) -> {
    this.logRequest(clientRequest);
  }).doOnCancel(() -> {
    ExchangeFunctions.logger.debug(clientRequest.logPrefix() + "Cancel signal (to close connection)");
  }).onErrorResume(WebClientUtils.WRAP_EXCEPTION_PREDICATE, (t) -> {
    return this.wrapException(t, clientRequest);
  }).map((httpResponse) -> {
    String logPrefix = this.getLogPrefix(clientRequest, httpResponse);
    this.logResponse(httpResponse, logPrefix);
    return new DefaultClientResponse(httpResponse, this.strategies, logPrefix, httpMethod.name() + " " + url, () -> {
      return this.createRequest(clientRequest);
    });
  });
}

1. connector를 통해 connect 수행
- connect의 callback 메서드로 request와 strategies를 수행하도록 세팅
2. logging 및 Exception 처리 등록
3. map 체이닝으로 ClientResponse를 생성

Message Write

private static <M extends ReactiveHttpOutputMessage> Mono<Void> writeWithMessageWriters(
			M outputMessage, BodyInserter.Context context, Object body, ResolvableType bodyType, @Nullable ReactiveAdapter adapter) {

		Publisher<?> publisher;
		if (body instanceof Publisher) {
			publisher = (Publisher<?>) body;
		}
		else if (adapter != null) {
			publisher = adapter.toPublisher(body);
		}
		else {
			publisher = Mono.just(body);
		}
		MediaType mediaType = outputMessage.getHeaders().getContentType();
		return context.messageWriters().stream()
				.filter(messageWriter -> messageWriter.canWrite(bodyType, mediaType))
				.findFirst()
				.map(BodyInserters::cast)
				.map(writer -> write(publisher, bodyType, mediaType, outputMessage, context, writer))
				.orElseGet(() -> Mono.error(unsupportedError(bodyType, context, mediaType)));
	}

BodyInserters에서 Body를 write 할 때 MessageWriter 중 첫 번째 것을 사용한다.
fromValue → writeWithMessageWriters(…)

Message Read

private static <T, S extends Publisher<T>> S readWithMessageReaders(
			ReactiveHttpInputMessage message, BodyExtractor.Context context, ResolvableType elementType,
			Function<HttpMessageReader<T>, S> readerFunction,
			Function<UnsupportedMediaTypeException, S> errorFunction,
			Supplier<S> emptySupplier) {

		if (VOID_TYPE.equals(elementType)) {
			return emptySupplier.get();
		}
		MediaType contentType = Optional.ofNullable(message.getHeaders().getContentType())
				.orElse(MediaType.APPLICATION_OCTET_STREAM);

		return context.messageReaders().stream()
				.filter(reader -> reader.canRead(elementType, contentType))
				.findFirst()
				.map(BodyExtractors::<T>cast)
				.map(readerFunction)
				.orElseGet(() -> {
					List<MediaType> mediaTypes = context.messageReaders().stream()
							.flatMap(reader -> reader.getReadableMediaTypes(elementType).stream())
							.collect(Collectors.toList());
					return errorFunction.apply(
							new UnsupportedMediaTypeException(contentType, mediaTypes, elementType));
				});
	}

BodyExtractor에서 등록된 messageReader 중 첫 번째 reader를 통해 메시지를 Read 한다.
toMono / toFlux → readWithMessageReaders(…)

WebClient 간단 세팅 Template

WebClient.builder()
  .clientConnector(new ReactorClientHttpConnector(HttpClient.create()
      // SSL 인증서 무시 설정
      .secure(SslProvider.builder()
          .sslContext(SslContextBuilder.forClient().trustManager(InsecureTrustManagerFactory.INSTANCE))
          .defaultConfiguration(SslProvider.DefaultConfigurationType.NONE)
          // Handshake Timeout tjfwjd
          .handshakeTimeoutMillis(2000)
          .build())
      // DNS Resolver 설정
      .resolver(DefaultAddressResolverGroup.INSTANCE)    // Sets the JVM built-in resolver.
      // Connection Timeout 설정
      .option(ChannelOption.CONNECT_TIMEOUT_MILLIS, this.applicationProperties.getTcpClientConnectionTimeout())
      .doOnConnected(connection ->
          connection
              // ReadTimeout 설정
              .addHandlerLast(new ReadTimeoutHandler(this.applicationProperties.getTcpClientReadTimeout()))
              // WriteTimeout 설정
              .addHandlerLast(new WriteTimeoutHandler(this.applicationProperties.getTcpClientWriteTimeout())))))
  .exchangeStrategies(ExchangeStrategies.builder()
      .codecs(configurer -> {
          // Date Size 무제한 설정
          configurer.defaultCodecs().maxInMemorySize(-1);
          // 살세 로깅 enable
          configurer.defaultCodecs().enableLoggingRequestDetails(true);
      })
      .build())
  // MDC로 transactionId 넣는 설정
  .filter(mdcFilter)
  // Req, Res 로깅 필터 등록 설정
  .filter(ExchangeFilterFunction.ofRequestProcessor(WebClientConfig::loggingRequestInfo))
  .filter(ExchangeFilterFunction.ofResponseProcessor(WebClientConfig::loggingResponseInfo))
  .build();
  
  

private static  Mono<ClientRequest> loggingRequestInfo(final ClientRequest request) {
  StringBuffer sb = new StringBuffer();
  sb.append("Req 3rd > ").append(request.method())
      .append(", URI=").append(request.url())
      .append(", Header=").append(request.headers().isEmpty() ? "" : JsonUtil.buildJsonStr(request.headers()))
      .append(", Body=").append(JsonUtil.buildJsonStr(request.body()));

  log.info(sb.toString());

  return Mono.just(request);
}

private static Mono<ClientResponse> loggingResponseInfo(final ClientResponse response) {
  log.info("Res 3rd > {}", response.statusCode());
  return Mono.just(response);
}

private static final ExchangeFilterFunction mdcFilter = (request, next) -> {
  // here runs on main(request's) thread
  Map<String, String> map = MDC.getCopyOfContextMap();
  return next.exchange(request)
      .doOnEach(value -> {
        // here runs on reactor's thread
        if (map != null) {
          MDC.setContextMap(map);
        }
      });
};

핵심 요약

WebClient는 REST Client를 Webflux에 맞게 인터페이스 및 설정을 제공
WebClient Instance는 Immutable
mutate를 통해서 요청 / 응답 설정에 대한 커스텀만 하며, 기본적인 인스턴스는 하나다.
Http 이하 계층과, 비즈니스 부분이 분리될 수 있도록 설계됨 (Connector 설정이 되어있다면…)
WebClient는 총 4단계로 요청 → 응답이 처리를 추상화하였다
- Http Config → Reqeust Config → Exchange → Response Handling
HttpClientConnector는 최초 요청 시 Pool을 만든다. (Provider의 역할)
Timeout 설정은 총 5가지 정도 있음
- Connection Timeout
- Handshake Timeout
- Read Timeout
- Write Timeout
- Response Timeout
REST 요청 중 여러 구간에서 Handler를 달 수 있음
- Request 전 / 후
- Response 전 / 후
- Connection 전 / 후
- Serialize, Deserialize 시

REFERENCE

https://docs.spring.io/spring-framework/reference/web/webflux-webclient.html

#1 EasyCalendar 기획 및 설계

북극곰은콜라 — Fri, 26 May 2023 15:08:39 +0900

개요

일정 정리를 위한 Calendar 관리는 제 삶에 필수적인 사항입니다.
하지만, 일정 입력 시 UX 적으로 번거로운 부분이 있습니다.
가령 반복적이지만 비 정기적인 일정 (운동, 모임 같은)을 입력할 때
날싸선택 -> 내용 입력 -> 시간 입력 -> 장소 입력 등등의 과정을 거치며
조금 더 편하게 입력할 수 있지 않을까 합니다.

기획

EasyCalendar란 반복적으로 일어나는 컨텍스트를 템플릿 화 하여, 반복되는 내용을 미리 입력해 놓고, 간편하게 등록하는 웹 서비스이다.

전체적인 구성으로는 4 페이즈로 나누어집니다.
1. 로그인 / 구글 연동 페이즈
- 최초 EntryPoint에서 p-bear 로그인 연동을 통해 로그인 및 토큰 발급
- 서비스 진입 시 구글 연동을 확인하며, 구글 연동 실패 / 미연동 시 구글 연동 진입
- 연동 성공 시 서비스
2. 일정 확인 및 간편 입력 버튼이 있는 DashBoard 페이즈
- 앞으로 시작될 3개의 이벤트에 대한 내용을 보여줍니다.
- 일정 템플릿이 리스트업 됩니다.
- 템플릿 등록버튼이 있습니다.
3. 일정 등록 페이즈
- 일정 등록 버튼 입력 시, 일정등록에 필요한 정보 입력 컨테이너가 해당 버튼 아래에 생성 또는 모달
- 일정 등록 버튼 위치
4. 일정 템플릿 등록 페이즈
- 일정 템플릿 등록을 위한 정보 입력 페이지가 나옵니다.
- 템플릿을 Type별로 관리할 예정
- WeekDayType: 이번주 또는 다음 주 xx요일로 사전입력된 정보를 등록할 수 있는 타입
- 템플릿에 대한 정보는 서버에서 관리
- 템플릿 CRD 제공

UI 설계

기능 설계

인증

- client는 p-bear AccessToken 만 관리
- 구글연동을 통해 서버에서 사용자 연동 계정 및 refresh_token 관리
- client는 유효한 p-bear AccessToken으로 요청을 하며, google Token이 필요한 경우 서버에서 캐싱 또는 refresh를 통해 Google로 ByPass

기능 정리

API	Desc
OAuth2.0 로그인	로그인 페이지 제공, 로그인 후 지정된 redirectUri로 redirect하여, client 해당 URI를 통해 token 획득
Google 연동	Google OAuth API를 통해 authorization_code 방식으로 code를 획득 서버로 code를 전달하여 연동 작업 수행
Google 연동 확인	p-bear AccessToken을 통해 Google 연동 정보를 조회
Calendar 리스트 조회	내 연동된 계정의 Google Calendar 리스트 조회 기능 서버 필수 제공 정보 - id (pk) - desc
Event 리스트 조회	지정된 Calendar의 등록된 이벤트 리스트 조회 기능 요청 사항 - calendarId - 갯수 - 이벤트 시작 시간 서버 필수 제공 정보 - id (pk) - title - desc - 시작 시간 - 종료 시간 - 등록 시간
템플릿 등록	지정된 형식의 템플릿 등록 기능 이름과 type으로 등록하며, 기타 정보 jsonObject로 제공 및 서버에서 validation 후 저장 요청 사항 - 이름 - type - 일정 명, 일정 상세 - properties (json) 응답으로 id 값을 준다
템플릿 리스트 조회	등록된 템플릿 리스트로 조회하는 기능 템플릿 관련 정보 전체 조회 리스트에 객체로 모든 정보가 담겨서 나온다.
템플릿 삭제	리스트 화면에서 object를 길게 클릭 또는 삭제 버튼 활성화해서 서버로 삭제 요청을 보낸다. 서버에서 id를 통해 템플릿 데이터를 삭제한다.

ETC

이번 프로젝트의 목적은 Flutter에 익숙해는 것이 첫 번째이다.
Flutter 주요 구현 사항
- UI
- Http 통신
- 토큰 관리

HttpClient (Netty) Configuration 정리

북극곰은콜라 — Thu, 25 May 2023 19:05:55 +0900

개요

Spring Webflux의 WebClient의 설정을 정리하기 전
HTTP 관련 구현체인 Netty의 HttpClient 설정을 우선 정리
기본적인 설정만 정리

HttpClient Configuration

Config	Desc
disableRetry(boolean disableRetry)	request 실패 시 retry 여부
doOnRedirect(BiConsumer<? super HttpClientResponse,? super Connection> doOnRedirect)	redirect 응답 시 Consumer 설정
doOnConnected(Consumer<? super Connection> doOnConnected)	connection success시 consumer 설정
followRedirect(boolean followRedirect)	redirect 시 follow 여부
keepAlive(boolean keepAlive)	keepAlive 설정
http2Settings(Consumer<Http2SettingsSpec.Builder> http2Settings)	http2 관련 세팅
responseTimeout(Duration maxReadOperationInterval)	connection 이후 response에 걸리는 총 시간에 대한 설정
secure(SslProvider sslProvider)	SSL 관련 설정 사설인증서 무시 SSL Timeout 등등
websocket(WebsocketClientSpec websocketClientSpec)	웹소켓 관련 설정

그 외 hearders, doOnRequest, doOnResponseError 등 다수의 설정들이 존재

ClientTransport Configuration

Config	Desc
channelGroup(ChannelGroup channelGroup)	채널 그룹 설정
doOnChannelInit(ChannelPipelineConfigurer doOnChannelInit)	채널 pipeline init 시 동작할 설정
option(ChannelOption<O> key, @Nullable O value)	채널옵션 설정 (후술)
runOn(EventLoopGroup eventLoopGroup)	이벤트 그룹 설정

ChannelOption

io.netty.channel.ChannelOption<T>

Config	Desc
RCVBUF_ALLOCATOR	수신 버퍼 allocate 사이즈 지정
CONNECT_TIMEOUT_MILLIS	커넥션 타임아웃
MAX_MESSAGES_PER_READ	한번에 읽을 최대 메시지 사이즈 설정
SO_SNDBUF, SO_RCVBUF	송/수신 버퍼의 크기 조정 (UDP에서 사용)

Conclusion

네트워크 관련 설정을 할 수 있다.
주요 설정으로
- SSL Provider를 통한 SSL 설정
- responseTimeout 설정
- Connection Timeout 설정
- read / write Timeout 설정 (doOnConnected에 handler를 추가해서)
- DNS resolver 관련 설정
- Buffer size 관련 설정

Timeout 관련해서 connection, read, write는 설정할 만하다. 다만 response Timeout의 경우 특별한 이유가 없는 한 Client 입장에서 설정하는 건 문제의 여지가 많을 듯하다.
DNS 관련 설정으로 resolver 설정을 DEFAULT로 안 하면, 도메인에서 ip를 찾지 못하는 이슈가 있었다.
기타 설정들은 특별한 이유가 없는 한 default로 하는 게 최적일 것으로 보인다.

REFERENCE

https://projectreactor.io/docs/netty/release/api/reactor/netty/http/client/HttpClient.html

Kafka Connect 사용성 검토

북극곰은콜라 — Wed, 24 May 2023 18:50:06 +0900

개요

- 데이터 파이프라인 생성 시 반복 작업을 줄이고 효율적인 전송을 이루기 위한 애플리케이션
- 반복작업에 대해서 매번 Producer, Consumer 애플리케이션의 배포/운영해야 하는 비효율 보완
- Connect 를 이용하면 특정한 작업 형태를 템플릿으로 만들어 놓은 Connector 를 실행함으로써 반복작업을 줄일 수 있음.
- Kafka 브로커와 별도의 클러스터를 구성하며 Connector 가 실행되는 환경을 제공

장단점

장점	단점
관리 용이 모니터링 가능 개발 생산성 최적화 및 유지보수되는 pre-build connector	시스템 복잡성 증가 보안 문제 가능성 증가 (타 시스템 연동 때문) 제한된 기능

Confluent Platform 소개

Confluent Platform은 여러 소스 데이터를 이용하는 실시간 데이터 파이프라인과 스트리밍 애플리케이션을 쉽게 구축할 수 있는 Kafka 기반 플랫폼
Kafka를 창시한 Jay Kreps는 핵심 멤버들과 함께 Kafka 개발에 집중하기 위해 2014년에 Confluent라는 회사를 창업
Kafka를 Enterpise에서 SaaS 형태로 제공하는 솔루션

Java 뿐 아니라 다양한 랭귀지(C, .Net, Python)로 개발 가능
REST Proxy, MQTT Proxy 통해 Kafka 연결성 확보
100+ Pre-built Connectors 이용 가능하고, 표준 Schema 통한 개발로 운영 복잡성 제거
익숙한 SQL Syntax (ksqlDB) 사용하여 개발이 용이하고, 아키텍처를 단순화

License 검토

구분	Desc
Community License	Pre-built Connectors (Free) Confluent REST Proxy ksqlDB Confluent Schema Registry Confluent Admin REST API
Enterprise License	Confluent Server (kafka) Schema Linking Pre-builtConnectors (Premium, Commercial) Confluent Control Center Confluent for Kubernetes Confluent Replicator MQTT Proxy
Developer License	Confluent Platform features for free single broker per cluster 여러 single broker cluster 사용은 가능

Confluent Platform Overview

cluster 선택 페이지

메인 overview 페이지

토픽 상세 페이지 중 일부

Pre-built Connectors

Kafka 생태계에 참여하는 각 회사에서 Connector 제공
Confluent Platform에서 요구사항에 맞춰 개발한 Connector 제공 (대부분 유료)

종류

Source Connector: 소스로부터 데이터를 토픽으로 발행하는 커넥터
Sink Connector: 토픽으로부터 데이터를 소스에 적재하는 커넥터
Transform Connector: source / sink 커넥터로 데이터가 가기 전 컨버팅을 수행하는 커넥터

Free Connectors (23년 상반기 기준)

구분	Connectors	종류	Desc
DB Connector	JDBC Connector (Source and Sink)	Source, Sink
	Redis Connector (Source and Sink) by Redis	Source, Sink
	MongoDB Connector (Source and Sink)	Source, Sink
	각종 CDC Connector	Source, Sink	CDC
converter	Kafka Connect Protobuf Converter	Transform	kafka schema registry 대상 컨버터
	Kafka Connect Avro Converter	Transform
	Kafka Connect JSON Schema Converter	Transform
	Kafka Connect Common Transformations	Transform
	Kafka Connect JSON Schema Transformations	Transform	validation, filter, ket,value convert
External System Connector	Snowflake Sink Connector	Sink
	HDFS 2 Sink Connector	Sink
	ElasticSearch Source / Sink Connector	Source, Sink
	Amazon S3 Sink Connector	Sink
	Google BigQuery Sink Connector	Sink
	Spooldir Source Connector	Source
	FilePulse Source Connector	Source
	Datadog Logs Sink Connector	Sink
	Twitter Source Connector	Source
	AWS Lambda Sink Connector	Sink
	Shell Sink/Source Connector	Source, Sink
	IRC Source Connector	Source
	RSS Source Connector	Source
기타	Datagen Source Connector	Source	MockData generator (for develop)

Connector 사용 예시 (with Confluent Platform)

Ex: MongoSinkConnector

각종 설정은 각 Connector 제작자의 document를 따른다
Mongo 커넥터의 경우 MongoDB 단체에서 제작 및 배포

옵션	Desc
Topic 관련	어느 토픽에서 데이터를 가져올 것인가
Common	kafka에서 가져온 데이터 가져오는 방법 binary data → connector input
Transform	transform connector 설정
Error Handling	에러 처리 관련 에러가 발생했을 때 핸들링하는 방법 설정
Errors	커넥터 자체의 에러에 대한 설정 (기동할 때 등)
Connection	MongoDB connection
Overrides	기존 설정에 대해서 override
Namespace	Sink 할 대상 database, collection 지정
Writes	DB에 write 할 때의 설정 timeout, retry 정책 등
Post Processing	key, value filtering, field rename
Id Strategies	생성할 record의 id 정책 (_id 관련)
Change Data Capture	CDC 관련 핸들링

Conclusion

- 비즈니스 로직이 없는 단순 ETL에 경우 활용 가능
- 관리의 편의성이 목적인데, Confluent Platform 같은 솔루션이 없으면 편의성 크게 상실
- Connector 설정이 생각보다 복잡 (Connector vendor에 따라서 속성이 너무 많음)
- 현 상황에서는 ElasticSearch를 kafka에 붙이는 용도, 테스트 데이터 발행하는 용도로 사용 가능

REFERENCE

https://docs.confluent.io/platform/current/connect/index.html

https://docs.confluent.io/platform/7.4/overview.html

Kafka Schema Registry

북극곰은콜라 — Tue, 23 May 2023 18:17:44 +0900

개요

- Schema Registry는 Kafka와 별도로 동작하는 프로세스이며, Kafka에서 발생하는 Message에 대한 Schema를 관리하는 역할을 가진다.
- RESTful 인터페이스로 동작한다.
- Confluent에서 공개한 오픈소스 (Hortonworks, Spring Cloud Stream 도 있음)

Confluent Schema Registry

목적

데이터 호환성을 유지 및 관리하기 위해서 개발되었다.
producer, consumer가 많을 수 있는 분산 시스템 환경에서, 데이터에 대한 호환성을 유지하기 위함
또한 schema에 대한 관리를 하기 위함. (data governance, 정확성, 신뢰성)

장단점

장점

단점

스키마 변경 시 발생하는 오류 방지: 메시지에 대한 변경이 일어날 때 보다 안정적으로 진행 가능
중복된 스키마 방지: 스키마의 중앙관리로 중복된 스키마를 방지
호환성 검사 (유료): kafka에 발행되는 메시지를 validation 할 수 있다.
스키마 버전관리: 스키마를 여러 버전으로 관리 가능하다. 롤백 등 가능
그룹간 협업 강화: schema에 대한 공유 및 보장

관리 포인트 증가(서버): schema registry 서버를 관리해야 함
관리 포인트 증가: 엄격한 스키마 검증이 있기 때문에, 스키마에 대한 관리 필요
중앙 집중식 서비스: 확장성, 가용성 문제 발생 가능

Schema Registry Flow

CachedSchemaRegistryClient: Confluent에서 제공하는 Scehma registry 연동 라이브러리 안에 한 모듈, 기동 시 schema registry에 등록된 모든 schema를 캐싱하며, _schmas를 consume 해서 신규 스키마에 대한 정보를 캐싱

Schema Registry는 kafka를 storage로 사용한다.

// topic: _schemas

// schema insert message
{
  "subject": "test.message-value",
  "version": 1,
  "id": 2,
  "schema": "{\"type\":\"record\",\"name\":\"Device\",\"namespace\":\"com.example.kafkatest.data.device\",\"fields\":[{\"name\":\"id\",\"type\":\"long\"},{\"name\":\"capability\",\"type\":{\"type\":\"record\",\"name\":\"Capability\",\"namespace\":\"com.example.kafkatest.data.device.capability\",\"fields\":[{\"name\":\"name\",\"type\":{\"type\":\"string\",\"avro.java.string\":\"String\"}},{\"name\":\"value\",\"type\":{\"type\":\"string\",\"avro.java.string\":\"String\"}}]}}]}",
  "deleted": false
}

// schema update (evolution) message
{
   "subject": "test.message-value",
   "version": 2,
   "id": 3,
   "schema": "{\"type\":\"record\",\"name\":\"Device\",\"namespace\":\"com.example.kafkatest.data.device\",\"fields\":[{\"name\":\"id\",\"type\":\"long\"},{\"name\":\"location\",\"type\":{\"type\":\"string\",\"avro.java.string\":\"String\"},\"default\":\"default-location\"},{\"name\":\"capability\",\"type\":{\"type\":\"record\",\"name\":\"Capability\",\"namespace\":\"com.example.kafkatest.data.device.capability\",\"fields\":[{\"name\":\"name\",\"type\":{\"type\":\"string\",\"avro.java.string\":\"String\"}},{\"name\":\"value\",\"type\":{\"type\":\"string\",\"avro.java.string\":\"String\"}}]}}]}",
   "deleted": false
}

producer는 publish 전 Schema Registry를 통해 스키마를 등록(갱신,확장)할 수 있으며, 실패 시 메시지 생성을 안 한다.

// Schema 등록 실패
2023-04-17 16:31:46.154 ERROR 26796 --- [io-40001-exec-1] o.a.c.c.C.[.[.[/].[dispatcherServlet]    : Servlet.service() for servlet [dispatcherServlet] in context with path [] threw exception [Request processing failed; nested exception is org.springframework.kafka.KafkaException: Send failed; nested exception is org.apache.kafka.common.errors.InvalidConfigurationException: Schema being registered is incompatible with an earlier schema for subject "test.message-value"; error code: 409] with root cause
org.apache.kafka.common.errors.InvalidConfigurationException: Schema being registered is incompatible with an earlier schema for subject "test.message-value"; error code: 409

Schema Evolution 전략

각 전략마다 schema를 POST 하는데 200인지 409인지 결정됨

11번가 Schema Registry 도입 예시

11번가의 고민

DTO 의 필드가 변경되면 어떻게 될까요?
-> 필드의 타입이나 이름이 변경된다면 Consumer에서 해석하지 못하는 메시지를 Producer 가 전송하게 될 수도 있는데 막을 수 있는 방법은 조심하는 방법밖에는 없습니다.

DTO에 변경사항이 발생해서 적용할 때 배포는 Producer 쪽을 먼저 해야 하나요? Consumer를 먼저 해야 하나요?
-> 어떤 변경이 어떤 영향을 주게 될지 잘 모르겠습니다. 변경이 생길 때마다 영향범위를 체크하고 이상이 없을지 충분히 테스트하고 배포해야 합니다.

Producer 가 json 포맷으로 메시지를 serialize 해서 Kafka topic에 전달하면 topic 에는 json 프로퍼티의 key 값을 반복적으로 저장하게 될 텐데 디스크 낭비 아닌가요?
-> 낭비입니다.

Producer는 Consumer 가 해석할 수 있는 메시지만을 전달하도록 할 수는 없을까요?

Schema Evolution 전략

FULL 전략을 사용
배포 시점을 제외, 서로 다른 schema version을 사용 안 함
배포 시점에 Deserialize Exception을 방지하기 위해 FULL 전략 채용
모든 필드에 대해 default를 지정하는 컨밴션 적용

Conclusion

- Schema Registry는 Kafka로 인해 끊어진 Message의 Schema를 관리 및 보장하기 위해 개발된 관리 프로세스
- data 호환성과 관리 포인트 난이도 사이에 trade-off가 존재한다.
- 다수의 팀이 kafka에 붙는 대형 개발사에서는 필수 요소로 손꼽힘

REFERENCE

Apache Avro 란

북극곰은콜라 — Mon, 22 May 2023 18:08:09 +0900

Avro

Avro 란

Avro란 Apache에서 만든 프레임워크로 데이터 직렬화 기능을 제공한다.
JSON과 비슷한 형식이지만, 스키마가 존재한다.
Avro = schema + binary(json value)

장단점

장점	단점
스키마를 통해 데이터 구조 및 타입을 알 수 있다. 데이터 압축 스키마 변경에 유연하게 대응 가능	binary로 serialize 되어서, 디버깅 등 상황에서 데이터 확인에 어려움이 있다. 스키마에 대한 관리가 필요하다 (관리 포인트 증가)

DataType

Primitive

null
boolean
int
long
float
double
bytes
string

Complex

record
- name (M): name of record, String
- namespace (O): 패키지, String
- doc (O): record documentation, String
- aliases (O): alias 지정, String
- fields (M): record의 속성들, Array
  - name (M): field name, String
  - doc (O): field documentation, String
  - type (M): dataType of field
  - default (O, default): field의 default 값 지정
  - order (O): ascending, descending, ignore
  - aliases: field alias 지정, String

Enums

name (M): name of record, String
namespace (O): 패키지, String
doc (O): record documentation, String
aliases (O): alias 지정, String
symbols (M): unique 한 value 지정, Array<String>
default (O, default): default 값 지정

Array

items (M): element의 type, String
default (O, default): default 값 지정

map

values (M): element의 type, String
default (O, default): default 값 지정

default values

Example

Record

{
  "type": "record",
  "name": "LongList",
  "aliases": ["LinkedLongs"],                      // old name for this
  "fields" : [
    {"name": "value", "type": "long"},             // each element has a long
    {"name": "next", "type": ["null", "LongList"]} // optional next element
  ]
}

Enum

{
  "type": "record",
  "name": "LongList",
  "aliases": ["LinkedLongs"],                      // old name for this
  "fields" : [
    {"name": "value", "type": "long"},             // each element has a long
    {"name": "next", "type": ["null", "LongList"]} // optional next element
  ]
}

Serialized Data

import avro.schema
from avro.datafile import DataFileReader, DataFileWriter
from avro.io import DatumReader, DatumWriter

schema = avro.schema.parse(open("user.avsc").read())  # need to know the schema to write

writer = DataFileWriter(open("users.avro", "w"), DatumWriter(), schema)
writer.append({"name": "Alyssa", "favorite_number": 256})
writer.append({"name": "Ben", "favorite_number": 7, "favorite_color": "red"})
writer.close()


0000000    O   b   j 001 004 026   a   v   r   o   .   s   c   h   e   m
0000020    a 272 003   {   "   t   y   p   e   "   :       "   r   e   c
0000040    o   r   d   "   ,       "   n   a   m   e   s   p   a   c   e
0000060    "   :       "   e   x   a   m   p   l   e   .   a   v   r   o
0000100    "   ,       "   n   a   m   e   "   :       "   U   s   e   r
0000120    "   ,       "   f   i   e   l   d   s   "   :       [   {   "
0000140    t   y   p   e   "   :       "   s   t   r   i   n   g   "   ,
0000160        "   n   a   m   e   "   :       "   n   a   m   e   "   }
0000200    ,       {   "   t   y   p   e   "   :       [   "   i   n   t
0000220    "   ,       "   n   u   l   l   "   ]   ,       "   n   a   m
0000240    e   "   :       "   f   a   v   o   r   i   t   e   _   n   u
0000260    m   b   e   r   "   }   ,       {   "   t   y   p   e   "   :
0000300        [   "   s   t   r   i   n   g   "   ,       "   n   u   l
0000320    l   "   ]   ,       "   n   a   m   e   "   :       "   f   a
0000340    v   o   r   i   t   e   _   c   o   l   o   r   "   }   ]   }
0000360  024   a   v   r   o   .   c   o   d   e   c  \b   n   u   l   l
0000400   \0 211 266   / 030 334   ˪  **   P 314 341 267 234 310   5 213
0000420    6 004   ,  \f   A   l   y   s   s   a  \0 200 004 002 006   B
0000440    e   n  \0 016  \0 006   r   e   d 211 266   / 030 334   ˪  **
0000460    P 314 341 267 234 310   5 213   6
0000471

사용성

IDE Support

Import

....

<dependencies>
    <dependency>
        <groupId>org.apache.avro</groupId>
        <artifactId>avro</artifactId>
        <version>1.11.0</version>
    </dependency>
</dependencies>

....

<build>
    <plugins>
        <plugin>
            <groupId>org.apache.avro</groupId>
            <artifactId>avro-maven-plugin</artifactId>
            <version>1.11.0</version>
            <executions>
                <execution>
                    <phase>generate-sources</phase>
                    <goals>
                        <goal>schema</goal>
                    </goals>
                    <configuration>
                        <sourceDirectory>${project.basedir}/src/main/resources/avro/</sourceDirectory>
                        <outputDirectory>${project.basedir}/src/main/java/</outputDirectory>
                    </configuration>
                </execution>
            </executions>
        </plugin>
        <plugin>
            <groupId>org.apache.maven.plugins</groupId>
            <artifactId>maven-compiler-plugin</artifactId>
            <version>3.8.1</version>
            <configuration>
                <source>1.8</source>
                <target>1.8</target>
            </configuration>
        </plugin>
    </plugins>
</build>

Schema 작성

{
  "name": "Device",
  "namespace": "com.xx.xxx.device",
  "type": "record",
  "fields": [
    {
      "name": "id",
      "type": "long"
    },
    {
      "name": "Capability",
      "type": {
        "name": "Capability",
        "namespace": "com.xx.xxx.device.capability",
        "type": "record",
        "fields": [
          {
            "name": "name",
            "type": "string"
          },
          {
            "name": "value",
            "type": "string"
          }
        ]
      }
    }
  ]
}

Serialize

private void serializeTestData() throws IOException {
    Device device = Device.newBuilder()
        .setId(1L)
        .setCapability(Capability.newBuilder()
            .setName("light")
            .setValue("on")
            .build())
        .build();

    DatumWriter<Device> deviceDatumWriter;
    DataFileWriter<Device> dataFileWriter = null;
    try {
      deviceDatumWriter = new SpecificDatumWriter<>();
      dataFileWriter = new DataFileWriter<>(deviceDatumWriter);
      dataFileWriter.create(device.getSchema(), new File("test.avro"));
      dataFileWriter.append(device);
    } catch (IOException e) {
      throw new RuntimeException(e);
    } finally {
      if (dataFileWriter != null) {
        dataFileWriter.close();
      }
    }
  }

Deseiralize

private void deserializeTestData() throws IOException {
    DatumReader<Device> deviceDatumReader = null;
    DataFileReader<Device> dataFileReader = null;

    try {
      deviceDatumReader = new SpecificDatumReader<>(Device.class);
      dataFileReader = new DataFileReader<>(new File("test.avro"), deviceDatumReader);
      Device device = null;
      while (dataFileReader.hasNext()) {
        device = dataFileReader.next(device);
        System.out.println(device);
      }
    } catch (Exception e) {
      throw new RuntimeException(e);
    } finally {
      if (dataFileReader != null) {
        dataFileReader.close();
      }
    }
  }

Result

REFERENCE

브라우저와 Redirect (feat. XMLHttpRequest)

북극곰은콜라 — Fri, 19 May 2023 23:02:06 +0900

XMLHttpRequest란?

- All modern browsers have a built-in XMLHttpRequest object to request data from a server.
비동기적 통신을 브라우저에서 제공하기 위한 W3C 표준 스펙이다.
브라우저에서 제공하는 객체이며, jQuery의 Ajax 또한 XMLHttpRequest를 활용하여 구현되어 있다.

Redirect 란?

요청 client에게 Server가 다른 곳으로 다시 요청하기 위한 HTTP Response Status이다.
- 301 Moved Permanently: 요청한 리소스의 URI가 변경됨, redirect 시 method가 GET으로 자동 변경
- 302 Found: 요청한 리소스의 URI가 일시적으로 변경됨, redirect 시 method가 GET으로 자동 변경
- 307 Temporary Redirect: 요청한 리소스가 다른 URI에 있으며, 302와 동일하지만, method가 변경 안됩니다.
- 308 Permanent Redurect: 요청한 리소스가 영구적으로 변경됨, 301과 동일하지만, method가 변경 안됩니다.

즉 서버에서 Client를 다른 URI로 넘기고 싶을 때 주로 사용된다.
OAuth 2.0 스펙에서, authorization 관련 요청 시, 토큰을 redirect를 통해서 전달한다.
서버에서 3xx HttpStatus로 응답하면 Client는 Response Header의 Location 정보를 가지고 Redirect를 수행한다.

XMLHttpRequest의 Redirect 응답

XMLHttpRequest는 브라우저에서 제공하는 Object이다.
따라서 해당 Object의 통신은 브라우저가 구현했다.
기본적으로 XMLHttpRequest는 Redirect를 자동으로 수행한다.

또한 XHR의 fetch 메서드에서 Redirect에 대한 핸들링을 설정할 수 있다.

fetch(url, {
    headers: {
        'Content-Type': 'application/x-www-form-urlencoded',
    },
    redirect: "follow",
}).then(function (response) {
    if (response.status === 401) {
        alert("로그인에 실패하였습니다.");
        console.log(response.status);
        return;
    }

    console.log(response.url);
    window.location.href = response.url;
});

개인 서버의 로그인 페이지의 script 중 일부이다.
redirect는 3가지 옵션을 지원한다.
follow: 항상 redirect를 수행한다. 즉 send 이후 제공받는 response 객체는 redirect 된 응답 값이다.
manual: redirect를 수행하지 않는다. 하지만, 보안상의 이유로 Location 값을 response로부터 받을 수 없다.
error: redirect status를 오류로 인식한다.

이슈사항 및 work around

Flutter 프로젝트 진행 중
OAuth 2.0 authorization_code의 redirect 되기 전 응답의 Loaction 헤더값을 핸들링하고 싶었지만
해당 값을 불러올 수 없었다.

기본적으로 Flutter의 기본 io 라이브러리의 web build는 XHR 사용하여 Flutter에 맞게 구현되어 있다.
하지만, 한번 레핑 되는 과정에서 redirect의 핸들링을 항상 follow 하도록 구현되어 있다.
결국 XHR을 직접 컨트롤하기 위해, 단일 페이지로 구성된 HTML + javascript로 따로 구현했다...

REFERENCE

#7 3rd OAuth 연동 (google)

북극곰은콜라 — Fri, 19 May 2023 22:37:28 +0900

개요

개인 서버의 인증 시스템과 타 인증시스템의 Integration에 대한 설계를 진행해 보았다.
OAuth2.0 시스템은 타 인증 시스템에 연동할 수 있는 스펙을 가지고 있기 때문에
비교적 수월한 설계가 가능했다.

인증/인가 정책

인증 시스템의 기본 정책에 대한 결정이 필요했다.
1. 인증은 무엇을 기준으로 할 것인가?
2. 인가는 무엇을 기준으로 할 것인가?

결정 사항
1. 인증은 내 서버의 계정을 기준으로 한다.
- 무조건 내 서버 계정으로 발급받은 토큰으로 인증을 수행한다.
2. 외부인증은 내 서버의 계정에 1:다 매핑하며, 인증된 내 서버 계정의 부가정보로 정의한다.
3. 인가는 내 서버 계정이 발급받은 토큰의 scope를 기준으로 한다.
4. 토큰 업그레이드를 통해 토큰의 인가를 관리할 수 있도록 한다.
- 토큰 업그레이드는 토큰은 그대로 두고, 토큰에 매핑된 부가정보만 추가 / 변경되는 프로세스
5. 외부 인증시스템과의 연동 또한 토큰 업그레이드 방식으로 진행한다.
- 외부 계정 연동은 내 서버 계정에 부가 정보를 추가하는 방식

토큰 발급 / 토큰 업그레이드 Flow

title 북극곰은콜라 인증 Sequence

note over Client, LoginPage, GateWay_Auth, Main
    일반 인증 (Authorization_code)
end note

Client->GateWay_Auth: 인증 요청 (GET /authorize)
GateWay_Auth->Client: Redirect (308)
Client->LoginPage: Redirect
LoginPage->GateWay_Auth: 인증 요청 (GET /authroize)\nWith id/pw
GateWay_Auth->LoginPage: Redirect (308)
LoginPage->Client: Redirect with token

note over Client, LoginPage, GateWay_Auth, Main, Google
    구글 연동
end note

Client->Google: 인증 요청 (Authorization_code)
Google->Client: Redirect (with code)
Client->GateWay_Auth: POST /oauth/token/google\n(my_token + Google_token)

GateWay_Auth->Google: 토큰 발급
Google->GateWay_Auth: response
GateWay_Auth->GateWay_Auth: parse id_token(JWT)
GateWay_Auth->Main: Check Google 연동\n(id_token subject로)
Main->GateWay_Auth: response

alt not 연동
    GateWay_Auth->GateWay_Auth: Get User From Token
    GateWay_Auth->Main: POST 연동 정보
    Main->GateWay_Auth: response
    GateWay_Auth->GateWay_Auth: Token Upgrade\n토큰 연동정보 추가
end

GateWay_Auth->Client: response upgraded Token

일반인증:
기본적으로 OAuth2.0 Authorization의 implicit grant 방식을 변형하여 사용하여 인증을 수행한다.
custom parameter로 id / pw에 대한 정보를 받아서, username / password로 인증을 수행
username / password가 없을 시 로그인 페이지로 redirect
username / password 검증으로 인증 통과 시 토큰 발급

구글 아이디 연동:
일반인증을 통한 토큰으로 1차 인증
구글에서 발급받은 authorization_code를 받아서 구글에서 토큰 발급
일반토큰의 accountId를 통해 연동이력확인, 없을 시 google id_token의 JWT 값을 파싱 하여 Google 연동 POST
연동 후 토큰 업그레이드 진행 (구글 토큰에 대한 정보 account 정보에 매핑)

REFERENCE

https://developers.google.com/identity/protocols/oauth2?hl=ko#2.-obtain-an-access-token-from-the-google-authorization-server.
https://developers.google.com/identity/protocols/oauth2/native-app?hl=ko

#6 Webflux기반 OAuth2서버 + gateway 구축

북극곰은콜라 — Sun, 14 May 2023 19:14:21 +0900

개요

서비스를 위해서 서버에 접근제어를 위한 인증서버가 필요했다.
개인적으로 정리한 요구사항:
- 개인 서버의 계정을 기반으로 인증을 수행할 수 있어야 한다.
- 내부적인 서비스 호출에 인가를 받을 수 있는 구조여야 한다.
- OAuth2.0 최소 스펙 이상 동작할 수 있어야 한다.
- 추후 외부 OAuth 프로토콜과 연계 될 수 있는 구조여야 한다.

Gateway OAuth 2.0 서버 개요

Server Architecture

전체적인 서버구성에 추가적인 요소들이 있다.
1. Nginx의 추가
- WebServer의 역할을 하며, 개인 서버의 유일한 Entry Point
- URL Prefix를 통해서 각 서버로 연동을 해준다.
- Web Resource (static page)에 대한 제공을 한다.

2. Gateway Auth Server
- API 서버로 접근하기 위한 Entry Point 역할을 한다.
- Nginx로 /gateway로 접근 가능
- API 서버로 접근할 수 있는 유일한 루트
- API에 대한 인증 및 인가를 수행한다. (OAuth 2.0 기반)
- Client에 대한 관리도 진행한다.

3. Redis
- 토큰 등 캐싱을 위한 데이터를 임시 보관한다.
- 캐시 DB로 역할을 FIX

Gateway OAuth 서버 구축

앞으로 늘어날 서비스들로 라우팅할 수 있는 Gateway 서버가 필요했다.
또한 해당 포인트에서 인증 및 인가를 수행하는 것이 효율적이라는 판단으로 해당 서비스에 구현했다.
이 아이디어는 Line에서 소개한 다음 글에서 얻었다.
https://engineering.linecorp.com/ko/blog/service-authentication-sidecar-proxy

개인서버를 스케일아웃 할 수 없는 구조에서, 인증서버를 따로 두는 것은 비효율적이라 판단하고
gateway에서 인증 / 인가 서비스를 직접 하여 불필요한 트레픽을 줄였다.

난관

Spring Cloud Gateway를 기반으로 서버를 구축했다.
문제는 Webflux 기반 Spring Security 프로젝트에서, 더 이상 인증서버에 대한 기능 (토큰 발급 등 OAuth2.0 스펙)의 지원을 중단했다는 점이다.
따라서 Spring 프로젝트로 따로 OAuth2.0 스펙을 구현해야하는 상황이다.

OAuth2.0은 오래된 스펙인 만큼 해당 서버를 구축할 수 있는 라이브러리가 있을 것이라 기대했다.
하지만 2가지 문제가 있었다.
1. OAuth 2.0 을 사용하는 client 입장의 라이브러리와 SDK가 대부분
2. 대부분의 라이브러리는 블로킹 기반의 서버에서 활용 가능하도록 API가 구성되어있음

처음 시도했던 방법은 블로킹 기반으로 설계된 라이브러리를 비동기 방식으로 Wrapping해서 구현해 보려 했다.
하지만, 대부분 Datasource를 제공하는 방식에서 문제가 생겼다.
결국 DataSource로 부터 데이터를 동기적으로 세팅하도록 설계가 되어있어서, Integrate하는데 문제가 발생했다.

그래도 직접 구현하기에는 스펙 자체가 작지 않아서 다른 방식을 찾아보았다.

해결

Nimbus라는 OAuth2.0 기반 엔터프라이즈 인테그레이션 서비스를 제공하는 회사?단체?가 있다.
Numbus에서 자신들의 OAuth2.0 서버를 기존 서버에 인테그레이션 할 수 있는 SDK를 제공한다.
해당 오픈소스에는 OAuth2.0의 인터페이스를 전체적으로 제공하고있다.
하지만 인증 로직에 대한 부분은 구현되어있지 않았다.

해당 SDK를 활용해서
인증 요청 -> (SDK) -> 인증로직 (구현) -> (SDK) -> 응답
하는 방식으로 최소한의 로직 구현으로 인증서버를 구축하기로 결정했다.

OAuth 2.0 서비스 구현

주요 라이브러리

implementation("org.springframework.boot:spring-boot-starter-webflux")
implementation("org.springframework.cloud:spring-cloud-starter-gateway")
implementation("org.springframework.boot:spring-boot-starter-security")
implementation("org.springframework.boot:spring-boot-starter-data-r2dbc")
implementation("org.springframework.boot:spring-boot-starter-data-redis-reactive")

implementation("com.nimbusds:c2id-server-sdk:4.53")
implementation("org.mariadb:r2dbc-mariadb:1.0.3")

Kotlin으로 구현된 서버이며
Spring Webflux 기반으로 한정된 서버 리소스를 최대할 활용하고자 했다.
Spring Security로 인증 / 인가에 대한 기능을 구현하고
nimbus 라이브러리를 활용해 인증을 위한 서비스를 구현했다.
Database를 논블로킹으로 활용 할 수 있게 R2DBC 인터페이스를 사용했으며
연동되는 DB는Redis와 MariaDB 이다.

Client Service

OAuth 2.0 의 Client에 대한 create, delete, verify 기능을 제공할 수 있도록 구현했다.

패키지 외부적으로 ClientHandler를 통해서 Client에 대한 CRD를 제공한다.
ClientAuthenticationVerifier는 Nimbus의 Client Verifier를 위한 모듈이며, 이는 Nimbus의 Verifier를 논블로킹 방식으로 레핑했다.

OAuth Service

OAuthHandler: 토큰 발급 요청을 적절하게 파싱하는 핸들러, Nimbus SDK를 적극 활용, Authoriz e 요청을 위한 로직은 이쪽에 구현
TokenService: 토큰 발급을 위한 로직들이 구현되어있는 핸들러, 구현된 사항으로는 Authorize Code, Authorize Token, Resource Owner 방식 3가지 이다.
TokenStore: 토큰에 대한 CRUD를 담당하는 클래스.
OAuthRedisRepository: 토큰을 Redis에 CRD를 하는 레파지토리

인증 / 인가 서비스 구현

@Bean
fun securityWebFilterChain(
    serverHttpSecurity: ServerHttpSecurity,
    authManager: AuthManager,
    authenticationConverter: AuthenticationConverter): SecurityWebFilterChain {
    val filter = AuthenticationWebFilter(authManager)
    filter.setServerAuthenticationConverter(authenticationConverter)

    val authorizeExchangeSpec = serverHttpSecurity
        .authorizeExchange()

    // permitAll 세팅
    permitAllApiMap.forEach{ entry ->
        entry.value.forEach { uri ->
            authorizeExchangeSpec.pathMatchers(entry.key, uri).permitAll()
        }
    }

    authorizeExchangeSpec
        // main 서버 기본 scope -> main:*
        .pathMatchers("/main/**").hasAuthority("SCOPE_main:*")

    return authorizeExchangeSpec
        .and()
        .addFilterAfter(filter, SecurityWebFiltersOrder.AUTHENTICATION)

        .csrf().disable()
        .formLogin().disable()
        .httpBasic().disable()
        .logout().disable()
        .cors().configurationSource(corsConfigurationSource())
        .and()
        .build()
}

Spring Security를 활용해서 인가에 대한 컨트롤을 수행한다.
회원가입, 토큰 발급 등에 대해서 permitAll(), 나머지는 서비스별로 SCOPE를 확인 하도록 설정

GateWay Service

@Bean
fun proxyRouterFunction(routeLocatorBuilder: RouteLocatorBuilder): RouteLocator = routeLocatorBuilder.routes()
    .route("main") { predicateSpec ->
        predicateSpec
            .path("/main/**")
            .filters { it
                .filter(apiAccessControlFilter.apply(ApiAccessControlFilter.Config()))
                .rewritePath("^/main", "")
            }
            .uri(mainRouteUrl)
    }
    .build()

Spring Cloud Gate를 활용하여 구성
/main으로 들어오는 요청을 main 서비스로 라우팅 한다.
prefix는 제거해서 요청

전체 flow 예시로
/gateway/main/api/xxx
Nginx에서 gateway가 지워지면서 gateway서버로 접근
gateway filter단에서 토큰 검증
/main을 지우면서 main 서버로 /api/xxx로 요청

추후 계획

기본 로그인 / 회원가입 페이지를 Niginx를 통해 제공하며
묵시적 코드 플로우를 통해 토큰을 제공할 예정이다.
전체적인 구성은
개별 서비스 -> login 페이지 (redirectURI 포함) -> 로그인 수행 -> 개별 서비스로 redirect
로 구성 되며, 로그인 페이지에 구글 연동 정도 추가 할 예정

REFERENCE

https://oauth.net/2/

https://www.rfc-editor.org/rfc/rfc6749

https://connect2id.com/products/server

Redis 설치 (ubuntu)

북극곰은콜라 — Wed, 26 Apr 2023 21:33:55 +0900

설치

// apt 업데이트
sudo apt-get update
sudo apt-get upgrade

// 설치
sudo apt-get install redis-server

// 설정
sudo vi /etc/redis/redis.conf
maxmemory 1g
maxmemory-policy allkeys-lru
bind xxx.xxx.xxx.xxx , xxx.xxx.xxx.xxx

// 재시작
sudo systemctl restart redis-server.service

// 확인
netstat -nlpt | grep 6379

방화벽 설정

sudo iptables -A INPUT -p tcp --dport 6379 -j ACCEPT
sudo netfilter-persistent save
sudo netfilter-persistent reload

Data 디렉토리 변경

// redis conf 수정
sudo vi /etc/redis/redis.conf

// dir 설정
dir {데이터 디렉토리}

// redis.service 수정
vi /etc/systemd/system/redis.service

// 디렉토리 관련 설정
ReadWriteDirectories=-{데이터 디렉토리}

REFERENCE

https://hayden-archive.tistory.com/429

R2DBC history 및 issue

북극곰은콜라 — Fri, 21 Apr 2023 15:01:47 +0900

개요

Reactive Relational Database Connectivity
SQL database에서 Reactive programming을 지원하기 위해 디자인된 새로운 Open Specification
R2DBC를 쉽게 사용할 수 있도록 ORM의 사용법을 참고하여 설계하였으나, ORM Framework에서 제공하는 다양한 기능을 제공하지 않음.

특징

Based on the Reactive Streams specification.
- provides a fully-reactive non-blocking API.

Works with relational databases.
- JDBC의 Blocking 특성과 달리, R2DBC를 사용하면 Reactive API를 사용하여 SQL database로 작업할 수 있다.

Supports scalable solutions.
- Reactive Stream을 사용하면 기존의 "연결 당 하나의 스레드"모델에서보다 강력하고 확장 가능한 접근 방식이 가능하다.

Provides an open specification.
- R2DBC 는 open specification이며 드라이버 공급업체가 spec을 구현하고 클라이언트가 사용할 SPI(Service Provider Interface) 제공합니다.
- R2DBC는 최소한의 SPI를 목표로 한다.

구현체

clickhouse-r2dbc - R2DBC wrapper of async Java client for ClickHouse.
cloud-spanner-r2dbc - driver for Google Cloud Spanner.
jasync-sql - R2DBC wrapper for Java & Kotlin Async Database Driver for MySQL and PostgreSQL (written in Kotlin).
oracle-r2dbc - native driver implemented for Oracle.
r2dbc-h2 - native driver implemented for H2 as a test database.
r2dbc-mariadb - native driver implemented for MariaDB.
r2dbc-mssql - native driver implemented for Microsoft SQL Server.
r2dbc-mysql - native driver implemented for MySQL (previously mirromutth/r2dbc-mysql).
r2dbc-postgresql - native driver implemented for PostgreSQL.

SPI History ~ 1.0

0.8

initial version

0.9

Extended transaction definitions
Improved Bind Parameter declararation
Consumption of OUT Parameters
Consumption of Result Segments
Lifecycle extension
Refinement of Option
Refinement of RowMetadata
Lock Wait and Statement Timeouts
Refined Exceptions for Readable.get(…) and Statement.bind(…)

1.0

Revised Result.getRowsUpdated() signature
- 1.0 스펙 중 이전 버전이랑 하위호환이 안되게 하는 주범, update 시 update row를 Long -> Integer로 변경해서, update(save) 시 classCastException이 발생한다.
Removed RowMetadata.getColumnNames() method
TCK Extensions

Spring Data R2DBC

Spring Data R2DBC version	imported R2DBC SPI version	주요 기능
1.0.0	0.8	initial major version
1.1.0	0.8.1	r2dbcEntityTemplate 기능 추가 query derivation 추가
1.2.0	0.8.3	r2dbcAuditing 추가 @Value support support Oracle R2DBC Driver
1.3.0	0.8.4	Query By Example 기능 추가
1.4.0	0.8.5	upgrade dependency
1.5.0	0.9.1	upgrade dependency
3.0.0	1.0.0	spring boot 3 대응

Spring Boot Starter Data R2DBC version	Spring Data R2DBC version
2.3.2	1.1.2
2.4.0	1.2.1
2.5.0	1.3.1
2.6.0	1.4.0
2.7.0	1.5.0
3.0.0	3.0.0

MySQL, MariaDB Driver

주저리주저리

신규 프로젝트에서 R2DBC 사용 도중 update 시 driver에서 오류가 올라와서 부랴부랴 알아봄.
SPI 1.0 버전이 나온 것까진 알고 있었는데 interface상 하위호환이 안될 줄은 상상도 못 함...
일단 버전에 맞는 mariaDB 구현체를 사용해서 해결한 상태.
이슈 해결 후 조사한 게 억울해서 블로그에 정리

이슈 stacktrace

20230421 14:59:18.570 [db-sql-netty-thread-2] ERROR o.s.b.a.w.r.e.AbstractErrorWebExceptionHandler - [695cf522-1]  500 Server Error for HTTP PUT "/dev/data" 
java.lang.ClassCastException: class java.lang.Long cannot be cast to class java.lang.Integer (java.lang.Long and java.lang.Integer are in module java.base of loader 'bootstrap')
	at java.base/java.util.stream.Collectors.lambda$summingInt$19(Collectors.java:673)
	Suppressed: reactor.core.publisher.FluxOnAssembly$OnAssemblyException: 
Error has been observed at the following site(s):
	*__checkpoint ⇢ Handler org.springframework.web.reactive.function.server.RouterFunctionDsl$PUT$2@10647471 [DispatcherHandler]
	*__checkpoint ⇢ com.pbear.mainfunctionalserver.common.log.LoggingWebFilter [DefaultWebFilterChain]
	*__checkpoint ⇢ HTTP PUT "/dev/data" [ExceptionHandlingWebHandler]
Original Stack Trace:
		at java.base/java.util.stream.Collectors.lambda$summingInt$19(Collectors.java:673)
		at reactor.core.publisher.MonoStreamCollector$StreamCollectorSubscriber.onNext(MonoStreamCollector.java:132)
		at reactor.core.publisher.FluxFlatMap$FlatMapMain.tryEmitScalar(FluxFlatMap.java:489)
		at reactor.core.publisher.FluxFlatMap$FlatMapMain.onNext(FluxFlatMap.java:422)
		at reactor.core.publisher.FluxMap$MapSubscriber.onNext(FluxMap.java:122)
		at reactor.core.publisher.FluxOnErrorResume$ResumeSubscriber.onNext(FluxOnErrorResume.java:79)
		at reactor.core.publisher.FluxMap$MapSubscriber.onNext(FluxMap.java:122)
		at reactor.core.publisher.FluxConcatMap$ConcatMapImmediate.innerNext(FluxConcatMap.java:282)
		at reactor.core.publisher.FluxConcatMap$ConcatMapInner.onNext(FluxConcatMap.java:863)
		at reactor.core.publisher.Operators$MonoSubscriber.complete(Operators.java:1839)
		at reactor.core.publisher.MonoCompletionStage.lambda$subscribe$0(MonoCompletionStage.java:96)
		at java.base/java.util.concurrent.CompletableFuture.uniHandle(CompletableFuture.java:930)
		at java.base/java.util.concurrent.CompletableFuture$UniHandle.tryFire(CompletableFuture.java:907)
		at java.base/java.util.concurrent.CompletableFuture.postComplete(CompletableFuture.java:506)
		at java.base/java.util.concurrent.CompletableFuture.complete(CompletableFuture.java:2073)
		at com.github.jasync.sql.db.util.FutureUtilsKt.success(FutureUtils.kt:16)
		at com.github.jasync.sql.db.mysql.MySQLConnection.succeedQueryPromise$lambda-12(MySQLConnection.kt:361)
		at java.base/java.util.Optional.ifPresent(Optional.java:183)
		at com.github.jasync.sql.db.mysql.MySQLConnection.succeedQueryPromise(MySQLConnection.kt:360)
		at com.github.jasync.sql.db.mysql.MySQLConnection.onOk(MySQLConnection.kt:227)
		at com.github.jasync.sql.db.mysql.codec.MySQLConnectionHandler.channelRead0(MySQLConnectionHandler.kt:125)
		at io.netty.channel.SimpleChannelInboundHandler.channelRead(SimpleChannelInboundHandler.java:99)
		at io.netty.channel.AbstractChannelHandlerContext.invokeChannelRead(AbstractChannelHandlerContext.java:444)
		at io.netty.channel.AbstractChannelHandlerContext.invokeChannelRead(AbstractChannelHandlerContext.java:420)
		at io.netty.channel.AbstractChannelHandlerContext.fireChannelRead(AbstractChannelHandlerContext.java:412)
		at io.netty.handler.codec.ByteToMessageDecoder.fireChannelRead(ByteToMessageDecoder.java:346)
		at io.netty.handler.codec.ByteToMessageDecoder.channelRead(ByteToMessageDecoder.java:318)
		at io.netty.channel.AbstractChannelHandlerContext.invokeChannelRead(AbstractChannelHandlerContext.java:444)
		at io.netty.channel.AbstractChannelHandlerContext.invokeChannelRead(AbstractChannelHandlerContext.java:420)
		at io.netty.channel.AbstractChannelHandlerContext.fireChannelRead(AbstractChannelHandlerContext.java:412)
		at io.netty.channel.DefaultChannelPipeline$HeadContext.channelRead(DefaultChannelPipeline.java:1410)
		at io.netty.channel.AbstractChannelHandlerContext.invokeChannelRead(AbstractChannelHandlerContext.java:440)
		at io.netty.channel.AbstractChannelHandlerContext.invokeChannelRead(AbstractChannelHandlerContext.java:420)
		at io.netty.channel.DefaultChannelPipeline.fireChannelRead(DefaultChannelPipeline.java:919)
		at io.netty.channel.nio.AbstractNioByteChannel$NioByteUnsafe.read(AbstractNioByteChannel.java:166)
		at io.netty.channel.nio.NioEventLoop.processSelectedKey(NioEventLoop.java:788)
		at io.netty.channel.nio.NioEventLoop.processSelectedKeysOptimized(NioEventLoop.java:724)
		at io.netty.channel.nio.NioEventLoop.processSelectedKeys(NioEventLoop.java:650)
		at io.netty.channel.nio.NioEventLoop.run(NioEventLoop.java:562)
		at io.netty.util.concurrent.SingleThreadEventExecutor$4.run(SingleThreadEventExecutor.java:997)
		at io.netty.util.internal.ThreadExecutorMap$2.run(ThreadExecutorMap.java:74)
		at java.base/java.lang.Thread.run(Thread.java:834)

REFERENCE

https://r2dbc.io/

https://docs.spring.io/spring-data/r2dbc/docs/current/reference/html/

https://r2dbc.io/spec/1.0.0.RELEASE/spec/html/#changes

https://stackoverflow.com/questions/74972672/java-lang-integer-cannot-be-cast-to-class-java-lang-long-in-r2dbc-mysql-model-cl

https://github.com/spring-projects/spring-data-commons/wiki/Release-Trains

Mysql data directory 변경

북극곰은콜라 — Wed, 19 Apr 2023 09:41:59 +0900

개요

mysql 데이터를 마운트한 하드로 옮겨서 운영하거나 백업 등을 할 때 유용한 가이드 요약 번역
ubuntu 용 가이드

Data Directory 확인

// config 파일로 확인
sudo grep -R --color datadir /etc/mysql/*

// DB 내에서 확인
mysql> SELECT @@datadir;
+---------------------------+
| @@datadir                 |
+---------------------------+
| /var/lib/mysql            |
+---------------------------+
1 row in set (0.000 sec)

Data 복사

// 옮길 폴더 생성 및 권한
mkdir /data
sudo chown mysql:mysql /data

// mysql stop
sudo systemctl stop mysql

// 복사
// rsync -avzh {from} {to}
sudo rsync -avzh /var/lib/mysql/ /data

// 보안 설정
sudo vi /etc/apparmor.d/tunables/alias

// 아래 한줄 추가
alias /var/lib/mysql -> /data,

설정 변경 및 확인

// config 파일에서 확인한 datadir 옵션을 변경
datadir = /data

// mysql 시작
sudo systemctl start mysql

// 접속 후 확인
mysql> SELECT @@datadir;
+---------------------------+
| @@datadir                 |
+---------------------------+
| /data                     |
+---------------------------+
1 row in set (0.000 sec)

REFERENCE

https://linuxhint.com/change_mysql_data_directory_ubuntu/

Gradle 이란

북극곰은콜라 — Tue, 18 Apr 2023 13:51:51 +0900

Gradle 이란

Groovy 기반의 빌드 툴

장점

자유로운 빌드 설정
동적인 빌드 설정 가능
손쉬운 wrapper
빠른 성능
(취향) 가독성

Build

Life Cycle

초기화 단계
1. init.gradle, gradle.properties 환경설정파일을 read
2. settings.gradle 파일에 포함된 하위 프로젝트(모듈) 설정
설정 단계
1. 모든 빌드 스크립트를 평가 및 DAG Create
2. 실행순서 결정
시행 단계
1. 태스크를 차례로 실행

Task

빌드 단계

DAG

Directed Acyclic Graph로 빌드 순서등을 가진 것
예시) java plugin DAG

Repositories & dependencies

Repositories

필요할 때 가져와서 쓸 수 있는 라이브러리의 집합
로컬 캐시에 저장됨
기본 디렉터리는 .gradle

// 예시
mavenCentral(), jcenter(), mavenLocal()
maven {
    credentials {
        username 'username'
        password 'password'
    }
    url 'http://xxx.yyy.zzz/abc'
}
flatDir {
    dirs 'lib'
}

Dependencies

사용하는 라이브러리들 명시
라이브러리 그룹, 이름, 버전으로 찾아오며 의존성 설정 가능

문법

전체 문법
[의존성] group: '[그룹]', name: '[이름]', version: '[버전]'

간이 문법
[의존성] '[그룹]:[이름]:[버전]'

버전은 1.+ 이런 식으로도 가능 (비추)

라이브러리의 jar만 참조
전체 : [의존성] group: '[그룹]', name: '[이름]', version: '[버전]' ext: 'jar'
간이식 : [의존성] '[그룹]:[이름]:[버전]@jar'

전이적 의존성 중 특정 라이브러리 제외 (이미 다른 곳에서 참조하여 받거나 특정 경로로 지정되었을 때)
compile xxxx:yyy:4.2 { exclude group: 'aaa.bbb.ccc' }

compile : 프로젝트 전체에서 사용가능
runtime : 런타임 시에만 사용
testCompile : src/test/java 소스 디렉터리에서만

컴파일 시에만
compileOnly 'org.projectlombok:lombok'
로컬 파일 시스템 파일 참조
compile files('libs/a.jar, 'libs/b.jar'')
compile fileTree(dir: 'libs', includes: ['*.jar'])

전의적 의존성
명시적으로 의존성을 가진 라이브러리가 가진 의존성들 dependencies 문법에 transitive: false로 비활성화 가능 (모든 라이브러리를 다 가지고 있어야 한다....)

Gradle Wrapper

Gradle 실행 시 해당 환경에 Gradle 설치 없이 하기 위함
빌드 설계자의 버전에 맞게 빌드 가능

구성

gradle-wrapper.jar : 그레이들 래퍼 jar
gradle-wrapper.properties : 그레이들 래퍼 버전 및 실행환경
gradlew : Unix 계열에서 실행가능한 스크립트
gradlew.bat : 윈도우 계열에서 실행가능한 스크립트

gradle-wrapper.properties

distributionBase=GRADLE_USER_HOME
distributionPath=wrapper/dists
distributionUrl=https\://services.gradle.org/distributions/gradle-6.6.1-bin.zip
zipStoreBase=GRADLE_USER_HOME
zipStorePath=wrapper/dists

distributionUrl : 래퍼의 다운로드 버전이 확인 가능
처음 실행 후 zipStoreBase 아래 zipStorePath 아래 저장되며 이후 캐시로 동작

실행

기본 : 명령창에서 ./gradlew(유닉스) 또는 gradlew.bat 실행(윈도우)
여러 타스크 실행 : ./gradlew clean init

Task 설명

// 빌드스크립트(build.gradle)에 외부 라이브러리가 필요할때 쓰는 메서드
// 항상 맨위
// 이 메서드로 추가시 현 스크립트에서 추가된 의존성, 저장소 및 메서드 사용가능
buildscript {
    repositories {
        mavenLocal()
    }
    dependencies {
    }
}
 
....
 
 
// ""은 변수 치환 사용, ''은 사용안함
 
task customTaskA {
    // 다른 task를 참조 (import)
    dependsOn 'customTaskB'
    // 전역변수 export
    ext.customValue = 'CUSTOM VALUE FROM TASK_A'
}
 
task customTaskB {
}
// task에서 실행될 일 추가
customTaskB.doLast {
    println 'add doLast to customTaskB'
}
 
// export된 변수 사용
task customTaskC {
    doLast {
        println customTaskA.customValue
    }
}
 
 
// 기본 타스크 지정
defaultTasks 'clean', 'devBuild'
 
 
// 변수 선언
def buildType = 'normal'
 
task buildProject {
    doLast {
        println '---build project start---'
        println "build type=${buildType}"
        println '---build project end---'
    }
}
 
task devBuild {
    dependsOn 'buildProject'
}
 
task releaseBuild {
    dependsOn 'buildProject'
}
 
// gradle 2단계(설정단계) 진행중 실행되는 메서드
// 등록된 타스크에 따라서 변수에 값 할당
gradle.taskGraph.whenReady {
    taskGrapth ->
        if (taskGrapth.hasTask(":releaseBuild")) {
            buildType = 'release'
            println 'release'
        } else if (taskGrapth.hasTask(":devBuild")) {
            buildType = 'dev'
            println 'dev'
        } else {
            buildType = 'normal'
            println 'normal'
        }
}

동작 원리

groovy와 코틀린으로 작성되어 있다.
org.gradle.api의 Project라는 인터페이스를 사용하는 형식

gradle 소스 분석 (v6.7)

Project (Interface)

개요
- main API이며 build file을 분석할 때 사용된다
- 해당 인터페이스는 각 프로젝트의 build.gradle와 1:1 관계를 가진다
- Task Object의 집합으로 구성되어 있다
life Cycle
- Settings 인스턴스를 생성한다 (Settings 인터페이스는 gradle.setting 파일과 1:1 관계, gradle.setting파일로 생성된다고 봐도 무방하다)
- Settings를 이용해서 프로젝트의 계층구조를 형성한다.
  - 해당 계층구조로 인해서 project가 순차적으로 생성된다.
- build.gradle 파일을 이용해서 Project 인스턴스를 생성

Task (Interface)

개요
- 어떠한 작업들을 가진 인터페이스 (ex: 컴파일 클래스, 유닛테스트 실행, WAR로 export 등등)
- gradle에서 실행가능 작업의 최소단위
- Action들로 이루어져 있다
- 기본적으로 TaskContainer에 의해서 생성 관리 된다.
build.gradle 파일에서의 Task
- Dynamic Properties
  - setProperty(String, Object) 메서드를 이용하여 세팅
  - 파일 내에서 해당 프로퍼티의 key 또는 property(String)으로 get 해서 사용
- Dependency
  - 다른 타스크들과의 의존성 및 순서를 세팅

// 예시 : buildscript 메서드 흐름

buildscript {
    repositories {
        mavenLocal()
    }
    dependencies {
    }
}


/*
Project 인터페이스의 buildscript(Closure configureClosure) 메서드를 실행
Closure 는 groovy의 Closure이다
	property, method등을 세팅 할 수 있으며, 정의된 메서드를 invoke 시킬 수 있는 기능을 가진 추상클래스
Closure가 repositories와 dependencies 메서드를 invoke 시킨다 (ScriptHandler)
ScriptHandler 인터페이스
	repositories(Closure configureClosure)
    	저장소를 설정한다
		사용가능 메서드 : https://docs.gradle.org/current/javadoc/org/gradle/api/artifacts/dsl/RepositoryHandler.html
	dependencies(Closure configureClosure)
    	의존성을 설정한다
		dependencies 사용가능 옵션 : https://developer.android.com/studio/build/dependencies?hl=ko
*/

REFERENCE

gradle 레시피 책

DB Type	Driver	develop by	Desc
Mysql	jasync-sql	jasync-sql	코틀린으로 개발된 드라이버 MySQL, PostgreSQL 지원
	r2dbc-mysql	mirrormutth	최초의 mysql r2dbc driver 구현체 현재는 개발 중단
	r2dbc-mysql	asyncer-io	mysql 5.5, 5.6, 5.7, 8.0 호환 r2dbc-spi 1.0까지 호환
MariaDB	mariadb-connector-r2dbc	mariadb-corp	MariaDB 공식 r2dbc 지원 드라이버