Semantik eksekusi, batasan, dan keamanan

Halaman ini merangkum bagaimana Script berperilaku saat runtime (urutan, transaksi, error, penguncian), batasan statis apa yang dikenakan saat disimpan, dan model keamanannya. Untuk sintaksis, lihat Katalog Statement dan Ekspresi nilai; untuk kombinasi praktis, lihat Cookbook.

Urutan eksekusi

• statements dieksekusi secara berurutan dari atas ke bawah. Ketika mencapai Return, eksekusi berhenti di titik tersebut.
• Eksekusi berlangsung secara inline, pada jalur yang menangani permintaan panggilan. Respons panggilan itu sendiri adalah hasil eksekusi (untuk bentuk responsnya, lihat Permintaan dan respons di Ikhtisar Script), dan waktu yang diberikan untuk satu eksekusi dibahas di Anggaran waktu di bawah.

Semantik eksekusi

Guard (prakondisi)

Tidak ada Statement guard khusus. Anda menyatakannya dengan If dan then:[Return]. Ketika kondisi dilanggar, ia mengembalikan hasil dan tidak menjalankan Statement selanjutnya (tentu saja Script tanpa guard juga dimungkinkan).

{ "type": "If", "condition": { "<": [ "{ /wallet/fields/balance/en-US }", "{ /payload/fields/cost }" ] },
  "then": [ { "type": "Return", "value": { "ok": false, "reason": "insufficient credit" }, "statusCode": 402 } ] }

Tanpa transaksi dan kompensasi best-effort

Script bukanlah transaksi. Saat gagal, engine mencoba mengompensasi (compensation) pekerjaan yang telah dilakukan sejauh ini dan mengembalikan penyebab error, tetapi dengan keterbatasan berikut (diterima sebagai konsekuensi desain).

• Membatalkan penghapusan membuat sys.id baru, sehingga referensi yang tadinya menunjuk ke sana menjadi rusak.
• Efek eksternal (Http) bersifat ireversibel (panggilan yang sudah keluar beserta biayanya tidak dapat dibatalkan).
• Kompensasi bisa sama sekali tidak berjalan, sehingga keadaan yang belum terkompensasi dapat tertinggal.

Jika Anda membutuhkan atomisitas sejati, tulis sendiri kompensasi di dalam Script tersebut, atau tempatkan operasi yang tidak dapat dibatalkan (misalnya panggilan eksternal) di paling akhir. Urutan yang paling berbahaya adalah yang "berhasil dirantai tetapi tidak dapat di-rollback, namun tampak aman."

Penguncian optimis

Persaingan update/patch dipersempit dengan version pada ResourceUpdate dan ResourcePatch. Jika Anda memberikan version (ekspresi nilai, Int), pembaruan dilakukan hanya jika cocok dengan sys.version target saat ini; ketidakcocokan di-abort karena error konflik versi (dapat ditangani secara lokal dengan Try/catch). Jika dihilangkan, berlaku last-write-wins tanpa pemeriksaan. Biasanya Anda membaca terlebih dahulu dengan ResourceRead atau ResourceFind lalu meneruskan sys.version tersebut (lihat CAS penguncian optimis di Cookbook).

Penulisan berbasis origin

Penulisan selalu tercermin di origin (draft), dan apakah diekspos ke delivery (CDA/ACDA) dikendalikan oleh publish (publish pada ResourceCreate/ResourceUpdate/ResourcePatch, atau ResourcePublish/ResourceUnpublish).

Apa yang dianggap sebagai kegagalan

Jika satu Statement gagal di tengah eksekusi, eksekusi berhenti di titik itu, kecuali ada Try yang menangani kegagalan tersebut. Pada saat itu engine mencoba membatalkan pekerjaan yang telah dilakukan sampai saat itu. Pembatalan ini memiliki keterbatasan, dan detailnya dibahas di Tanpa transaksi dan kompensasi best-effort.

