riagie / libraries-utils

0.0.1 2023-04-19 04:04 UTC

Requires

• php: >=7.2
• giggsey/libphonenumber-for-php: ^8.12
• php-curl-class/php-curl-class: ^9.5
• phpmailer/phpmailer: ^6.5
• pragmarx/random: ^0.2.2
• ramsey/uuid: ^4.2
• spatie/array-to-xml: ^2.15
• wolfcast/browser-detection: ^2.9

Requires (Dev)

• phpunit/phpunit: ^9.5
• symfony/var-dumper: ^5.4

MIT

• Ogie Nurdiana

• api
• client
• server
• libraries
• automation

Published on Packagist.org on 2023-06-22 09:37 UTC

README

Engine service generator identifier (ADR-045). Identitas env: TYPE=engine, NAME=libraries-utils (mengikuti nama unit). Pemanggil: unit internal (app, api, service pendukung) lintas bahasa — bukan untuk pihak luar. Implementasi lama (library) sudah dipensiunkan — acuan parity via git history commit awal unit (ADR-052).

Prinsip: Terpusat vs Lokal (ADR-047/050)

Pemanggil beragam bahasa — engine hanya melayani fungsi yang wajib identik lintas bahasa atau butuh dependensi/egres terpusat. Fungsi lain dihitung native di app masing-masing; kode porting tanpa endpoint TIDAK dibawa ke runtime (ADR-050) — acuannya arsip reference/:

Grup	Fungsi	Penempatan
Kontrak identifier	uuid, secret, refnum, token, apiId, ppid, unique	ENGINE — format dijaga 1 sumber kebenaran (ADR-LIB-001)
Dependensi berat	phoneNumber	ENGINE — lib + data carrier tak perlu di-shipping tiap app
Egres eksternal	geolocation	ENGINE — call keluar + rate limit terpusat
Waktu & format	setStartTime, getElapsedTime, setExpired, Object, Json, Xml, Text, Debug	LOKAL — native di bahasa masing-masing; tanpa endpoint
Konteks request	clientIp, clientBrowser	LOKAL — data asal ada di pemanggil; parser native
Konteks proses	getEnv, loadFile, database	INTERNAL-ONLY — konteks proses tak bisa dibawa lewat HTTP (salah konteks)
Standar HTTP internal	setHeaders, setOpts	internal engine (helper geolocation)

Endpoint (9 + info root)

Base: http://{HOST}:{PORT} (default http://127.0.0.1:30150) — format respon lihat section Format Respon; path tak dikenal → 404 bentuk framework (satu-satunya pengecualian, ADR-054).

Method	Path	Fungsi	Body
GET	/	info & health service (status, name, env)	—
POST	/api/v1/uuid	uuid() — multi-versi, lihat Versi UUID	opsional, tanpa body = v4
POST	/api/v1/secret	secret() — 32 char lowercase	—
POST	/api/v1/refnum	refnum() — 32 char uppercase	—
POST	/api/v1/token	token() — 28 char mixedcase	—
POST	/api/v1/api-id	apiId() — api- + 10 digit	—
POST	/api/v1/ppid	ppid() — 16 char alfanumerik	{"text": "DUMMY NAME"}
POST	/api/v1/unique	unique() — prefix indeks alfabet + digit	{"character": "D", "length": 6} (opsional)
POST	/api/v1/phone-number	phoneNumber()	{"phone": "081323456789", "country": "ID"}
POST	/api/v1/geolocation	geolocation() — lihat Mode geolocation	{"ip": "1.2.3.4"} (opsional)

Cara Hit

Semua endpoint inti: POST, Content-Type: application/json (endpoint tanpa body boleh tanpa header), tanpa auth — berjalan sepenuhnya di jaringan internal (ADR-046). Contoh dari bahasa pemanggil apa pun:

POST http://127.0.0.1:30150/api/v1/refnum

