KRET LANGUAGE ACADEMY · DOKUMENTACJA ZE ŹRÓDEŁ

Wersjonowany kontrakt usługi

BASIC20 min

Postęp nauki 0 / 3

Zaloguj się na konto użytkownika, aby zachować postęp.

Czego się nauczysz

Prześledź źródła i wyjaśnij opisany kontrakt.
W ContractCompileSchema dopasuj nazwę metody do schematu wejścia i wyniku.

Wymagania wstępne

Ukończ Podstawy i wcześniejszy poziom tej ścieżki.

Wyjaśnienie krok po kroku

Plik .klink opisuje kontrakt. Lokalny protokół broker–plugin i RPC mają własne wersje. Zdefiniowanie usługi nie przyznaje prawa do komunikacji; poprawny schemat to dopiero informacja o strukturze wiadomości.

Praca z kodem źródłowym

Kontrakt usługi `.klink`: kompilacja i schemat

Kontrakt `klink "1.0"` z usługą, wersją SemVer, metodami (parametry, wynik, termin, uprawnienie) i typami KretS. `kret link compile` daje postać kanoniczną JSON i skrót SHA-256, `kret link schema` — JSON Schema żądań i wyników (pochodna kontraktu, nie drugie źródło prawdy). Kontrakt **nie daje prawa do komunikacji**.

Plik

1klink "1.0"
2
3// Wersjonowany kontrakt usługi notatek.
4service notes.api {
5    version "1.2.0"
6
7    method add {
8        description "Dodaje notatkę i zwraca wszystkie notatki."
9        param text String
10        returns "List<String>"
11        permission kretlink.publish
12        timeout 5s
13    }
14    method count {
15        description "Liczba notatek."
16        returns Int64
17    }
18    method find {
19        description "Pierwsza notatka z prefiksem albo null."
20        param prefix String
21        returns "String?"
22    }
23}
24

Czytanie kodu linia po linii

Objaśnienia struktury nie są walidacją semantyczną. Szczegółowy kontrakt opisują referencje i README przykładu.

klink "1.0"Odczytaj tę linię w kontekście otaczającego bloku i objaśnień autora poniżej.
Pusta linia oddziela fragmenty źródła.
// Wersjonowany kontrakt usługi notatek.Komentarz autora; nie jest wykonywany.
service notes.api {Odczytaj tę linię w kontekście otaczającego bloku i objaśnień autora poniżej.
version "1.2.0"Pole tożsamości lub wersji w otaczającym bloku; zachowaj jego kontekst.
Pusta linia oddziela fragmenty źródła.
method add {Odczytaj tę linię w kontekście otaczającego bloku i objaśnień autora poniżej.
description "Dodaje notatkę i zwraca wszystkie notatki."Odczytaj tę linię w kontekście otaczającego bloku i objaśnień autora poniżej.
param text StringOdczytaj tę linię w kontekście otaczającego bloku i objaśnień autora poniżej.
returns "List<String>"Odczytaj tę linię w kontekście otaczającego bloku i objaśnień autora poniżej.
permission kretlink.publishOdczytaj tę linię w kontekście otaczającego bloku i objaśnień autora poniżej.
timeout 5sOdczytaj tę linię w kontekście otaczającego bloku i objaśnień autora poniżej.
}Zamknięcie struktury otwartej we wcześniejszych liniach.
method count {Odczytaj tę linię w kontekście otaczającego bloku i objaśnień autora poniżej.
description "Liczba notatek."Odczytaj tę linię w kontekście otaczającego bloku i objaśnień autora poniżej.
returns Int64Odczytaj tę linię w kontekście otaczającego bloku i objaśnień autora poniżej.
}Zamknięcie struktury otwartej we wcześniejszych liniach.
method find {Odczytaj tę linię w kontekście otaczającego bloku i objaśnień autora poniżej.
description "Pierwsza notatka z prefiksem albo null."Odczytaj tę linię w kontekście otaczającego bloku i objaśnień autora poniżej.
param prefix StringOdczytaj tę linię w kontekście otaczającego bloku i objaśnień autora poniżej.
returns "String?"Odczytaj tę linię w kontekście otaczającego bloku i objaśnień autora poniżej.
}Zamknięcie struktury otwartej we wcześniejszych liniach.
}Zamknięcie struktury otwartej we wcześniejszych liniach.
Pusta linia oddziela fragmenty źródła.