Jika Statement yang gagal berada di dalam Try, kegagalan itu dapat ditangani di catch. Di dalam catch, Anda merujuk isi kegagalan ({ message }) melalui /error. Statement mana yang gagal tidak disertakan di dalamnya.

Kasus-kasus berikut diperlakukan sebagai kegagalan.

• Operasi resource gagal (target tidak ada, versi tidak cocok, operasi tidak didukung, dan sebagainya)
• Http gagal (lihat Dua cara Http gagal)
• Transformasi file Media gagal (lihat Kasus ketika transformasi file gagal)
• Batas atas runtime yang ditetapkan untuk setiap Statement terlampaui (misalnya, Batas atas panjang nilai)

Return bukanlah kegagalan. Return mengakhiri eksekusi lebih awal secara normal, sehingga tidak berpindah ke catch.

Dua cara Http gagal

Kegagalan Http terbagi menjadi dua jenis, tergantung apakah kegagalan itu ditangani sebagai respons status. Perbedaan ini menentukan apakah retry dan ignoreStatusCode berlaku.

Kondisi kegagalan selama proses pengiriman file dibahas secara rinci di Mengirim file sebagai body.

Agregasi sisi server hanya untuk jumlah

Jumlahnya dihitung di sisi server oleh ResourceCount. Karena ia tidak membaca itemnya, ia tidak terikat pada batas atas jumlah item yang diproses.

Untuk sum dan group-by tidak ada operasi server khusus. Agregasi semacam itu harus Anda hitung sendiri dengan menelusuri ResourceForEach lalu menggunakan SetVar dan JsonLogic, sehingga terikat pada batas atas jumlah item yang diproses (tidak cocok untuk mengagregasi jutaan record). Jika Anda hanya membutuhkan jumlahnya, gunakan ResourceCount alih-alih menelusuri.

Tanpa penungguan atau penundaan

Script tidak memiliki Statement Delay. Script dieksekusi sekali lalu selesai, dan tidak menunggu atau melakukan polling secara internal hingga job eksternal selesai.

Batasan statis (divalidasi saat disimpan)

Berikut ini diperiksa pada saat Script disimpan (pembuatan/perubahan). Jika dilanggar, penyimpanan ditolak (gagal saat penyusunan, bukan saat runtime). Pelanggaran mana yang ditolak dengan kode mana dibahas di Error.

Batas tetap pada tabel di atas adalah nilai yang ditetapkan platform, sehingga sama tanpa memandang paket. Sebaliknya, jumlah total Statement dan jumlah panggilan eksternal per definisi adalah batas per paket. Karena keduanya bukan error validasi melainkan batas paket, jika terlampaui, penyimpanan/pengubahan ditolak karena melampaui batas paket (definisi yang sama diperbolehkan pada paket yang lebih tinggi) dan dibuka dengan peningkatan paket. Angka per paket ada di Paket Harga.

Berbeda dengan panggilan eksternal seperti Http, EmailSend, penyerapan file Media tidak dihitung terhadap batas panggilan eksternal per definisi.

ResourceForEach adalah Statement komposit yang memiliki anak, sehingga Statement itu sendiri tidak dihitung ke jumlah panggilan eksternal. Statement panggilan eksternal (Http, EmailSend) di dalam onEach-lah yang dihitung (secara statis dihitung sebagai 1, tetapi benar-benar dijalankan untuk tiap item selama penelusuran). onEach dapat memuat panggilan eksternal atau penyerapan file Media, dan hal ini juga berlaku untuk body Loop. Berapa kali perulangan itu benar-benar berputar tidak masuk ke hitungan ini, melainkan masuk sebagai perkalian pada Anggaran waktu di bawah.

Batas atas panjang nilai (runtime)

Statement tanda tangan dan pemrosesan teks, serta Cache, memiliki batas atas untuk ukuran nilai yang ditanganinya. Yang dibatasi bukan panjang ekspresinya, melainkan panjang nilai hasil resolve dari ekspresi itu (enam belas karakter { /rawPayload } menunjuk ke puluhan KB), sehingga pemeriksaannya terjadi selama eksekusi, bukan saat penyimpanan.

