Kiến trúc IAUP

IAUP là một plugin Bukkit nhỏ với pipeline upload async có guard. Mục tiêu thiết kế chính: không block server thread, reject work cũ sau reload, và cập nhật ItemsAdder config có tính quyết định.

Component chính

ItemsAdderUploadPlus sở hữu:

• command handling
• lifecycle
• settings snapshot
• upload-in-progress guard
• hook registration
• upload orchestration

PluginSettings parse và validate config thành object setting immutable.

S3UploadService build S3 client, upload zip, và trả về object key cùng download URL.

ItemsAdderConfigUpdater ghi URL cuối cùng vào ItemsAdder config.

ItemsAdderHookRegistrar đăng ký listener ItemsAdder pack-compressed event khi có.

Enable flow

Khi enable:

1. tạo message service
2. tạo hook registrar
3. save default config
4. parse settings
5. đăng ký /iaup
6. bắt đầu lifecycle epoch mới
7. bind ItemsAdder hook nếu bật

Nếu parse settings fail, IAUP tự disable.

Upload guard

IAUP dùng atomic boolean:

uploadInProgress

Nó ngăn upload chồng lên nhau. Flag được set trước khi schedule async task và clear trong finally.

Async upload pipeline

Upload task chạy bất đồng bộ:

1. build S3 client
2. build object key từ path_scheme
3. upload generated.zip với content type application/zip
4. áp dụng canned ACL trừ khi acl là none
5. build public hoặc presigned download URL
6. cập nhật ItemsAdder config
7. gửi success/failure message
8. tùy chọn schedule /iareload về main thread

S3 client shutdown sau khi upload hoàn tất.

Lifecycle epoch

Reload và shutdown có thể xảy ra khi async upload đang chạy. IAUP dùng lifecycle epoch để ngăn task cũ apply kết quả cũ.

Khi upload start, plugin capture:

runEpoch = lifecycle.currentEpoch()

Trước khi ghi config hoặc dispatch reload, task kiểm tra epoch đó còn hiện hành không. Nếu không, nó exit mà không apply state cũ.

Reload flow

/iaup reload:

1. parse setting mới
2. bắt đầu lifecycle epoch mới
3. clear upload-in-progress
4. swap settings
5. rebind hook

Nếu rebind fail, IAUP cố restore setting và hook trước đó.

Build URL

Object key placeholder được replace trước:

{uid} {file} {name} {ext} {date} {ts}

Sau đó chọn URL mode:

• presigned URL nếu use_presigned_url true
• public_url_base/objectKey nếu public base được đặt
• endpoint/bucket/objectKey cho path-style endpoint mode
• S3 SDK object URL trong các case còn lại

Cache busting append query parameter sau khi URL được build.

Chiến lược cập nhật ItemsAdder config

IAUP đọc ItemsAdder config dưới dạng line trước và cố thay đúng:

resource-pack.hosting.external-host.url

Cách này giữ hầu hết formatting và comment. Nếu replace theo line fail, IAUP fallback sang Bukkit YamlConfiguration, set cùng path, rồi save file.