fusee-framework 1.7.0 → 1.9.0

package/framework/types/store.d.ts

@@ -1,8 +1,66 @@
-export function defineStore<T>(id: string, setup: () => T): () => T;
-export function resetStore(id: string): void;
-export function clearStores(): void;
-export function registerStorePlugin(plugin: (store: any, id: string) => void): void;
-
-declare global {
-    function defineStore<T>(id: string, setup: () => T): () => T;
-}
+export type MutationType = 'direct' | 'patch object' | 'patch function';
+
+export const MutationType: {
+    readonly DIRECT: 'direct';
+    readonly PATCH_OBJECT: 'patch object';
+    readonly PATCH_FUNCTION: 'patch function';
+};
+
+export interface StoreMutation {
+    type: MutationType;
+    storeId: string;
+    payload?: Record<string, any>;
+}
+
+export interface SubscribeOptions {
+    flush?: 'pre' | 'post' | 'sync';
+    detached?: boolean;
+}
+
+export type SubscribeCallback = (mutation: StoreMutation, state: any) => void;
+export type UnsubscribeFunction = () => void;
+
+export interface Store<T> {
+    readonly id: string;
+    readonly type: 'store';
+    patch(partial: Partial<{ [K in keyof T]: T[K] extends (...args: any[]) => any ? ReturnType<T[K]> : T[K] }> | ((state: T) => void)): void;
+    subscribe(callback: SubscribeCallback, options?: SubscribeOptions): UnsubscribeFunction;
+}
+
+export type StoreHook<T> = (() => T & Store<T>) & { $id: string };
+
+export function defineStore<T>(id: string, setup: () => T): StoreHook<T>;
+export function resetStore(id: string): void;
+export function clearStores(): void;
+export function registerStorePlugin(plugin: (store: any, id: string) => void): void;
+export function useNestedStore<T>(useStoreFn: StoreHook<T>): T & Store<T>;
+
+export type StoreToRefs<T> = {
+    [K in keyof T]: T[K] extends (...args: any[]) => infer R ? import('./signal').SignalAccessor<R> : never
+}
+
+export type StoreToState<T> = {
+    [K in keyof T]: T[K] extends (...args: any[]) => infer R
+        ? import('./signal').SignalAccessor<R> extends { readonly: true }
+            ? never
+            : import('./signal').SignalAccessor<R>
+        : never
+}
+
+export type StoreToGetters<T> = {
+    [K in keyof T]: T[K] extends (...args: any[]) => infer R
+        ? import('./signal').SignalAccessor<R> extends { readonly: true }
+            ? import('./signal').SignalAccessor<R>
+            : never
+        : never
+}
+
+export function storeToRefs<T>(store: T & Store<T>): StoreToRefs<T>;
+export function storeToState<T>(store: T & Store<T>): StoreToState<T>;
+export function storeToGetters<T>(store: T & Store<T>): StoreToGetters<T>;
+
+declare global {
+    function defineStore<T>(id: string, setup: () => T): import('./store').StoreHook<T>;
+    function useNestedStore<T>(useStoreFn: import('./store').StoreHook<T>): T & Store<T>;
+    type MutationType = import('./store').MutationType;
+}

package/ghid_go_fusee_integrat_go1_26.txt