• Keempatnya sama seperti kegagalan runtime lainnya sehingga dapat ditangani secara lokal dengan Try/catch.
• Batas atas Signature disesuaikan dengan ukuran body yang benar-benar dikirim penyedia (peristiwa pembayaran berukuran beberapa KB, dan webhook pesanan mencapai puluhan KB). Hash menempati posisi yang menyambung beberapa field saja, sehingga jauh lebih sempit.
• Angka 128 karakter untuk Regex.pattern adalah pemeriksaan saat penyimpanan pada Batasan statis di atas. Panjang itu bukan perangkat untuk mencegah ledakan komputasi ((a+)+$ sudah berbahaya hanya dengan enam karakter). Yang mencegah ledakan adalah aturan yang mengharuskan pattern ditulis sebagai literal serta anggaran waktu di bawah; yang dijanjikan panjang itu hanyalah ukuran yang masih dapat dibaca dan ditinjau manusia.

Anggaran waktu (runtime)

Waktu yang diizinkan untuk satu eksekusi paling lama 180 detik. Waktu yang benar-benar diizinkan ditentukan oleh definisi Script (dan juga oleh paket jika mengirim file), yaitu dasar 30 detik ditambah waktu yang dapat dipakai oleh panggilan eksternal.

Anggaran ini berlaku untuk eksekusi secara keseluruhan. Terpisah dari itu, satu permintaan Http harus selesai dalam timeoutMs milik permintaan tersebut.

Dasar 30 detik

Semua pekerjaan yang bukan panggilan eksternal, seperti membaca dan menulis resource atau menerima dan memproses file Media, diproses di dalam 30 detik ini. Script tanpa panggilan eksternal diberi 30 detik.

Waktu yang ditambahkan per Statement

Waktu Statement yang diletakkan berurutan dijumlahkan seluruhnya.

Jika tidak ada panggilan eksternal di dalam perulangan, waktu yang ditambahkan tetap 0 meskipun dikalikan dengan jumlah iterasi. Karena itu, perulangan semacam itu harus selesai di dalam dasar 30 detik.

Waktu unduhan per file

Nilai ini adalah waktu yang dibutuhkan untuk menerima data sebesar batas unduhan paket dengan kecepatan 10.000.000 byte per detik.

Contoh perhitungan

Script yang memanggil satu Http (timeoutMs 30 detik, retry 1) yang mengirim dua foto pada paket Pro dihitung sebagai berikut.

• Http: (30 detik + 10,5 detik × 2) × 2 = sekitar 102 detik
• Seluruh eksekusi: 30 detik + 102 detik = sekitar 132 detik

132 detik lebih pendek daripada 180 detik, sehingga Script ini diberi 132 detik.

Jika melebihi 180 detik

Meskipun nilai hasil perhitungan melebihi 180 detik, Script tetap tersimpan dan dijalankan. Namun, eksekusi dihentikan begitu mencapai 180 detik.

Batas jumlah per paket

Untuk Script, jumlah per Organization dibatasi oleh paket.

Terpisah dari itu, jumlah Statement dan jumlah panggilan eksternal (Http, EmailSend) yang dapat dimuat oleh satu definisi Script juga dibatasi oleh paket. Saat menyimpan/mengubah definisi, jika melampaui batas paket tersebut, permintaan ditolak; untuk angka konkretnya, lihat Paket Harga.

Ketika batas tercapai, pembuatan Script baru ditolak.

Ukuran unduhan file Http

Ketika Http mengambil file yang akan dikirim sebagai body permintaan dari URL (urlBody, part url pada multipartBody), ukuran yang dapat diterima per URL file dibatasi oleh paket. Yang berlaku adalah paket dari Organization tempat Space pemilik Script tersebut berada.

• Batas ini berlaku terpisah untuk setiap URL. Jika ada beberapa part url, setiap file harus berada dalam batas ini.
• Jika Anda mencoba mengirim file yang melampaui batas, Http tersebut gagal (lihat Dua cara Http gagal).
• Batas ini juga menjadi dasar waktu unduhan yang ditambahkan ke Anggaran waktu.

