Skip to content

Commit 2cd422e

Browse files
GOKULRAJ136GOKULRAJ136
committed
Merge branch 'v1.3.1-rc.1' into develop
Signed-off-by: GOKULRAJ136 <110164849+GOKULRAJ136@users.noreply.github.com>
1 parent 03d3934 commit 2cd422e

112 files changed

Lines changed: 6259 additions & 3815 deletions

File tree

Some content is hidden

Large Commits have some content hidden by default. Use the searchbox below for content that may be hidden.

‎AGENTS.md‎

Lines changed: 157 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,157 @@
1+
# AGENTS.md
2+
3+
This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
4+
5+
---
6+
7+
## Build Commands
8+
9+
**Always skip GPG signing locally:**
10+
```bash
11+
# Build everything
12+
mvn clean install -Dmaven.javadoc.skip=true -Dgpg.skip=true
13+
14+
# Build a single module (run from the module directory)
15+
cd kernel/kernel-idgenerator-service
16+
mvn clean install -Dgpg.skip=true
17+
18+
# Skip tests for faster builds
19+
mvn clean install -Dgpg.skip=true -DskipTests=true
20+
21+
# Run a single test class
22+
mvn test -Dgpg.skip=true -Dtest=UinGeneratorServiceTest
23+
24+
# Run with a specific Spring profile
25+
java -Dspring.profiles.active=local -jar target/<jar-name>.jar
26+
27+
# Run with remote config server
28+
java -Dspring.profiles.active=env \
29+
-Dspring.cloud.config.uri=<config-url> \
30+
-Dspring.cloud.config.label=<branch> \
31+
-jar target/<jar-name>.jar
32+
```
33+
34+
The root `pom.xml` only contains the `kernel` module. All service modules are under `kernel/`.
35+
36+
---
37+
38+
## Repository Structure
39+
40+
```
41+
commons/
42+
├── pom.xml # Root POM (io.mosip:commons:1.4.0-SNAPSHOT)
43+
├── kernel/ # All kernel modules — one Maven reactor
44+
│ ├── pom.xml # io.mosip.kernel:kernel-parent (Java 21, 39 submodules)
45+
│ ├── kernel-bom/ # Bill of Materials — all third-party version pins
46+
│ ├── kernel-core/ # Shared interfaces, exceptions, base DTOs, utilities
47+
│ ├── kernel-logger-logback/ # Logback wrapper implementing kernel-core logger SPI
48+
│ ├── kernel-dataaccess-hibernate/ # Hibernate JPA base classes
49+
│ ├── kernel-idgenerator-*/ # ID generator libraries (VID, PRID, RID, TokenID, MachineID, etc.)
50+
│ ├── kernel-idvalidator-*/ # Corresponding validators for each ID type
51+
│ ├── kernel-notification-service/ # Spring Boot: SMS + email via REST (port 8083)
52+
│ ├── kernel-ridgenerator-service/ # Spring Boot: RID generation REST service
53+
│ ├── kernel-idgenerator-service/ # Vert.x: UIN + VID generator service (NOT Spring MVC)
54+
│ ├── kernel-pridgenerator-service/ # Spring Boot: PRID generation REST service
55+
│ ├── kernel-salt-generator/ # Spring Boot: cryptographic salt generation
56+
│ └── kernel-config-server/ # Spring Cloud Config Server wrapper
57+
├── helm/ # Helm charts for Kubernetes deployment
58+
│ ├── idgenerator/ # chart version: 0.0.1-develop (image: mosipqa/kernel-idgenerator-service:develop)
59+
│ ├── notifier/ # chart version: 0.0.1-develop
60+
│ ├── ridgenerator/ # chart version: 0.0.1-develop
61+
│ ├── pridgenerator/ # chart version: 0.0.1-develop
62+
│ ├── config-server/ # chart version: 0.0.2-develop
63+
│ ├── conf-secrets/ # chart version: 0.0.1-develop
64+
│ └── regproc-salt/ # chart version: 0.0.1-develop
65+
├── db_scripts/ # PostgreSQL DDL + DML scripts (mosip_kernel schema)
66+
│ └── <db_name>/ddl/ dml/ # Tables + seed data; run via deploy.sh
67+
└── deploy/ # Shell-based Kubernetes install scripts
68+
├── kernel/
69+
├── config-server/
70+
└── conf-secrets/
71+
```
72+
73+
---
74+
75+
## Architecture: Two Service Patterns
76+
77+
### Standard Spring Boot services
78+
`kernel-ridgenerator-service`, `kernel-pridgenerator-service`, `kernel-notification-service`, `kernel-salt-generator`, `kernel-config-server` — follow the conventional `@SpringBootApplication` pattern with Spring MVC controllers. Their `bootstrap.properties` points to the config server for all runtime config.
79+
80+
### Vert.x + Spring hybrid (`kernel-idgenerator-service`)
81+
This is the most architecturally unusual module. It does **not** use Spring MVC for its HTTP layer. Instead:
82+
- `IDGeneratorVertxApplication.main()` first fetches config from Spring Config Server via the Vert.x config retriever, then bootstraps a `Vertx` instance manually.
83+
- **UIN subsystem**: `UinGeneratorVerticle` + `UinTransferVerticle` — worker verticles that pre-generate a pool of UINs in PostgreSQL (`kernel.uin` table) using `SecureRandom` + Verhoeff checksum + configurable filters. UINs are produced in batches and held in the DB until consumed by ID Repository.
84+
- **VID subsystem**: `VidPoolCheckerVerticle`, `VidPopulatorVerticle`, `VidExpiryVerticle`, `VidIsolatorVerticle` — worker verticles managing the VID pool lifecycle. VID generation reuses the `kernel-idgenerator-vid` library.
85+
- Spring context (`HibernateDaoConfig`) is initialised only for JPA (Hibernate/PostgreSQL), not for HTTP serving.
86+
- Verticles communicate via the Vert.x event bus (addresses defined in `UinGeneratorConstant`, `EventType`).
87+
- HTTP health checks are handled by Vert.x `HealthCheckHandler`, not Spring Actuator routes.
88+
89+
---
90+
91+
## MOSIP ID Types (Domain Context)
92+
93+
Understanding these is essential when working on any generator or validator module:
94+
95+
| ID | Full Name | Nature | Key facts |
96+
|---|---|---|---|
97+
| **UIN** | Unique Identification Number | Permanent resident ID | Generated with SecureRandom + Verhoeff checksum; never reissued; filtered against pattern rules |
98+
| **VID** | Virtual ID | Temporary alias for UIN | Expirable, revocable, privacy-friendly; used for authentication instead of exposing UIN |
99+
| **RID / AID** | Registration / Application ID | Per-registration-event ID | Tracks each lifecycle event (enrolment, update, lost ID) at registration center |
100+
| **PRID** | Pre-Registration ID | Pre-registration phase ID | Assigned when resident books appointment before visiting registration center |
101+
| **Token ID (PSUT)** | Partner-Specific User Token | Per-partner pseudonym | Returned in auth response to relying party; prevents cross-partner linkage; not used for auth |
102+
103+
Additional IDs generated by library modules (not services): MachineID, RegistrationCenterID, PartnerID, MISPID, LicenseKey.
104+
105+
---
106+
107+
## Key Cross-Cutting Patterns
108+
109+
### Dependency hierarchy
110+
All modules depend on `kernel-core` for interfaces and `kernel-bom` for version pinning. Do not declare third-party dependency versions in module POMs — they come from the BOM.
111+
112+
### Lombok
113+
All entity classes and most DTOs use `@Data`, `@AllArgsConstructor`, `@NoArgsConstructor`. Lombok is declared as `<scope>compile</scope>` in `kernel-core/pom.xml` and inherited. **Important**: if a `.java` file is placed in the wrong package directory (package declaration doesn't match directory), the resulting "duplicate class" compile error will prevent Lombok annotation processing from completing, causing cascading "cannot find symbol" errors across the entire module — not just the offending file.
114+
115+
### Configuration
116+
All services pull runtime configuration from the MOSIP Config Server at startup. Property files live in a separate repo: `https://github.com/mosip/mosip-config`. The relevant files are `application-default.properties` and `kernel-default.properties`. Local overrides go in `bootstrap.properties` (`spring.profiles.active=local`).
117+
118+
### Database schemas
119+
Each service uses its own PostgreSQL schema (e.g., `kernel` for UIN/VID tables). DDL/DML bootstrap scripts are in `db_scripts/`. Tests use H2 in-memory with the same Hibernate configuration.
120+
121+
### Versioning convention
122+
- `develop` branch: `*-SNAPSHOT` versions (currently `1.4.0-SNAPSHOT`)
123+
- Release candidates: `1.x.x-rc.y`
124+
- Production releases: `1.x.x`
125+
- Helm chart versions for develop stay at `0.0.x-develop`; Docker image `tag: develop`, repo `mosipqa/...` (not `mosipid/...` which is production)
126+
127+
### Branch merge strategy
128+
When merging a release tag into develop (`PROMPT.md` pattern):
129+
- Default to release tag for all code changes
130+
- Keep develop's SNAPSHOT versions in all `pom.xml`
131+
- Keep develop's Helm chart versions (`0.0.x-develop`) and `mosipqa/` image repos in `values.yaml`
132+
- Take resource limits / javaOpts from the release tag
133+
- Version bump is done separately (`Snapshot.md` pattern): find-replace SNAPSHOT version strings in `pom.xml` files only
134+
135+
---
136+
137+
## Runtime Prerequisites (Local Dev)
138+
139+
1. **Config Server** running, pointed at a local clone of `mosip-config`
140+
2. **PostgreSQL 10+** with scripts from `db_scripts/` applied
141+
3. **Keycloak / auth server** (for services that validate auth tokens)
142+
4. `kernel-auth-adapter.jar` on classpath for auth-protected services
143+
144+
Config server local start command:
145+
```bash
146+
java -jar kernel-config-server-<version>.jar \
147+
-Dspring.profiles.active=native \
148+
-Dspring.cloud.config.server.native.search-locations=file:<path-to-mosip-config>/config
149+
```
150+
151+
API docs (Swagger) for each service are at `http://localhost:<port>/v1/<service-name>/swagger-ui.html`.
152+
153+
---
154+
155+
## CI/CD
156+
157+
CI runs on push via GitHub Actions (`.github/workflows/push-trigger.yml`). The workflow builds all modules, runs tests, and publishes SNAPSHOT artifacts to `https://central.sonatype.com/repository/maven-snapshots/`. GPG signing is required for publish but skipped locally with `-Dgpg.skip=true`. Sonar analysis runs under the `sonar` Maven profile.

‎README.md‎

Lines changed: 157 additions & 27 deletions
Original file line numberDiff line numberDiff line change
@@ -1,38 +1,168 @@
1-
[![Maven Package upon a push](https://github.com/mosip/commons/actions/workflows/push-trigger.yml/badge.svg?branch=develop)](https://github.com/mosip/commons/actions/workflows/push-trigger.yml)
2-
[![Quality Gate Status](https://sonarcloud.io/api/project_badges/measure?project=mosip_commons&metric=alert_status)](https://sonarcloud.io/dashboard?branch=develop&id=mosip_commons)
1+
# MOSIP Commons
32

4-
5-
# Commons
3+
[![Maven Package upon a push](https://github.com/mosip/commons/actions/workflows/push-trigger.yml/badge.svg?branch=release-1.3.x)](https://github.com/mosip/commons/actions/workflows/push-trigger.yml)
4+
[![Quality Gate Status](https://sonarcloud.io/api/project_badges/measure?branch=release-1.3.x&project=mosip_commons&metric=alert_status)](https://sonarcloud.io/dashboard?branch=release-1.3.x&id=mosip_commons)
65

76
## Overview
8-
As the name suggests, Commons refers to all the common services (also called "kernel") that are used by other modules of MOSIP.
97

10-
## Databases
11-
Refer to [SQL scripts](db_scripts).
8+
**MOSIP Commons** is a collection of foundational libraries used across all MOSIP microservices.
129

13-
## Build & run (for developers)
14-
The project requires JDK 1.11.
15-
1. Build and install:
16-
```
17-
$ cd kernel
18-
$ mvn install -DskipTests=true -Dmaven.javadoc.skip=true -Dgpg.skip=true
19-
```
20-
1. Build Docker for a service:
21-
```
22-
$ cd <service folder>
23-
$ docker build -f Dockerfile
24-
```
10+
It contains services to support configuration management, ID generation, notifications, and cryptographic salt generation.
2511

26-
## Deploy
27-
To deploy Commons services on Kubernetes cluster using Dockers refer to [Sandbox Deployment](https://docs.mosip.io/1.2.0/deployment/sandbox-deployment).
12+
---
13+
# Services
2814

29-
## Test
30-
Automated functaionl tests available in [Functional Tests repo](https://github.com/mosip/mosip-functional-tests).
15+
The following core services are part of MOSIP Commons:
3116

32-
## APIs
33-
API documentation is available [here](https://mosip.github.io/documentation/).
17+
---
3418

35-
## License
36-
This project is licensed under the terms of [Mozilla Public License 2.0](LICENSE).
19+
1. **[Kernel Notification Service](kernel/kernel-notification-service)** - Centralized notification service for sending messages such as SMS, emails.
20+
2. **[Kernel Config Server](kernel/kernel-config-server)** - Centralized configuration service used by all MOSIP microservices.
21+
3. **[Kernel RID Generator Service](kernel/kernel-ridgenerator-service)** - Generates globally unique Registration IDs (RID).
22+
4. **[Kernel ID Generator Service](kernel/kernel-idgenerator-service)** - Generates unique IDs required across MOSIP service.
23+
5. **[Kernel PRID Generator Service](kernel/kernel-pridgenerator-service)** - Generates Pre-Registration IDs (PRID).
24+
6. **[Kernel Salt Generator](kernel/kernel-salt-generator)** - Generates cryptographically strong salts for cryptographic operation.
25+
26+
27+
---
28+
29+
## Database
30+
Before starting the local setup, execute the required SQL scripts to initialize the database.
31+
All database SQL scripts are available in the [db scripts](./db_scripts) directory.
32+
33+
# Local Setup
34+
35+
## Prerequisites
36+
- **JDK:** 21
37+
- **Maven:** 3.9+
38+
- **Docker:** Latest
39+
- **PostgreSQL:** 10+
40+
- **Keycloak/IDP:** Required for notification authentication
41+
- **Config Server** with correct property files
42+
43+
44+
### Runtime Dependencies
45+
Add below runtime dependencies to the classpath, or include it as a Maven dependency:
46+
- Add `kernel-auth-adapter.jar`
47+
- Add `kernel-smsserviceprovider-msg91.jar`
48+
49+
### Configuration
50+
51+
Common module uses the following configuration files that are accessible in this [repository](https://github.com/mosip/mosip-config/tree/master).
52+
Please refer to the required released tagged version for configuration.
53+
- [application-default.properties](https://github.com/mosip/mosip-config/blob/master/application-default.properties) : Contains common configurations which are required across MOSIP modules.
54+
- [kernel-default.properties](https://github.com/mosip/mosip-config/blob/master/kernel-default.properties) : Contains configurations required or to be overridden for Commons module.
55+
56+
57+
## Installation
58+
59+
### Local Setup (for Development or Contribution)
60+
61+
1. Make sure the config server is running. For detailed instructions on setting up and running the config server, refer to the [MOSIP Config Server Setup Guide](https://docs.mosip.io/1.2.0/modules/registration-processor/registration-processor-developers-guide#environment-setup).
62+
63+
**Note**: Refer to the MOSIP Config Server Setup Guide for setup, and ensure the properties mentioned above in the configuration section are taken care of. Replace the properties with your own configurations (e.g., DB credentials, IAM credentials, URL).
64+
65+
2. Clone the repository:
66+
67+
```text
68+
git clone <repo-url>
69+
cd commons
70+
```
71+
72+
3. Build the project:
73+
74+
```text
75+
mvn clean install -Dmaven.javadoc.skip=true -Dgpg.skip=true
76+
```
77+
78+
4. Start the application:
79+
- Click the Run button in your IDE, or
80+
- Run via command: `java -jar target/specific-service:<$version>.jar`
81+
82+
5. Verify Swagger is accessible.
83+
84+
### Local Setup with Docker (Easy Setup for Demos)
85+
86+
#### Option 1: Pull from Docker Hub
87+
88+
Recommended for users who want a quick, ready-to-use setup — testers, students, and external users.
89+
90+
Pull the latest pre-built images from Docker Hub using the following commands:
91+
92+
```text
93+
docker pull mosipid/kernel-notification-service:1.3.0
94+
95+
```
96+
97+
#### Option 2: Build Docker Images Locally
98+
99+
Recommended for contributors or developers who want to modify or build the services from source.
37100

101+
1. Clone and build the project:
102+
103+
```text
104+
git clone <repo-url>
105+
cd commons
106+
mvn clean install -Dmaven.javadoc.skip=true -Dgpg.skip=true
107+
```
108+
109+
2. Navigate to each service directory and build the Docker image:
110+
111+
```text
112+
cd kernel/<service-directory>
113+
docker build -t <service-name> .
114+
```
115+
116+
#### Running the Services
117+
118+
Start each service using Docker:
119+
120+
```text
121+
docker run -d -p <port>:<port> --name <service-name> <service-name>
122+
```
123+
124+
#### Verify Installation
125+
126+
Check that all containers are running:
127+
128+
```text
129+
docker ps
130+
```
131+
132+
Access the services at `http://localhost:<port>` using the port mappings listed abov
133+
134+
135+
---
136+
137+
## Deployment
138+
139+
### Kubernetes
140+
141+
To deploy Admin services on a Kubernetes cluster, refer to the [Sandbox Deployment Guide](https://docs.mosip.io/1.2.0/deploymentnew/v3-installation).
142+
143+
144+
## Documentation
145+
146+
### API Documentation
147+
148+
API endpoints, base URL, and mock server details are available via Swagger documentation: [MOSIP Common Service API Documentation](https://mosip.github.io/documentation/1.2.0/1.2.0.html).
149+
150+
### Product Documentation
151+
152+
To learn more about MOSIP services from a functional perspective and use case scenarios, refer to our main documentation: [Click here](https://github.com/mosip/commons).
153+
154+
155+
---
156+
## Contribution & Community
157+
158+
• To learn how you can contribute code to this application, [click here](https://docs.mosip.io/1.2.0/community/code-contributions).
159+
160+
• If you have questions or encounter issues, visit the [MOSIP Community](https://community.mosip.io/) for support.
161+
162+
• For any GitHub issues: [Report here](https://github.com/mosip/commons/issues)
163+
164+
---
165+
166+
## License
38167

168+
This project is licensed under the [Mozilla Public License 2.0](LICENSE).

‎db_scripts/mosip_kernel/ddl/kernel-uin.sql‎

Lines changed: 13 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -15,6 +15,15 @@ CREATE TABLE kernel.uin(
1515

1616
);
1717
-- ddl-end --
18+
19+
--index section starts----
20+
CREATE INDEX IF NOT EXISTS idx_uin_status ON kernel.uin using btree(uin_status) where uin_status='UNUSED';
21+
CREATE INDEX IF NOT EXISTS idx_uin_uin ON kernel.uin using btree(uin);
22+
CREATE INDEX IF NOT EXISTS idx_uin_status_all ON kernel.uin USING btree (uin_status);
23+
CREATE INDEX IF NOT EXISTS idx_uin_status_crdtime ON kernel.uin USING btree (uin_status, cr_dtimes);
24+
CREATE INDEX IF NOT EXISTS idx_uin_status_isdeleted ON kernel.uin USING btree (uin_status, is_deleted);
25+
--index section ends------
26+
1827
COMMENT ON TABLE kernel.uin IS 'UIN: Stores pre-generated UINs that are assigned to an individual as part of registration process.';
1928
-- ddl-end --
2029
COMMENT ON COLUMN kernel.uin.uin IS 'UIN: Pre-generated UINs (Unique Identification Number), which will be used to assign to an individual';
@@ -34,3 +43,7 @@ COMMENT ON COLUMN kernel.uin.is_deleted IS 'IS_Deleted : Flag to mark whether th
3443
COMMENT ON COLUMN kernel.uin.del_dtimes IS 'Deleted DateTimestamp : Date and Timestamp when the record is soft deleted with is_deleted=TRUE';
3544
-- ddl-end --
3645

46+
47+
-- autovacuum tuning section starts --
48+
ALTER TABLE uin SET (autovacuum_vacuum_scale_factor = 0.05, autovacuum_vacuum_threshold = 1000, autovacuum_analyze_scale_factor = 0.03, autovacuum_analyze_threshold = 500);
49+
-- autovacuum tuning section ends --

‎db_scripts/mosip_kernel/ddl/kernel-vid.sql‎

Lines changed: 12 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -35,3 +35,15 @@ COMMENT ON COLUMN kernel.vid.is_deleted IS 'IS_Deleted : Flag to mark whether th
3535
-- ddl-end --
3636
COMMENT ON COLUMN kernel.vid.del_dtimes IS 'Deleted DateTimestamp : Date and Timestamp when the record is soft deleted with is_deleted=TRUE';
3737
-- ddl-end --
38+
39+
-- PERFORMANCE OPTIMIZATION INDEXES
40+
CREATE INDEX idx_vid_status_not_deleted ON kernel.vid (vid_status) WHERE is_deleted = false;
41+
CREATE INDEX CONCURRENTLY idx_vid_status_isdeleted ON kernel.vid (vid_status, is_deleted);
42+
CREATE INDEX IF NOT EXISTS idx_vid_status_available_not_deleted ON kernel.vid USING btree (vid_status) WHERE vid_status = 'AVAILABLE' AND is_deleted = false;
43+
CREATE INDEX IF NOT EXISTS idx_vid_status_crdtime ON kernel.vid USING btree (vid_status, cr_dtimes);
44+
CREATE INDEX IF NOT EXISTS idx_vid_status_unused ON kernel.vid USING btree (cr_dtimes) WHERE vid_status = 'UNUSED';
45+
46+
47+
-- autovacuum tuning section starts --
48+
ALTER TABLE vid SET (autovacuum_vacuum_scale_factor = 0.05, autovacuum_vacuum_threshold = 1000, autovacuum_analyze_scale_factor = 0.03, autovacuum_analyze_threshold = 500);
49+
-- autovacuum tuning section ends --

‎db_upgrade_scripts/mosip_kernel/sql/1.2.0.1_to_1.2.0.2_rollback.sql‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1 @@
1+
\echo 'Rollback Queries not required for transition from $CURRENT_VERSION to $UPGRADE_VERSION'

0 commit comments

Comments
 (0)