kit-policy

# kit-policy

إطار عمل للتفويض مرن وقابل للتكوين لـ Kit، مستوحى من [Action Policy](https://actionpolicy.evilmartians.io/) الخاص بـ Ruby.

---

[TOC]

---

## الملفات

| الملف | الوصف |
|------|-------------|
| [`.editorconfig`](https://gitlab.com/kit-lang/packages/kit-policy/-/blob/main/.editorconfig) | إعدادات تنسيق المحرر |
| [`.gitignore`](https://gitlab.com/kit-lang/packages/kit-policy/-/blob/main/.gitignore) | قواعد تجاهل Git لمخرجات البناء والتبعيات |
| [`.tool-versions`](https://gitlab.com/kit-lang/packages/kit-policy/-/blob/main/.tool-versions) | إصدارات أدوات asdf (Zig, Kit) |
| [`LICENSE`](https://gitlab.com/kit-lang/packages/kit-policy/-/blob/main/LICENSE) | ملف ترخيص MIT |
| [`README.md`](https://gitlab.com/kit-lang/packages/kit-policy/-/blob/main/README.md) | هذا الملف |
| [`examples/blog-policy.kit`](https://gitlab.com/kit-lang/packages/kit-policy/-/blob/main/examples/blog-policy.kit) | مثال لسياسة المدونة |
| [`kit.toml`](https://gitlab.com/kit-lang/packages/kit-policy/-/blob/main/kit.toml) | بيان الحزمة مع البيانات الوصفية والمهام وتكوين lint |
| [`src/core.kit`](https://gitlab.com/kit-lang/packages/kit-policy/-/blob/main/src/core.kit) | مساعدات التفويض الأساسية |
| [`src/error.kit`](https://gitlab.com/kit-lang/packages/kit-policy/-/blob/main/src/error.kit) | أخطاء التفويض، أنواع النتائج، وأسباب الفشل |
| [`src/main.kit`](https://gitlab.com/kit-lang/packages/kit-policy/-/blob/main/src/main.kit) | الوحدة الجذرية للحزمة |
| [`src/scope.kit`](https://gitlab.com/kit-lang/packages/kit-policy/-/blob/main/src/scope.kit) | مساعدات النطاق، المسند، والترقيم |
| [`tests/policy.test.kit`](https://gitlab.com/kit-lang/packages/kit-policy/-/blob/main/tests/policy.test.kit) | اختبارات سلوك السياسة الشاملة |
| [`tests/types.test.kit`](https://gitlab.com/kit-lang/packages/kit-policy/-/blob/main/tests/types.test.kit) | اختبارات أنواع السياسة والمساعدات |

## التبعيات

_لا تبعيات لحزمة Kit._

## التثبيت

```console
kit add gitlab.com/kit-lang/packages/kit-policy.git
```

## الاستخدام

```kit
import Kit.Policy.Core as PolicyCore
import Kit.Policy.Error as PolicyError
import Kit.Policy.Scope as PolicyScope

type Post = {id: Int, author-id: Int, published?: Bool, title: String}
type User = {id: Int, admin?: Bool}
type AuthContext = {user: User}

post-policy = fn(post, ctx, action) =>
  if ctx.user.admin? then
    PolicyCore.allow
  else
    match PolicyCore.resolve-alias action
      | :show -> PolicyCore.allow-if post.published?
      | :update -> PolicyCore.allow-if (ctx.user.id == post.author-id)
      | :destroy -> PolicyCore.allow-if (ctx.user.id == post.author-id)
      | _ -> PolicyCore.no-rule action

post-scope = fn(posts, ctx) =>
  if ctx.user.admin? then
    posts
  else
    posts |>> List.filter (fn(post) => post.published?)

main = fn =>
  user = {id: 1, admin?: false}
  ctx = {user: user}
  post = {id: 1, author-id: 1, published?: true, title: "Hello"}
  posts = [post]

  if PolicyCore.can-with? post-policy post ctx :update then
    println "Can update post"
  else
    println "Cannot update post"

  visible-posts = PolicyScope.scope-with post-scope posts ctx
  page = PolicyScope.paginate 1 10 visible-posts
  info = PolicyScope.pagination-info 1 10 visible-posts

  println "Visible posts: ${page}"
  println "Pages: ${info.pages}"

  err = PolicyError.not-authorized "Post" :update "not the author"
  println (PolicyError.message err)

main
```

## نظرة عامة على API

### Policy.Core

مساعدات أساسية لدوال السياسة التي ترجع `Result Bool PolicyError`.

```kit
PolicyCore.can-with? policy resource context action
PolicyCore.may-with? policy resource context action

PolicyCore.allow
PolicyCore.deny
PolicyCore.allow-if condition
PolicyCore.deny-if condition
PolicyCore.no-rule action
PolicyCore.allow-or-deny condition resource-name reason action
```

مساعدات التحقق الأولي ترجع `Option Bool`: `Some true` يسمح، `Some false` يمنع، و `None` يستمر إلى القاعدة الرئيسية.

```kit
PolicyCore.admin-bypass is-admin? ctx
PolicyCore.owner-check is-owner? resource ctx
PolicyCore.first-pre-check [check1, check2, check3]
```

مساعدات الإجراءات توفر مجموعات إجراءات شائعة وأسماء مستعارة.

```kit
PolicyCore.crud-actions
PolicyCore.read-actions
PolicyCore.write-actions

PolicyCore.read-action? action
PolicyCore.write-action? action

PolicyCore.resolve-alias :new     # :create
PolicyCore.resolve-alias :edit    # :update
PolicyCore.resolve-alias :delete  # :destroy
PolicyCore.resolve-alias :view    # :show
```

مساعدات تركيب السياسة تجمع عدة نتائج تفويض.

```kit
PolicyCore.all-allowed? [result1, result2, result3]
PolicyCore.any-allowed? [result1, result2, result3]
```

### Policy.Scope

مساعدات النطاق لتصفية المجموعات قبل إرجاع البيانات للمتصل.

```kit
PolicyScope.scope-with scope-fn items ctx
PolicyScope.filter-by predicate items

PolicyScope.is-owned-by? get-owner-id get-user-id item ctx
PolicyScope.is-published? get-published item
PolicyScope.is-in-state? get-state target-state item
PolicyScope.is-admin-or? check-admin fallback-check ctx item
```

التابعات المسندية مفيدة لبناء فحوصات نطاق قابلة لإعادة الاستخدام.

```kit
PolicyScope.both? pred1 pred2 item
PolicyScope.either? pred1 pred2 item
PolicyScope.not-matching? pred item
```

مساعدات الترقيم تستند إلى الفهرسة من 1.

```kit
page1 = PolicyScope.paginate 1 10 items
pages = PolicyScope.total-pages 10 items
info = PolicyScope.pagination-info 1 10 items
```

### Policy.Error

أنواع الأخطاء والنتائج لأعطال التفويض.

```kit
type PolicyError =
  | NotAuthorized {resource: String, action: Keyword, reason: String}
  | RuleNotFound {action: Keyword}
  | ContextMissing {field: String}
  | PolicyNotFound {resource-type: String}
  | CustomError String

type FailureReason = FailureReason {
  policy: String,
  action: Keyword,
  details: String
}

type AuthResult =
  | Allowed
  | Denied String
```

الدوال المساعدة مصدرة من الوحدة، لذلك عند استيرادها باسم `PolicyError` يتم استدعاؤها كدوال وحدة.

```kit
PolicyError.not-authorized resource action reason
PolicyError.rule-not-found action
PolicyError.context-missing field
PolicyError.policy-not-found resource-type
PolicyError.custom message

PolicyError.message err
PolicyError.kind err
PolicyError.is-not-authorized? err
PolicyError.is-rule-not-found? err

PolicyError.new policy action
PolicyError.with-details policy action details
PolicyError.policy reason
PolicyError.action reason
PolicyError.details reason
PolicyError.format reason

PolicyError.allowed
PolicyError.denied reason
PolicyError.is-allowed? result
PolicyError.is-denied? result
PolicyError.reason result
PolicyError.to-result resource-name action result
```

## ملاحظات التصميم

- السياسات هي دوال عادية، لذا يسهل اختبارها وتركيبها.
- التفويض صريح: المساعدات ترجع `Result Bool PolicyError` بدلاً من رمي الاستثناءات.
- النطاقات منفصلة عن فحوصات السياسة بحيث يمكن تصفية القوائم قبل العرض أو التسلسل.
- الإجراءات الشائعة تستخدم كلمات مفتاحية مثل `:index`, `:show`, `:create`, `:update`, و `:destroy`.
- الحزمة غير مرتبطة بإطار معين ويمكن استخدامها مع أي كود لتطبيقات Kit.

## التطوير

### تشغيل الأمثلة

تشغيل مثال سياسة المدونة باستخدام المفسر:

```console
kit run examples/blog-policy.kit
```

تجميع المثال إلى ثنائي أصلي:

```console
kit build examples/blog-policy.kit && ./blog-policy
```

### تشغيل الاختبارات

تشغيل مجموعة الاختبارات:

```console
kit test
```

تشغيل مجموعة الاختبارات مع تغطية:

```console
kit test --coverage
```

### تشغيل kit dev

تشغيل سير العمل التطويري القياسي (تنسيق، فحص، اختبار):

```console
kit dev
```

سيقوم هذا بما يلي:
1. تنسيق وفحص ملفات المصدر في `src/`
2. فحص أنواع الأمثلة في `examples/`
3. تشغيل الاختبارات في `tests/` مع تغطية

### التحقق من توافق المفسر/المترجم

تشغيل فحوصات التطابق للأمثلة:

```console
kit parity --failures-only
```

### توليد التوثيق

توليد توثيق API من تعليقات التوثيق:

```console
kit doc
```

**ملاحظة**: مصادر Kit التي تحتوي على تعليقات توثيق (`##`) ستولد مستندات HTML في `docs/*.html`.

### تنظيف مخرجات البناء

إزالة الملفات المولدة وذاكرة التخزين المؤقت ومخرجات البناء:

```console
kit task clean
```

**ملاحظة**: معرفة في [kit.toml](https://gitlab.com/kit-lang/packages/kit-policy/-/blob/main/kit.toml).

## التثبيت المحلي

لتثبيت هذه الحزمة محلياً للتطوير:

```console
kit install
```

هذا يقوم بتثبيت الحزمة في `~/.kit/packages/@kit/policy/`، مما يجعلها متاحة للاستيراد كـ `Kit.Policy` في مشاريع أخرى.

## الترخيص

هذه الحزمة مرخصة بموجب رخصة MIT - راجع [LICENSE](https://gitlab.com/kit-lang/packages/kit-policy/-/blob/main/LICENSE) للتفاصيل.