Oczekiwany wynik: Kod 0 w obu krokach; schemat wymienia usługę `notes.api` i jej metody.

Typowy błąd: Rekord jako typ parametru — rekordy w kontraktach 1.0 są NOT_SUPPORTED. Dozwolone: `Bool Int64 Float64 String Bytes Unit List<T> Map<String,T> T?`.

Instrukcja, wersje i zapisane wyniki →

Materiały źródłowe do tego tematu

Przeczytaj powiązane rozdziały. Kod i kontrakty zachowano z importu; historia źródeł jest dostępna przy każdym rozdziale.

KretLink — wprowadzenie

Status 1.0: `FROZEN_SUPPORTED_SUBSET` — zamrożony dokładnie opisany zakres; reszta poza kontraktem 1.0. Gramatyka/wersja: klink-1.0. Status języka nie nadaje uprawnień KCS ani prawa do działania w Production.

Czym jest

KretLink to wersjonowane kontrakty usług (.klink) i dwa protokoły: łącze broker↔plugin kretlink-local/1 (stdin/stdout) oraz RPC kretlink-rpc/1 na potokach nazwanych (tożsamość procesu, wzajemny HMAC, terminy). Kontrakt można walidować, ale nie daje on prawa do komunikacji. Eksport usług pluginów, stream w Core i produkcyjne uprawnienia kretlink.* są zablokowane (A17, FB-06).

Dla początkujących

Kontrakt mówi, jakie metody ma usługa, jakie przyjmują parametry i co zwracają. SDK sprawdza kontrakt i generuje z niego JSON Schema. To jak umowa interfejsu — sama nie łączy programów.

Dla zaawansowanych programistów

Postać kanoniczna JSON + SHA-256 niezależny od kolejności metod. Dopuszczenie połączenia: tożsamość procesu z systemu (PID, ścieżka, opcjonalnie SHA-256) → wersja protokołu → wzajemny HMAC-SHA256 (usługa dowodzi pierwsza) → zgodność kontraktów. Każde wywołanie: metoda → uprawnienia → typy → limit równoległości → termin. Ramki ≤ 524 288 B (limit dokumentu KCS); identyfikator korelacji D-KCS-10; powtórzone/cofnięte identyfikatory wywołań zamykają połączenie. Strumienie z kredytem — EXPERIMENTAL (KCS-LNK-0121).

Jakie problemy rozwiązuje

Jawne, wersjonowane kontrakty komunikacji i bezpieczne lokalne IPC bez zaufania do samej możliwości połączenia z potokiem.

Kiedy używać