POST http://127.0.0.1:30150/api/v1/ppid           body: {"text": "DUMMY NAME"}
POST http://127.0.0.1:30150/api/v1/unique         body: {"character": "D", "length": 6}
POST http://127.0.0.1:30150/api/v1/phone-number   body: {"phone": "081323456789"}
POST http://127.0.0.1:30150/api/v1/geolocation    body: {"ip": "8.8.8.8"}
POST http://127.0.0.1:30150/api/v1/uuid           body: {"version": 3, "namespace": "dns", "name": "example.org"}

GET  http://127.0.0.1:30150/                      (info & health)

Format Respon (ADR-054 — aturan penuh: _docs/ENGINE-RESPONSE.md)

Format khusus engine — berbeda dari layer non-engine (envelope {RC, RCM, DATA, P}):

Kondisi	HTTP	Body
Sukses ("0200")	200	{"data": <isi>}
Parameter salah ("0400")	400	{"message": "INVALID REQUEST PARAMETER"}
Gagal internal ("0500")	500	{"message": "INTERNAL SERVER ERROR"}

• Kode varchar CORE_API — HTTP status = int kode; daftar kode & pesan resmi: _docs/RESPONSE-CODES.md (satu-satunya tabel).
• Tanpa P (pagination) — engine tidak mengenal pagination.
• Body JSON rusak / bukan JSON valid (dengan Content-Type json) → 400 {"message": "INVALID REQUEST PARAMETER"}.
• Contoh: POST /api/v1/refnum → {"data": "E1JL7J341HGV4LTLRDBWAVMGKVL5XJYO"}

Versi UUID (ADR-048)

Endpoint /api/v1/uuid menerima body opsional untuk memilih versi — format hasil selalu 36 char sesuai kontrak:

Body	Versi	Sifat
(tanpa body) / {"version": 4}	v4	random — perilaku lama, default
{"version": 1, "node": "aabbccddeeff", "msecs": 1760000000000}	v1	time-based; node & msecs opsional
{"version": 2, "domain": "person", "id": 1000, "node": "...", "msecs": ...}	v2	DCE security; domain (person/group/org/domain) + id wajib
{"version": 3, "namespace": "dns", "name": "example.org"}	v3	deterministik (MD5); namespace alias dns/url/oid/x500 atau UUID custom + name wajib

Perhatian: v2/v3 deterministik — input sama menghasilkan UUID sama; v1/v2 memuat timestamp (bukan untuk kebutuhan kerahasiaan). Input kurang/tidak valid → 400.

Mode geolocation (ADR-049)

Panggilan	Hasil
{"ip": "<IP mitra>"}	detail lengkap IP yang diberikan — pola utama: app utama meneruskan IP mitra yang diterimanya langsung dari koneksi
(tanpa ip)	auto-detect = IP publik server engine (egress bersama jaringan internal) — untuk profil IP publik sendiri, BUKAN mitra

Pemanggil yang butuh geo mitra wajib forward IP via body — tanpa ip untuk kebutuhan mitra menghasilkan lokasi server, bukan mitra.

Pemanggil Lintas Bahasa

Engine = jembatan kontrak, bukan pengganti library. Dipanggil dari app utama/service lain (bahasa apa pun) — lihat Cara Hit. Format hasil dijamin identik dengan tabel kontrak di AGENTS.md folder _libraries (ADR-LIB-001) — refnum 32 char uppercase, uuid 36 char, dst. Fungsi waktu/format/konteks: pakai native bahasa app masing-masing; kebutuhan util lokal non-kontrak lintas platform kelak disediakan _libraries-core (ROADMAP).

Akses

Service ini global-INTERNAL — hanya untuk unit internal (app, api, service pendukung); TIDAK untuk pihak luar. TANPA auth/API key (ADR-046) karena berjalan sepenuhnya di jaringan internal — wajib ditempatkan di jaringan internal. Fungsi berisiko wajib tetap tanpa endpoint; dilarang menambah endpoint yang mengekspos env, file server, atau konfigurasi.

Menjalankan

cp .env.example .env   # lalu sesuaikan
make dev               # development (hot reload) — lokal TANPA container
make run               # produksi tanpa build
make build             # build binary ke bin/
make test              # test suite parity
make clean