Model keamanan

secrets

Nilai rahasia seperti kunci API eksternal, kunci rahasia penyedia pembayaran (PG), kunci tanda tangan webhook, atau nilai autentikasi Basic … yang sudah dihitung sebelumnya tidak ditulis apa adanya di Statement. Deklarasikan nilai itu di secrets pada definisi, lalu baca di Statement dengan { /secrets/<key> }. Kunci uji yang dipublikasikan juga diletakkan di tempat yang sama. Dengan begitu, saat beralih ke kunci sungguhan, Statement tidak perlu diubah dan Anda cukup mengganti nilai di secrets.

"secrets": [
  { "key": "LLM_API_KEY",            "value": "sk-...",    "description": "Kunci API untuk memanggil LLM" },
  { "key": "WEBHOOK_SIGNING_SECRET", "value": "whsec_...", "description": "" }
],
"statements": [
  { "type": "Http", "method": "POST", "url": "https://api.openai.com/v1/chat/completions",
    "headers": [ { "key": "Authorization", "value": "Bearer { /secrets/LLM_API_KEY }" } ],
    "body": { /* ... */ }, "name": "llm" }
]

• Penyimpanan: value dienkripsi dan disimpan dengan aman oleh WEEGLOO. Statement membaca nilai aslinya dengan { /secrets/<key> }.
• Pembacaan: dalam respons API yang mengembalikan Script (pembacaan, pembuatan, perubahan), value dikembalikan sebagai nilai aslinya. Role yang dapat membaca Script itu dapat melihat nilainya, jadi persempit izin bacanya. Anggota (ServiceUser) tidak dapat membaca definisi Script (pembacaan dan penyusunannya khusus CMA, dan ACMA tidak memiliki Script API).
• Perubahan: perubahan penuh (PUT) mengganti seluruh definisi. Jika Anda mengirimnya tanpa secrets, nilai rahasia yang sudah dideklarasikan akan terhapus, dan jika Statement masih mereferensikan nilai itu dengan { /secrets/… }, penyimpanan ditolak. Karena itu, kirimkan secrets setiap kali Anda melakukan perubahan. Anda cukup mengirim kembali nilai dari respons pembacaan apa adanya.
• Nilai selama eksekusi: apa yang dilakukan terhadap nilai yang dibaca ditentukan oleh Statement. Jika nilai itu dikembalikan dengan Return, nilainya tercatat di respons eksekusi dan ScriptLog, dan jika dimasukkan ke SetVar, Cache, Content, nilainya tersimpan sebagai nilai asli di tempat tersebut. Kirim nilai rahasia hanya ke API eksternal yang membutuhkan nilai itu.
• App Bundle: saat Script dipaketkan menjadi App Bundle, value pada secrets disamarkan menjadi ******, sedangkan key dan description ikut dimuat apa adanya. Script yang dibuat dengan menginstal App Bundle tersebut memiliki nilai rahasia berupa ******, sehingga Statement yang membaca nilai itu baru berfungsi setelah pihak yang menginstal memasukkan nilai sebenarnya. Nilai yang ditulis di luar secrets (header Http, secret pada Signature, dan sebagainya) tidak disamarkan dan ikut dimuat apa adanya.

Satu Script dapat memiliki hingga 20 secrets. Aturan pointer dibahas di /secrets pada Ekspresi nilai.

Identitas eksekusi dan otorisasi