kontrakty komunikacyjne i wersjonowane API
kontrakty KretBridge (KretS ↔ C#)
JSON Schema dla narzędzi

Kiedy nie używać

eksport usług pluginów (zablokowany)
RPC między komputerami (NOT_SUPPORTED)
rekordy w kontraktach (NOT_SUPPORTED)
Linux/macOS (tożsamość procesu niedostępna — NOT_SUPPORTED)

Współpraca z innymi technologiami

KretBridge (kontrakt usługi C#), KretS (kompilator sprawdza wywołania), broker (łącze kretlink-local/1), Core (RPC health, ramUsage).

Obecny status

FROZEN_SUPPORTED_SUBSET — zamrożony dokładnie opisany zakres; reszta poza kontraktem 1.0.

Dalej: ARCHITECTURE.md · SYNTAX_REFERENCE.md · ../Tutorials/BASIC/TUTORIAL_PL.md

Otwórz cały rozdział ze źródłem →

KretLink — referencja składni

Status 1.0: `FROZEN_SUPPORTED_SUBSET` — zamrożony dokładnie opisany zakres; reszta poza kontraktem 1.0. Gramatyka/wersja: klink-1.0. Status języka nie nadaje uprawnień KCS ani prawa do działania w Production.

Opisane są wyłącznie konstrukcje potwierdzone implementacją SDK (i, gdzie zaznaczono, testami tej rundy).

`service / version`

Usługa i jej wersja SemVer.

Plik

1klink "1.0"
2service notes.api {
3    version "1.2.0"
4}

Czytanie kodu linia po linii

Objaśnienia struktury nie są walidacją semantyczną. Szczegółowy kontrakt opisują referencje i README przykładu.

klink "1.0"Odczytaj tę linię w kontekście otaczającego bloku i objaśnień autora poniżej.
service notes.api {Odczytaj tę linię w kontekście otaczającego bloku i objaśnień autora poniżej.
version "1.2.0"Pole tożsamości lub wersji w otaczającym bloku; zachowaj jego kontekst.
}Zamknięcie struktury otwartej we wcześniejszych liniach.

Cecha	Wartość
Parametry / typy	—
Wynik	—
Wymagania	—
Ograniczenia	zgodność: ta sama wersja główna
Możliwe błędy	KCS-LNK-*
Wprowadzono	1.0

`method`

Metoda z parametrami, wynikiem, uprawnieniem i terminem.

Plik

1method add {
2    description "…"
3    param text String
4    returns "List<String>"
5    permission kretlink.publish
6    timeout 5s
7}

Czytanie kodu linia po linii

Objaśnienia struktury nie są walidacją semantyczną. Szczegółowy kontrakt opisują referencje i README przykładu.

method add {Odczytaj tę linię w kontekście otaczającego bloku i objaśnień autora poniżej.
description "…"Odczytaj tę linię w kontekście otaczającego bloku i objaśnień autora poniżej.
param text StringOdczytaj tę linię w kontekście otaczającego bloku i objaśnień autora poniżej.
returns "List<String>"Odczytaj tę linię w kontekście otaczającego bloku i objaśnień autora poniżej.
permission kretlink.publishOdczytaj tę linię w kontekście otaczającego bloku i objaśnień autora poniżej.
timeout 5sOdczytaj tę linię w kontekście otaczającego bloku i objaśnień autora poniżej.
}Zamknięcie struktury otwartej we wcześniejszych liniach.

Cecha	Wartość
Parametry / typy	`param nazwa Typ`
Wynik	`returns`
Wymagania	`permission` → uprawnienie KCS sprawdzane przez brokera
Ograniczenia	teksty bez znaków sterujących/BiDi (`KCS-LNK-0116`)
Możliwe błędy	KCS-LNK-0116
Wprowadzono	1.0

`stream (EXPERIMENTAL)`

Strumień z kontrolą przepływu (kredyt).

Plik

1stream ticks {
2    param limit Int64
3    returns Int64
4}

Czytanie kodu linia po linii

Objaśnienia struktury nie są walidacją semantyczną. Szczegółowy kontrakt opisują referencje i README przykładu.

stream ticks {Odczytaj tę linię w kontekście otaczającego bloku i objaśnień autora poniżej.
param limit Int64Odczytaj tę linię w kontekście otaczającego bloku i objaśnień autora poniżej.
returns Int64Odczytaj tę linię w kontekście otaczającego bloku i objaśnień autora poniżej.
}Zamknięcie struktury otwartej we wcześniejszych liniach.

Cecha	Wartość
Parametry / typy	—
Wynik	typ elementu
Wymagania	—
Ograniczenia	poza Stable 1.0 (D-KCS-13); KretS 2.0 nie wywołuje strumieni
Możliwe błędy	KCS-LNK-0121 (ostrzeżenie / warning)
Wprowadzono	1.0 (experimental)

Otwórz cały rozdział ze źródłem →

KretLink — samouczek BASIC

Status 1.0: `FROZEN_SUPPORTED_SUBSET` — zamrożony dokładnie opisany zakres; reszta poza kontraktem 1.0. Gramatyka/wersja: klink-1.0. Status języka nie nadaje uprawnień KCS ani prawa do działania w Production.

Cel: pierwszy plik, podstawowa struktura, najprostszy działający przykład, najczęstszy błąd, sposób uruchomienia.

Narzędzia: kret = <SDK>\Compiler\kret.exe (SDK 1.0.0-rc.3+kret.local.3), kretui-host = <SDK>\UiHost\kretui-host.exe. {DATA}/{OUT} = nowe, puste katalogi.

1. Kontrakt usługi `.klink`: kompilacja i schemat (`KRETLINK-B01-ContractCompileSchema`)

Projekt: ../../Examples/BASIC_ContractCompileSchema/ · klasyfikacja VALIDATION_ONLY · Playground PUBLIC_STATIC

Kroki (katalog roboczy: katalog przykładu):

kret link compile Bridge/notes.klink -o {OUT}/notes.json
kret link schema Bridge/notes.klink — w wyniku: notes.api

Wynik tej rundy: PASS — zob. EXPECTED_OUTPUT.txt.

Otwórz cały rozdział ze źródłem →

Ćwiczenie i sprawdzenie wiedzy

W ContractCompileSchema dopasuj nazwę metody do schematu wejścia i wyniku.

Twoje wyjaśnienie lub rozwiązanie — prywatny szkic na tej stronieSzkic nie jest wysyłany na serwer i znika po opuszczeniu lekcji. Przed wyjściem możesz go skopiować.

Podpowiedzi

KretLink to wersjonowane kontrakty usług (`.klink`) i dwa protokoły: łącze broker↔plugin `kretlink-local/1` (stdin/stdout) oraz RPC `kretlink-rpc/1` na potokach nazwanych (tożsamość procesu, wzajemny HMAC, terminy). Kontrakt można walidować, ale **nie daje on prawa do komunikacji**. Eksport usług pluginów, `stream` w Core i produkcyjne uprawnienia `kretlink.*` są zablokowane (A17, FB-06).
Odczytaj ograniczenia i oczekiwane błędy z dostarczonego samouczka; check i run są oddzielnymi krokami.

Omówienie rozwiązania

Odpowiedź oprzyj na pokazanym kodzie i rozdziale źródłowym. Plik .klink opisuje kontrakt. Lokalny protokół broker–plugin i RPC mają własne wersje. Zdefiniowanie usługi nie przyznaje prawa do komunikacji; poprawny schemat to dopiero informacja o strukturze wiadomości.

Podsumowanie i następny krok

Zaloguj się na konto użytkownika, aby zapisywać postęp i zakładki. Konta obsługi mogą czytać bez zapisu postępu. Logowanie →

Czego się nauczysz

Wyjaśnienie krok po kroku

Praca z kodem źródłowym

Kontrakt usługi `.klink`: kompilacja i schemat

Materiały źródłowe do tego tematu

KretLink — wprowadzenie

Czym jest

Dla początkujących

Dla zaawansowanych programistów

Jakie problemy rozwiązuje

Kiedy używać

Kiedy nie używać

Współpraca z innymi technologiami

Obecny status

KretLink — referencja składni

service / version

method

stream (EXPERIMENTAL)

KretLink — samouczek BASIC

1. Kontrakt usługi .klink: kompilacja i schemat (KRETLINK-B01-ContractCompileSchema)

Ćwiczenie i sprawdzenie wiedzy

Podsumowanie i następny krok

`service / version`

`method`

`stream (EXPERIMENTAL)`

1. Kontrakt usługi `.klink`: kompilacja i schemat (`KRETLINK-B01-ContractCompileSchema`)