Dokumentasi API (OpenAPI): GET /docs saat service berjalan.

Deployment

• Lokal: jalan langsung via make dev / make run — tanpa container.
• Produksi: via container — Dockerfile + docker-entrypoint.sh, port 30150. Konfigurasi disuntik saat run (env container / env_file) — .env tidak dibaking ke image (lihat .dockerignore); kesehatan service dicek via GET /.

Konfigurasi (.env)

Variabel	Default	Fungsi
TYPE	engine	tipe unit (engine)
ENV	development	mode
NAME	libraries-utils	nama service (mengikuti nama unit)
HOST	0.0.0.0	bind host
PORT	30150	port service (registry PORTS)
TIMEOUT	60	timeout call keluar service (geolocation), detik

Struktur

_libraries-utils/
├── main.ts               # entry service
├── routes/api.ts         # registrasi endpoint (9 inti) + info root
├── src/
│   ├── config/           # baca .env
│   ├── controllers/      # handler endpoint (ApiController)
│   ├── helpers/          # generator live + envelope/RC + HTTP helper geolocation + logger
│   ├── middlewares/      # kosong — service global internal tanpa auth (ADR-046);
│   │                     # logging via helpers/logger (middleware request — ADR-055)
│   ├── migrations/       # kosong — engine stateless tanpa DB
│   ├── models/           # kosong — engine stateless tanpa DB
│   └── types/            # tipe request/response + deklarasi vendor
├── tests/                # test suite parity (36 test) — ter-track git
├── storage/              # GIT-IGNORED penuh — artefak runtime (log harian, dll.)
├── Makefile, Dockerfile, .dockerignore, docker-entrypoint.sh
└── .env / .env.example

Parity & Limitasi

• Fungsi arsip yang diekspos: 7 generator + phoneNumber + geolocation (ADR-047); porting 1:1 — kode non-ekspos dihapus dari runtime; acuan parity = git history commit awal unit (src/Utils.php asli — ADR-052).
• providerNumber pada phoneNumber() selalu kosong — pemetaan carrier tidak tersedia di runtime baru; field lain identik.
• geolocation() memanggil layanan publik ip-api.com (free tier, rate limit) — versi JSON dengan field yang sama seperti arsip. Perbaikan perilaku: mode forward IP kini memakai IP di path URL (/json/{ip}) — di arsip lama mode ini tidak pernah berfungsi karena parameter query diabaikan layanan geo (selalu ter-resolve ke IP pemanggil).
• uuid() multi-versi: v4 identik arsip (uuid4()); v1/v2/v3 = kemampuan baru (ADR-048), v3 terkunci test vector resmi.

Testing

make test

36 test: kontrak generator (panjang/format), uuid multi-versi (v1–v4 + validasi), format respon engine (kode varchar → HTTP, bentuk data/message, validasi 0400), logger (timestamp/rotasi/mask/pasangan REQ-RES), phoneNumber, http helper — kode non-live tidak lagi dites (ADR-050). Test suite berada di tests/ (root unit) dan ter-track git.

Logging (ADR-055 — aturan penuh: _docs/LOGS.md)

Setiap hit dicatat pasangan REQ–RES ke storage/logs/{YYYYMMDD}.log (rotasi harian, git-ignored):

[Mon Oct 12 14:20:29 2026 +0700][INFO][api-3920498356] REQ POST /api/v1/refnum id=3a8ab03d-252c body={}
[Mon Oct 12 14:20:29 2026 +0700][INFO][api-3920498356] RES POST /api/v1/refnum id=3a8ab03d-252c http=200 durasi_ms=12 body={"data":"..."}

Engine meng-generate api-id per hit dan mengembalikannya di header respon X-Api-Id — pemanggil tidak perlu mengirim header apa pun (nilai berguna sebagai nomor referensi trace). Respon HTTP ≥ 400 tercatat bertipe WARNING; kredensial otomatis dimasking.