@@ -0,0 +1,276 @@
+Ghid integrat: Construirea serverului Fusee în Go 1.26 — ghid tehnic detaliat și bune practici
+
+Scopul acestui fișier
+- Un ghid tehnic complet, în limba română, pentru construirea serverului Fusee în Go (versiunea 1.26). Integrează cele două ghiduri anterioare: un ghid general pentru server Fusee în Go și un ghid tehnic actualizat specific Go 1.26.
+- Public țintă: student CS care dezvoltă Fusee (framework JS cu reactivitate fină) și are nevoie de un backend scalabil în Go pentru orchestrare compilare, servire artefacte, build pipeline, caching, multi-tenant, observabilitate și securitate.
+
+Sumar rapid
+1. Motivație pentru Go
+2. Ce e nou în Go 1.26 și implicații practice
+3. Reguli explicite pentru editorul AI / echipă
+4. Setup și toolchain (Go 1.26)
+5. Arhitectură recomandată proiect
+6. Concurență în Go: modele, pattern-uri și scenarii Fusee
+7. Implementări concrete: worker pool, errgroup, rate limiting, backpressure
+8. HTTP server design și API pentru Fusee
+9. Job orchestration: sync vs async, cache, deduplicare, multi-tenant
+10. Securitate, izolare runner, sandboxing
+11. Observabilitate, tracing și profilare (incl. goroutine leak profile 1.26)
+12. Testing: unit, integration, golden, differential, leak tests
+13. CI/CD, Dockerfile, producție
+14. Performanță și optimizări practice
+15. Anti-patterns și greșeli comune
+16. Checklist de migrare JS → Go
+17. Plan de învățare și implementare 90+ zile
+18. Resurse și linkuri utile
+
+1) De ce Go pentru serverul Fusee
+- Simplitate, viteza de dezvoltare și ecosistem pentru servere networked.
+- Model de concurență ușor de folosit (goroutines + channels) ideal pentru orchestration.
+- Toolchain stabil, cross-compilation simplă, suport bun pentru containerizare și cloud native.
+- Go 1.26 aduce optimizări GC și instrumente utile (goroutine leak profile) care ajută la construirea unui server robust.
+
+2) Ce e nou în Go 1.26 (rezumat relevant)
+- Green Tea garbage collector activ implicit (reduce overhead GC pentru alocări mici și concu- intensive).
+- `errors.AsType[E error](err)` — verificări tip-sigure pentru erori.
+- `new(expr)` — permite `new` cu expresii (utile pentru pointere inițializate inline în DTO-uri).
+- Experimental: `simd/archsimd`, `runtime/secret`, `goroutineleak` profile.
+- `go fix` modernizat — automatizări pentru modernizarea codului.
+Referințe oficiale: https://go.dev/doc/go1.26 și https://go.dev/blog/go1.26
+
+3) Reguli explicite pentru editorul AI / echipă
+- Propagă `context.Context` în toate apelurile I/O, job-run și comunicare între componente.
+- Nu lansa goroutine fără mecanism de oprire: folosește `context`, `WaitGroup`, canale, `errgroup`.
+- Nu inventa API extern: folosește API-uri documentate; întreabă dacă nu e sigur.
+- Evită variabile globale mutabile; folosește injecție de dependență (constructori de tip NewXxx).
+- Error handling explicit: returnează erori, folosește `errors.Is`/`errors.AsType`.
+- Nu folosi panic pentru control-flow; folosește recover centralizat la boundary-uri HTTP.
+- Aplică backpressure — canale cu buffer limitat, rate-limiter (token bucket), cozi finite.
+- Testează tot: unit tests, integration tests, benchmark-uri și leak tests (goroutineleak profile).
+
+4) Setup & toolchain pentru Go 1.26
+- Instalează Go 1.26 de pe https://go.dev/dl/ (sau managerul preferat). Setează `GOPATH` doar dacă ai nevoie; folosește `go mod`.
+- Inițializează modul:
+  - `go mod init github.com/yourorg/fusee-server`
+  - Asigură `go 1.26` în `go.mod` (editează manual dacă `go mod init` a creat o versiune inferioară)
+- Instrumente recomandate:
+  - `gofmt` (format), `go vet`, `golangci-lint`, `staticcheck`
+  - `go test` + `-race` pentru detecție race conditions
+  - `pprof` (profilare CPU/memorie) și `GOEXPERIMENT=goroutineleakprofile` pentru leak detection în CI/dev
+  - `minio` pentru test local S3, `redis` pentru cache/metadate
+  - `docker` / `kind` / `testcontainers` pentru e2e
+
+5) Structura recomandată proiect
+- cmd/fusee-server/main.go
+- internal/server (HTTP server, middleware)
+- internal/api (handlers, DTO, validation)
+- internal/compile (orchestrare job-uri, queue)
+- internal/worker (worker pool, runners)
+- pkg/storage (S3 adapter), pkg/cache (in-memory + Redis)
+- pkg/observability (metrics/tracing wrappers)
+- test/ (fixtures, golden)
+
+6) Concurența în Go — concepte și pattern-uri esențiale
+- Goroutine: `go fn()` — unitate ușoară de execuție. Nu sunt gratuite.
+- Channel: comunicare sincronă/asincronă între goroutine. Folosește canale buffered pentru backpressure.
+- select: multiplexare pe canale + context.Done() pentru cancel.
+- sync.WaitGroup: sincronizare pentru grupuri de goroutine.
+- sync.Mutex / RWMutex / atomic: folosirea cu atenție când state partajat.
+- errgroup: colectare erori din mai multe goroutine, propagare cancel.
+
+Pattern-uri utile:
+- Worker pool — pentru job-uri compilare.
+- Fan-out/fan-in — paralelizare taskuri independente.
+- Owner-per-shard — pentru a evita lock contention.
+- Circuit breaker + retry with backoff — pentru dependențe instabile.
+
+7) Exemple concrete (cod schematic) — worker pool și orchestration
+- Exemplar worker pool (robust, cu ctx, timeout și wg):
+
+```
+package worker
+
+import (
+    "context"
+    "sync"
+    "time"
+)
+
+type Job struct {
+    ID    string
+    Input []byte
+}
+
+type Result struct {
+    JobID string
+    Err   error
+}
+
+func StartWorkers(ctx context.Context, n int, jobs <-chan Job, results chan<- Result, wg *sync.WaitGroup) {
+    for i := 0; i < n; i++ {
+        wg.Add(1)
+        go func(workerID int) {
+            defer wg.Done()
+            for {
+                select {
+                case <-ctx.Done():
+                    return
+                case job, ok := <-jobs:
+                    if !ok { return }
+                    jobCtx, cancel := context.WithTimeout(ctx, 5*time.Minute)
+                    resErr := processJob(jobCtx, job)
+                    cancel()
+                    select {
+                    case results <- Result{JobID: job.ID, Err: resErr}:
+                    case <-ctx.Done():
+                        return
+                    }
+                }
+            }
+        }(i)
+    }
+}
+
+// processJob este funcția de lucru care trebuie să respecte contextul
+func processJob(ctx context.Context, j Job) error {
+    // implementare: build, write artifact to S3, update DB
+    return nil
+}
+```
+
+Observații:
+- Folosește `jobCtx` cu timeout specific pentru fiecare job.
+- Rezultatele pot fi stocate în DB sau trimise pe canal `results`.
+- `wg` este așteptat la shutdown pentru a evita goroutine leaks.
+
+8) HTTP server design & endpoint-uri recomandate
+- Endpoints cheie:
+  - POST /compile → acceptă request, validează, calculează hash input, verifică cache, enquează job asincron și returnează 202 + job_id (sau 200 + artifact dacă e cache hit)
+  - GET /compile/{id}/status → starea jobului
+  - GET /assets/{hash} → serve artifact (WASM/JS) cu headers CDN
+  - /metrics, /debug/pprof/*, /healthz, /readyz
+- Principii handler:
+  - Handlers mici: parse, validate, convert DTO, call service layer, write response
+  - Middleware pentru logging, tracing, recover (panic->500), rate-limit
+
+Exemplu handler schematic:
+
+```
+func (s *Server) compileHandler(w http.ResponseWriter, r *http.Request) {
+    ctx := r.Context()
+    var req CompileRequest
+    if err := json.NewDecoder(r.Body).Decode(&req); err != nil {
+        http.Error(w, "invalid JSON", http.StatusBadRequest)
+        return
+    }
+    if !s.limiter.Allow() {
+        http.Error(w, "rate limit", http.StatusTooManyRequests)
+        return
+    }
+    key := s.computeHash(req)
+    if art, ok := s.cache.Get(key); ok {
+        w.Header().Set("Content-Type", "application/wasm")
+        w.Write(art)
+        return
+    }
+    jobID, err := s.queue.Enqueue(ctx, req)
+    if err != nil {
+        http.Error(w, "internal", http.StatusInternalServerError)
+        return
+    }
+    w.WriteHeader(http.StatusAccepted)
+    json.NewEncoder(w).Encode(map[string]string{"job_id": jobID})
+}
+```
+
+9) Job orchestration: sync vs async, cache & deduplicare
+- Dev: permită compilare sync cu timeout curat (feedback rapid).
+- Prod: async cu job queue și worker pool; returnează 202. Stochează artefactele în object store.
+- Deduplicare: folosește hash funcțional (deterministic) din input (source + flags) pentru a evita recompilări.
+- Stochează metadate în Redis/DB (status, retrier count, last error, artifact URL).
+
+10) Securitate și izolare
+- Rulează build-runner în containere sandbox (firecracker, gVisor, k8s Jobs) sau procese izolate.
+- Limitările resurselor: cgroup limits, ulimit pentru procese runner.
+- Validare input: never trust client input — sanitize, size limits, timeouts.
+- TLS & auth pentru API, rate-limit per tenant.
+
+11) Observabilitate, tracing și profilare
+- Logging: zap/zerolog (structured logs). Include trace_id, job_id, tenant_id în log fields.
+- Metrics: Prometheus client — counters, histograms (compile_duration_seconds), gauges (job_queue_length).
+- Tracing: OpenTelemetry — trace request flow: HTTP -> queue -> worker -> storage.
+- Profilare: pprof endpoints. Go 1.26 pprof UI default la flamegraph. Activează `goroutineleakprofile` în test/CI pentru leak detection.
+
+12) Testare recomandată
+- Unit tests (table-driven) pentru serviciile pure.
+- Mocks pentru dependințe I/O (storage, redis) cu `github.com/golang/mock` sau `testify/mock`.
+- Integration tests cu MinIO/Redis în container (testcontainers).
+- Golden tests pentru output codgen (compare generated JS/WASM bytes).
+- Differential tests: compară comportamentul JS-based compiler cu runner (Rust/WASM) dacă există.
+- Leak tests: rulează workload mic + colectează goroutineleak profile și asigură că nu apar goroutine leaked.
+
+13) CI/CD și Docker
+- Docker multistage build; folosește `CGO_ENABLED=0` pentru binare statice (dacă nu folosești cgo).
+- GitHub Actions / GitLab CI: lint -> unit tests -> build -> container -> smoke tests (integration), optional: run goroutine leak profile in CI smoke stage.
+- Exemple Dockerfile (multistage):
+
+```
+FROM golang:1.26 AS builder
+WORKDIR /src
+COPY go.mod go.sum ./
+RUN go mod download
+COPY . .
+RUN CGO_ENABLED=0 GOOS=linux go build -trimpath -o /app/cmd/fusee-server ./cmd/fusee-server
+
+FROM gcr.io/distroless/static-debian11
+COPY --from=builder /app/cmd/fusee-server /usr/local/bin/fusee-server
+EXPOSE 8080
+ENTRYPOINT ["/usr/local/bin/fusee-server"]
+```
+
+14) Performanță & optimizări
+- Măsoară cu pprof înainte de optimizare.
+- Evită alocările repetate: folosește `sync.Pool` pentru buffers mari.
+- Sharding pentru a reduce lock contention.
+- Folosește canale pentru coordonare când se potrivește, dar evită blocking pe canale necontrolate.
+- Dacă e nevoie de operații vectorizate, poți explora `simd/archsimd` (experimental) sau implementări native în Rust pentru codgen.
+
+15) Anti-patterns de evitat
+- Goroutine leaks (pornite fără mecanism de oprire).
+- Folosirea `panic` pentru flow control.
+- Variabile globale mutabile pentru state aplicație.
+- Blocking pe canale nebuffered în contexte fără timeout.
+- Ignorarea contextului în apeluri externe.
+
+16) Checklist migrare JS -> Go (server)
+- Definește API contract (OpenAPI)
+- Generare DTO în Go
+- Implementare handlers pure și service layer
+- Job queue + worker pool + cache/dedup
+- Storage artifacts (S3) + CDN headers
+- Observability (metrics, tracing) și health endpoints
+- Security review + sandboxing runner
+- Tests: unit/integration/golden/leak
+
+17) Plan 90 zile (orientativ)
+- Săptămâna 1-2: setup proiect, basic HTTP + middleware, DTO
+- Săptămâna 3-4: implementare job queue simplu, worker pool, sync compile dev mode
+- Săptămâna 5-6: integrate storage (MinIO), cache (Redis), dedup
+- Săptămâna 7-8: add rate limiter, multi-tenant basics, health & metrics
+- Săptămâna 9-10: tracing OTel, pprof, goroutine leak tests în CI
+- Săptămâna 11-12: CI/CD, Docker image, smoke e2e, performance tuning
+
+18) Resurse și linkuri utile
+- Go 1.26 Release Notes: https://go.dev/doc/go1.26
+- Go blog: https://go.dev/blog/go1.26
+- Effective Go: https://go.dev/doc/effective_go
+- golang.org/x/sync/errgroup: https://pkg.go.dev/golang.org/x/sync/errgroup
+- golang.org/x/time/rate: https://pkg.go.dev/golang.org/x/time/rate
+- Prometheus client: https://github.com/prometheus/client_golang
+- OpenTelemetry Go: https://opentelemetry.io/docs/instrumentation/go/
+
+Concluzie
+- Construirea serverului Fusee în Go 1.26 aduce beneficii de performanță, scalabilitate și o experiență solidă de dezvoltare. Folosește `context` pe scară largă, gestionează cu grijă goroutine-urile, instrumentează observabilitatea și asigură izolare pentru runner.
+- Go 1.26 oferă instrumente adiționale (goroutine leak profile, `errors.AsType`, Green Tea GC) care, folosite corect, îți vor ușura munca și îmbunătăți fiabilitatea.
+
+Dacă dorești, pot salva acest fișier ca `ghid_go_fusee_integrat_go1_26.txt` și ți-l pot pune la dispoziție pentru descărcare. De asemenea pot genera o versiune v2 care include un repo template complet (fișiere `main.go`, `server` package, worker example), workflow GitHub Actions și setări `golangci-lint`.