• Identitas eksekusi: selama eksekusi, setiap operasi resource dilakukan dengan identitas pengguna yang memanggil /execute. createdBy/updatedBy dari resource yang dibuat atau diubah adalah pemanggil, dan cakupan createdBy: ":self" juga diuraikan berdasarkan pemanggil. Pengecualiannya adalah panggilan anonim. Eksekusi yang masuk melalui /execute/anonymous tidak memiliki pemanggil, sehingga keduanya diuraikan berdasarkan penulis (Panggilan anonim).
• Ada dua batas otorisasi, dan saat runtime izin resource tidak diperiksa ulang pada setiap Statement.
  1. Saat penyusunan (penyimpanan): ketika sebuah Script disimpan, sistem memeriksa apakah penulis benar-benar memiliki izin resource dan aksi yang dipakai oleh Statement di dalamnya. Jika satu saja tidak ada, penyimpanan ditolak. Dengan kata lain, Script yang memuat operasi tanpa izin memang tidak akan pernah tersimpan sejak awal. Statement yang memilih resource, baik berupa leaf maupun ResourceForEach yang memiliki blok, semuanya menjalani pemeriksaan ini. Definisi yang sudah tersimpan pun diperiksa ulang ketika diubah, sehingga setelah izinnya dicabut, definisi itu tidak dapat diperbaiki dan disimpan lagi.
     • Direktori anggota (ServiceUser) diperiksa bukan lewat map izin, melainkan lewat sumbu pengaturan. Untuk memakai resource: "ServiceUser" pada tiga Statement pembacaan serta ResourceUpdate dan ResourcePatch, settings pada SpaceRole penulis harus memuat SETTING_SERVICE_LOGIN (atau SETTING_ALL) (settings pada SpaceRole). Alasannya, direktori anggota adalah resource yang dikelola pengaturan Space di semua jalur lainnya juga.
     • Statement yang membuat atau menghapus anggota tidak dapat disimpan dengan role apa pun. Karena Script tidak dapat membuat atau menghapus anggota, penolakannya bukan karena izin kurang (403) melainkan karena Statement yang salah tulis (400). Artinya, ini bukan celah yang bisa ditutup dengan menambah izin. Perubahan yang diizinkan hanyalah roleOverride dan enableLogin pada ResourceUpdate dan ResourcePatch (Menangani direktori anggota).
  2. Saat pemanggilan (/execute): hanya izin Execute Script milik pemanggil yang diperiksa. Tanpa izin itu, hasilnya 403. Jika lolos, izin resource per Statement tidak diperiksa lagi saat runtime; eksekusi langsung berjalan. Cara kerjanya seperti izin eksekusi fungsi dalam pemrograman. Jika Anda memiliki izin untuk menjalankan fungsi tersebut, izin untuk setiap operasi individual di dalamnya tidak ditanyakan lagi. Pada jalur panggilan anonim, pemeriksaan ini tidak ada. Sebab tidak ada pemanggil yang bisa diperiksa, sehingga membuka jalur itu setara dengan mempublikasikan satu Script tanpa autentikasi.
• Pemblokiran pemanggilan langsung (directCallEnabled): jika directCallEnabled dari Script bernilai false, pemanggilan langsung /execute itu sendiri ditolak. Gerbang ini terkena setelah pemeriksaan izin Execute dilewati, sehingga pemanggilan tetap terblokir meskipun Anda memiliki izin Execute. Pemanggil yang tidak memiliki izin menerima 403 sebelum mencapai gerbang ini. Karena gerbang ini hanya ada pada endpoint tersebut, aksi terhubung (script) pada Webhook dan Scheduler tetap menjalankannya seperti biasa. Nilai bawaannya adalah true (memperbolehkan pemanggilan langsung).
• Panggilan anonim (anonymousCallEnabled): nilai bawaannya adalah false. Jika disetel true, hanya Script itu yang juga dapat dijalankan melalui jalur khusus tanpa autentikasi (/execute/anonymous), dan saat itu identitas eksekusinya adalah penulis, bukan pemanggil. Dari kedua batas di atas, pemeriksaan saat pemanggilan (izin Execute) tidak ada pada jalur itu, sehingga autentikasi yang sebenarnya dilakukan oleh Script itu sendiri (verifikasi tanda tangan atas permintaan yang diterima). Syarat mengaktifkannya dan aturan penyimpanannya dibahas di Panggilan anonim.
• Cakupan kepemilikan: createdBy: ":self" pada filter where berarti "hanya yang dibuat oleh pemanggil saat ini" (misalnya, hanya membaca dompet milik Anda sendiri). Pada Script yang mengizinkan panggilan anonim, filter ini tidak dapat dipakai. Karena tidak ada pemanggil, ia diuraikan menjadi penulis, sehingga makna aslinya sebagai cakupan kepemilikan tidak lagi berlaku.
• Izin yang didelegasikan (perhatian bagi penulis): menggabungkan kedua batas di atas, menjalankan sebuah Script setara dengan bertindak dengan izin penulis yang didelegasikan kepadanya. Pemanggil hanya perlu Execute, dan Statement di dalam Script berjalan persis dalam cakupan yang diotorisasikan kepada penulis saat disimpan. Akibatnya, operasi resource yang tidak dapat dilakukan sendiri oleh pemanggil pun tetap bisa terjadi melalui Script. Karena izin yang diberikan kepada penulis itulah jangkauan efektif dari Script tersebut, tentukan dengan cermat operasi apa yang Anda masukkan ke dalam Script.

