Data

Tools

Indexes

Applications

Experiments

Awesome

An open API service indexing awesome lists of open source software.

https://github.com/micro-func/docs

docs.microfunc.com
https://github.com/micro-func/docs

Last synced: about 1 year ago
JSON representation

docs.microfunc.com

Awesome Lists containing this project

README 

          
# Dokumentacja microfunc - gRPC Service Framework



## Spis treści

1. [Wprowadzenie](#wprowadzenie)

2. [Instalacja](#instalacja)

3. [Architektura systemu](#architektura-systemu)

4. [Plik konfiguracyjny microfunc.yaml](#plik-konfiguracyjny)

5. [Zarządzanie zadaniami](#zarządzanie-zadaniami)

6. [Komunikacja zewnętrzna](#komunikacja-zewnętrzna)

7. [Integracja z LLM](#integracja-z-llm)

8. [Zarządzanie usługami](#zarządzanie-usługami)

9. [Środowiska uruchomieniowe](#środowiska-uruchomieniowe)

10. [Integracja z CI/CD](#integracja-z-cicd)

11. [Przykłady użycia](#przykłady-użycia)

12. [Lista plików frameworka](#lista-plików-frameworka)

13. [Rozwiązywanie problemów](#rozwiązywanie-problemów)



## Wprowadzenie



gRPC Service Framework to kompleksowe narzędzie do zarządzania mikrousługami opartymi na protokole gRPC. Framework umożliwia:



- Definiowanie usług w jednym pliku konfiguracyjnym YAML

- Pobieranie plików źródłowych z różnych lokalizacji (lokalnych, Git, generowanych przez LLM)

- Automatyczne generowanie kodu usług gRPC

- Zarządzanie zadaniami manualnymi i automatycznymi

- Komunikację z zewnętrznymi systemami przez webhooks i API

- Obsługę zabezpieczeń z wykorzystaniem TLS

- Integrację z systemami CI/CD

- funkcje zarządzania zadaniami i zewnętrznej komunikacji, które uzupełniają istniejącą integrację z modelami językowymi (LLM)



## Instalacja



### Wymagania wstępne



- Python 3.8+

- Git

- OpenSSL (opcjonalnie dla generowania certyfikatów)

- Dostęp do API modelu językowego (dla funkcji LLM)



### Instalacja z repozytorium



```bash

git clone https://github.com/org/grpc-service-framework.git

cd grpc-service-framework

pip install -r requirements.txt

python setup.py install

```



### Szybki start



```bash

# Inicjalizacja nowego projektu

microfunc.py init moj-projekt

cd moj-projekt



# Generowanie plików za pomocą LLM

export OPENAI_API_KEY="twój-klucz-api"

microfunc.py llm-generate



# Budowanie usług

microfunc.py build



# Uruchamianie usług

microfunc.py up

```



## Architektura systemu



gRPC Service Framework składa się z kilku kluczowych komponentów:



1. **Konfigurator projektu** - obsługuje plik `microfunc.yaml` i zarządza wszystkimi aspektami projektu

2. **Generator usług gRPC** - tworzy kod serwerów, klientów i definicji protobuf na podstawie funkcji źródłowych

3. **Integracja z LLM** - umożliwia generowanie kodu i innych zasobów przy użyciu modeli językowych

4. **Menedżer zadań** - zarządza zadaniami manualnymi i automatycznymi

5. **Menedżer komunikacji** - obsługuje webhooks i integracje z zewnętrznymi API

6. **Runner usług** - uruchamia i monitoruje usługi gRPC



```

                  +-------------------+

                  |   microfunc.yaml  |

                  +-------------------+

                           |

                           v

                  +-------------------+

                  |  Konfigurator     |

                  |     Projektu      |

                  +-------------------+

                           |

          +----------------+----------------+

          |                |                |

+-----------------+ +---------------+ +---------------+

|  Generator      | |  Menedżer     | |  Menedżer     |

|  usług gRPC     | |  Zadań        | |  Komunikacji  |

+-----------------+ +---------------+ +---------------+

          |                |                |

          |                v                |

          |        +---------------+        |

          +------->|  Integracja   |<-------+

                   |  z LLM        |

                   +---------------+

                           |

                           v

                  +-------------------+

                  |     Runner        |

                  |     Usług         |

                  +-------------------+

```



## Plik konfiguracyjny



Wszystkie aspekty projektu są definiowane w pliku `microfunc.yaml`. Plik ten ma następującą strukturę:



```yaml

version: '1.2'



sources:

  local: { ... }  # Pliki lokalne

  git: { ... }    # Pliki z repozytoriów Git

  llm: { ... }    # Pliki generowane przez LLM



certificates: { ... }  # Konfiguracja certyfikatów TLS



tasks:               # sekcja do zarządzania zadaniami

  manual: [ ... ]    # Zadania do wykonania przez człowieka

  automated: [ ... ] # Zadania automatyczne



communication:       # sekcja do komunikacji zewnętrznej

  webhooks: [ ... ]  # Konfiguracja webhooków

  apis: [ ... ]      # Konfiguracja integracji z API



services: { ... }    # Definicje usług gRPC



global: { ... }      # Ustawienia globalne

```



### Sekcja `sources`



Definiuje źródła plików dla projektu:



```yaml

sources:

  # Pliki lokalne

  local:

    functions:

      path: "./functions"

      files:

        - "printer_service.py"

  

  # Pliki z repozytoriów Git

  git:

    common_lib:

      url: "https://github.com/org/common-grpc-lib.git"

      branch: "main"

      path: "src/functions"

      files:

        - "auth.py"

  

  # Pliki generowane przez LLM

  llm:

    provider: "openai"

    model: "gpt-4"

    api_key_env: "OPENAI_API_KEY"

    

    generated_functions:

      path: "./llm_generated/functions"

      prompts:

        data_validator:

          output_file: "data_validator.py"

          prompt: "Stwórz funkcję walidacji danych..."

          parameters:

            temperature: 0.2

```



### Sekcja `tasks` (nowa)



Definiuje zadania do wykonania w ramach projektu:



```yaml

tasks:

  # Zadania manualne do wykonania przez człowieka

  manual:

    - id: "configure-printers"

      title: "Konfiguracja drukarek fizycznych"

      description: "Skonfiguruj drukarki termiczne w systemie operacyjnym."

      assignee: "admin@example.com"

      due_date: "2025-03-15"

      status: "pending"  # pending, in_progress, completed, blocked

      priority: "high"   # low, medium, high, critical

      tags: ["hardware", "configuration"]

      

  # Zadania automatyczne wykonywane przez system

  automated:

    - id: "generate-test-data"

      title: "Generowanie danych testowych"

      description: "Wygeneruj zestaw testowych etykiet."

      executor: "data-generator-bot"

      schedule: "0 0 * * *"  # Codziennie o północy (format cron)

      status: "pending"

      priority: "medium"

      tags: ["testing", "data"]

      script: "./scripts/generate_test_data.py"

      parameters:

        count: 100

        types: ["product", "shipping", "info"]

```



### Sekcja `communication` (nowa)



Definiuje integracje z zewnętrznymi systemami:



```yaml

communication:

  # Konfiguracja webhooków do powiadamiania o zdarzeniach

  webhooks:

    - id: "slack-notifications"

      url: "https://hooks.slack.com/services/YOUR_WEBHOOK_URL"

      events: ["service.start", "service.stop", "task.completed", "error"]

      format: "json"

      headers:

        Content-Type: "application/json"

        Authorization: "Bearer ${SLACK_API_TOKEN}"

  

  # Konfiguracja API do komunikacji z innymi systemami

  apis:

    - id: "inventory-system"

      type: "rest"

      base_url: "https://inventory.example.com/api/v1"

      auth_type: "oauth2"

      auth_config:

        client_id: "${INVENTORY_CLIENT_ID}"

        client_secret: "${INVENTORY_CLIENT_SECRET}"

        token_url: "https://inventory.example.com/oauth/token"

      endpoints:

        - path: "/products"

          method: "GET"

          description: "Pobieranie listy produktów"

```



## Zarządzanie zadaniami



Nowy moduł zarządzania zadaniami umożliwia śledzenie i zarządzanie pracą w projekcie.



### Typy zadań



- **Zadania manualne** - muszą być wykonane przez człowieka

- **Zadania automatyczne** - mogą być wykonane automatycznie przez system



### Komendy CLI do zarządzania zadaniami



```bash

# Wyświetlanie listy wszystkich zadań

microfunc.py tasks list



# Wyświetlanie listy zadań o określonym statusie

microfunc.py tasks list --status pending



# Wyświetlanie szczegółów zadania

microfunc.py tasks show configure-printers



# Aktualizacja statusu zadania

microfunc.py tasks update configure-printers in_progress \

  --comment "Rozpoczęto konfigurację drukarek"



# Ręczne uruchomienie zadania automatycznego

microfunc.py tasks execute generate-test-data

```



### Automatyczne wykonywanie zadań



Zadania automatyczne mogą być uruchamiane:

- Według harmonogramu (format cron)

- Na podstawie wyzwalaczy (np. `on_deploy`, `on_commit`)

- Ręcznie przez użytkownika



Każde zadanie automatyczne ma skojarzony skrypt, który jest wykonywany przy uruchomieniu zadania.



## Komunikacja zewnętrzna



Nowy moduł komunikacji umożliwia integrację z zewnętrznymi systemami.



### Webhooks



Webhooks służą do powiadamiania zewnętrznych systemów o zdarzeniach:

- Uruchomienie/zatrzymanie usługi

- Zmiana statusu zadania

- Błędy w systemie



```bash

# Ręczne wywołanie webhooka

microfunc.py communicate webhook error \

  --data-file ./error_details.json

```



### Integracje API



Komponenty systemu mogą komunikować się z zewnętrznymi API:

- REST API

- gRPC API



```bash

# Wywołanie metody API

microfunc.py communicate api inventory-system /products \

  --params-file ./api_params.json

```



## Integracja z LLM



Framework umożliwia generowanie kodu i innych zasobów przy użyciu modeli językowych.



### Konfiguracja dostawcy LLM



```yaml

llm:

  provider: "openai"  # openai, anthropic, custom

  model: "gpt-4"      # model do wykorzystania

  api_key_env: "OPENAI_API_KEY"  # zmienna środowiskowa z kluczem

```



### Generowanie zasobów



```bash

# Generowanie wszystkich zasobów zdefiniowanych w konfiguracji

microfunc.py llm-generate



# Wymuszenie regeneracji, ignorując cache

microfunc.py llm-generate --force

```



### Typy generowanych zasobów



- **Funkcje** (`generated_functions`) - implementacje funkcji w Pythonie

- **Konfiguracje** (`generated_configs`) - pliki konfiguracyjne, np. reguły walidacji

- **Proto definicje** (`generated_protos`) - schemat API w formacie Protocol Buffers



## Zarządzanie usługami



Pełny cykl życia usług gRPC:



```bash

# Synchronizacja plików z różnych źródeł

microfunc.py sync



# Budowanie usług

microfunc.py build



# Uruchamianie usług

microfunc.py up



# Sprawdzanie statusu usług

microfunc.py status



# Zatrzymywanie usług

microfunc.py down

```



## Środowiska uruchomieniowe



Framework umożliwia definiowanie różnych konfiguracji dla środowisk:



```

environments/

├── development/

│   └── microfunc.yaml

├── staging/

│   └── microfunc.yaml

└── production/

    └── microfunc.yaml

```



Użycie konfiguracji dla konkretnego środowiska:



```bash

# Budowanie dla środowiska produkcyjnego

microfunc.py build --config environments/production/microfunc.yaml

```



## Integracja z CI/CD



Framework można łatwo zintegrować z GitLab CI i GitHub Actions.



### GitLab CI



```yaml

# .gitlab-ci.yml

stages:

  - generate

  - build

  - deploy

  - notify



generate-code:

  stage: generate

  script:

    - export OPENAI_API_KEY=$OPENAI_API_KEY

    - microfunc.py llm-generate

  artifacts:

    paths:

      - llm_generated/



build-services:

  stage: build

  script:

    - microfunc.py build

  artifacts:

    paths:

      - generated/



deploy-services:

  stage: deploy

  script:

    - microfunc.py up

  when: manual



notify-deployment:

  stage: notify

  script:

    - microfunc.py communicate webhook service.start --data-file ./deployment-info.json

```



### GitHub Actions



```yaml

# .github/workflows/build-deploy.yml

name: Build and Deploy



on:

  push:

    branches: [ main ]



jobs:

  generate:

    runs-on: ubuntu-latest

    steps:

      - uses: actions/checkout@v2

      - name: Generate code with LLM

        run: |

          export OPENAI_API_KEY=${{ secrets.OPENAI_API_KEY }}

          microfunc.py llm-generate

  

  build:

    needs: generate

    runs-on: ubuntu-latest

    steps:

      - name: Build services

        run: microfunc.py build

  

  deploy:

    needs: build

    runs-on: ubuntu-latest

    steps:

      - name: Deploy services

        run: microfunc.py up

      

      - name: Notify deployment

        run: microfunc.py communicate webhook service.start

```



## Przykłady użycia



### Projekt drukarki etykiet



```yaml

# microfunc.yaml

services:

  printer-service:

    function: 

      source: "local.functions"

      name: "printer_service.py"

    

  data-validator-service:

    function:

      source: "llm.generated_functions"

      name: "data_validator.py"

```



### Dodanie zadania manualnego



```bash

# Ręczne dodanie zadania

cat > task.json << EOF

{

  "id": "update-drivers",

  "title": "Aktualizacja sterowników drukarek",

  "description": "Zaktualizuj sterowniki do najnowszej wersji",

  "assignee": "admin@example.com",

  "status": "pending",

  "priority": "medium"

}

EOF



microfunc.py tasks add --file task.json

```



### Wywołanie webhooka



```bash

# Powiadomienie o błędzie

cat > error.json << EOF

{

  "error_type": "hardware",

  "message": "Utracono połączenie z drukarką",

  "device": "lp0"

}

EOF



microfunc.py communicate webhook error --data-file error.json

```



## Lista plików frameworka



Poniżej znajduje się lista kluczowych plików wchodzących w skład frameworka:



### Główne skrypty



- `microfunc.py` - Główne narzędzie CLI

- `grpc_generator.py` - Generator kodu gRPC



### Moduły integracyjne



- `llm_integration.py` - Integracja z modelami językowymi

- `task_manager.py` - Zarządzanie zadaniami

- `communication_manager.py` - Komunikacja zewnętrzna



### Pliki konfiguracyjne



- `microfunc.yaml` - Główny plik konfiguracyjny projektu

- `requirements.txt` - Zależności Pythona



### Pliki generowane



- `generated/` - Katalog z wygenerowanymi usługami

  - `[nazwa-usługi]/` - Katalog usługi

    - `proto/` - Definicje Protocol Buffers

    - `server/` - Kod serwera gRPC

    - `client/` - Kod klienta gRPC

    - `function/` - Kopia funkcji źródłowej

    - `service.json` - Konfiguracja usługi



- `llm_generated/` - Katalog z plikami wygenerowanymi przez LLM

  - `functions/` - Wygenerowane funkcje

  - `proto/` - Wygenerowane definicje Protocol Buffers

  - `config/` - Wygenerowane pliki konfiguracyjne



- `.registry/` - Lokalny rejestr funkcji

- `.llm_cache/` - Cache wyników LLM

- `tasks.db` - Baza danych SQLite z zadaniami



## Rozwiązywanie problemów



### Najczęstsze problemy



#### 1. Błędy z API LLM



```

Błąd: Nie znaleziono klucza API w zmiennej środowiskowej OPENAI_API_KEY

```



**Rozwiązanie**: Ustaw zmienną środowiskową `OPENAI_API_KEY` z właściwym kluczem API.



#### 2. Problemy z generowaniem kodu Proto



```

Błąd: Nie można skompilować pliku proto

```



**Rozwiązanie**: Zainstaluj `grpcio-tools` i sprawdź poprawność wygenerowanego pliku proto.



#### 3. Błędy podczas uruchamiania zadań automatycznych



```

Błąd: Nie znaleziono skryptu ./scripts/generate_test_data.py

```



**Rozwiązanie**: Upewnij się, że ścieżka do skryptu jest poprawna i ma uprawnienia do wykonywania.



### Logi diagnostyczne



Wszystkie logi są zapisywane w katalogu `logs/`:



```bash

# Wyświetlenie logów głównego procesu

cat logs/app.log



# Wyświetlenie logów konkretnej usługi

cat logs/printer-service/service.log

```



### Tryb debugowania



Aby uruchomić framework w trybie debugowania, ustaw zmienną środowiskową:



```bash

export GRPC_DEBUG=true

microfunc.py build

```