Daftar periksa ringkas

Sebelum menyimpan, periksa hal-hal berikut.

• Jika Anda mengaktifkan panggilan anonim (anonymousCallEnabled), tidak ada createdBy: ":self" pada where, dan Statement yang memverifikasi permintaan yang diterima (Signature, dan sejenisnya) diletakkan di paling depan.
• Jumlah panggilan eksternal (Http, EmailSend) dan total Statement berada dalam batas paket, SetVar 10 atau kurang, dan Cache 5 atau kurang.
• Jika memakai Cache, Anda menulis key sebagai literal dan tidak meletakkannya di dalam Loop atau ResourceForEach.
• Jika menelusuri kumpulan besar dengan ResourceForEach, Anda telah mendeklarasikan limit atau memastikan ukurannya dapat diselesaikan seluruhnya.
• Jika Anda memuat perulangan (Loop, ResourceForEach), Anda sudah memastikan bahwa perulangan itu masuk sebagai perkalian ke Anggaran waktu (tanpa panggilan eksternal, batasnya adalah anggaran dasar 30 detik).
• Nilai rahasia seperti kunci API eksternal atau kunci tanda tangan sudah dideklarasikan di secrets dan dibaca dengan { /secrets/<key> }. Tidak ada nilai rahasia yang ditulis apa adanya di Statement.
• Jika menyimpan dengan perubahan penuh (PUT), Anda mengirimkan secrets bersamanya.
• Pesan yang dipakai untuk verifikasi tanda tangan diambil dengan { /rawPayload }, bukan /payload.
• Jika ada Statement yang menangani anggota (ServiceUser), penulis memiliki SETTING_SERVICE_LOGIN, dan Anda tidak menyertakan Statement yang membuat atau menghapus resource tersebut.
• Operasi yang tidak dapat dibatalkan (panggilan eksternal) ditempatkan sebisa mungkin di bagian akhir.
• Jika mengirim file dengan Http, Anda hanya menulis satu field body permintaan (body, urlBody, multipartBody) dan sudah memastikan setiap file berada dalam batas unduhan per paket.
• Jika Anda mengkhawatirkan persaingan update/patch, gunakan version pada ResourceUpdate atau ResourcePatch.
• Untuk mengembalikan hasil, Anda menentukan Return.value.

Error

Berikut adalah kode yang muncul saat penyimpanan ditolak karena bentuk definisi melanggar batasan statis. Kode yang melanggar aturan ekspresi nilai ada di Error pada Ekspresi nilai, sedangkan kode yang muncul saat pemanggilan dan penghapusan ada di Error pada endpoint. Untuk kode yang berlaku umum pada semua resource, lihat Error umum.

Dokumen terkait

• Ekspresi nilai: aturan nilai dan kondisi.
• Katalog Statement: field dan hasil dari setiap Statement.
• Cookbook: kumpulan contoh yang lengkap.
• Resource dan endpoint Script: struktur resource Script dan endpoint HTTP seperti /execute.
• Ikhtisar Script: struktur tingkat atas dan waktu yang diberikan untuk satu eksekusi.