@ir-kit/kit 0.0.1 → 1.0.0

package/runtime/asyncapi/dispatch/dispatch.gen.ts

@@ -0,0 +1,188 @@
+// AUTO-GENERATED by @ir-kit/kit/sdk/asyncapi — do not hand-edit.
+
+import type { ConsumeMessage } from "amqplib";
+
+export type Handler<T> = (msg: T, raw: ConsumeMessage) => Promise<void> | void;
+
+export interface EventMeta {
+  type: string;
+  exchange: string;
+  routingKey: string;
+}
+
+/**
+ * Decodes a raw message body into the typed shape. Default is
+ * JSON.parse + utf8. Override to plug in a validator (zod/typia/ajv) —
+ * runtime is otherwise unverified and the cast is taken on trust.
+ */
+export type ParseFn = (buf: Buffer) => unknown;
+
+const defaultParse: ParseFn = (buf) => JSON.parse(buf.toString("utf8"));
+
+export interface RegistryOptions {
+  parse?: ParseFn;
+}
+
+export class Registry<
+  // biome-ignore lint/suspicious/noExplicitAny: caller's spec defines its shape
+  EM extends Record<string, any>,
+  Registered extends keyof EM = never,
+> {
+  private handlers = new Map<keyof EM, Handler<unknown>>();
+  private metaByType = new Map<keyof EM, EventMeta>();
+  private parse: ParseFn;
+
+  constructor(
+    events: Readonly<Record<string, EventMeta>>,
+    opts: RegistryOptions = {},
+  ) {
+    for (const meta of Object.values(events)) {
+      this.metaByType.set(meta.type as keyof EM, meta);
+    }
+    this.parse = opts.parse ?? defaultParse;
+  }
+
+  on<K extends keyof EM>(
+    type: K,
+    handler: Handler<EM[K]>,
+  ): Registry<EM, Registered | K> {
+    if (this.handlers.has(type)) {
+      console.warn(
+        `Registry.on: handler for "${String(type)}" was already registered, overwriting`,
+      );
+    }
+    this.handlers.set(type, handler as Handler<unknown>);
+    return this as Registry<EM, Registered | K>;
+  }
+
+  dispatch = (raw: ConsumeMessage | null): void => {
+    if (!raw) return;
+
+    let msg: EM[keyof EM];
+    try {
+      msg = this.parse(raw.content) as EM[keyof EM];
+    } catch (err) {
+      console.error("Registry.dispatch: failed to parse message body", err);
+      return;
+    }
+
+    const incoming = raw.fields.routingKey;
+
+    // Fast path: producer publishes with the concrete event type as the
+    // routing key, so most messages match an exact key in `handlers`.
+    const direct = this.handlers.get(incoming as keyof EM);
+    if (direct) {
+      this.runHandler(direct, msg, raw, incoming);
+      return;
+    }
+
+    // Slow path: incoming key didn't match a registered type literally,
+    // so walk patterns for a wildcard match (`*`, `#`).
+    for (const [type, handler] of this.handlers) {
+      const meta = this.metaByType.get(type);
+      if (!meta) continue;
+      if (matchRoutingKey(meta.routingKey, incoming)) {
+        this.runHandler(handler, msg, raw, String(type));
+        return;
+      }
+    }
+  };
+
+  private runHandler(
+    handler: Handler<unknown>,
+    msg: unknown,
+    raw: ConsumeMessage,
+    label: string,
+  ): void {
+    try {
+      const result = handler(msg, raw);
+      if (result instanceof Promise) {
+        result.catch((err: unknown) => {
+          console.error(`Registry.dispatch: handler for "${label}" threw`, err);
+        });
+      }
+    } catch (err) {
+      console.error(`Registry.dispatch: handler for "${label}" threw`, err);
+    }
+  }
+
+  toCallback<K extends Registered>(
+    type: K,
+  ): (raw: ConsumeMessage | null) => void {
+    const handler = this.handlers.get(type);
+    if (!handler) {
+      throw new Error(
+        `Registry.toCallback: no handler registered for "${String(type)}"`,
+      );
+    }
+    return (raw) => {
+      if (!raw) return;
+      let msg: EM[K];
+      try {
+        msg = this.parse(raw.content) as EM[K];
+      } catch (err) {
+        console.error(
+          `Registry.toCallback("${String(type)}"): failed to parse message body`,
+          err,
+        );
+        return;
+      }
+      this.runHandler(handler, msg as unknown, raw, String(type));
+    };
+  }
+
+  get bindings(): ReadonlyArray<{
+    type: Registered;
+    exchange: string;
+    routingKey: string;
+  }> {
+    const out: Array<{
+      type: Registered;
+      exchange: string;
+      routingKey: string;
+    }> = [];
+    for (const type of this.handlers.keys()) {
+      const meta = this.metaByType.get(type);
+      if (!meta) continue;
+      out.push({
+        type: type as Registered,
+        exchange: meta.exchange,
+        routingKey: meta.routingKey,
+      });
+    }
+    return out;
+  }
+}
+
+export function createRegistry<
+  // biome-ignore lint/suspicious/noExplicitAny: caller's spec defines its shape
+  EM extends Record<string, any>,
+>(
+  events: Readonly<Record<string, EventMeta>>,
+  opts: RegistryOptions = {},
+): Registry<EM> {
+  return new Registry<EM>(events, opts);
+}
+
+/** RabbitMQ topic-exchange routing-key matcher: `*` = one word, `#` = zero or more. */
+function matchRoutingKey(pattern: string, key: string): boolean {
+  return matchSegments(pattern.split("."), key.split("."));
+}
+
+function matchSegments(
+  p: ReadonlyArray<string>,
+  k: ReadonlyArray<string>,
+): boolean {
+  if (p.length === 0) return k.length === 0;
+  const head = p[0];
+  const tail = p.slice(1);
+  if (head === "#") {
+    for (let i = 0; i <= k.length; i++) {
+      if (matchSegments(tail, k.slice(i))) return true;
+    }
+    return false;
+  }
+  if (k.length === 0) return false;
+  if (head === "*" || head === k[0]) return matchSegments(tail, k.slice(1));
+  return false;
+}

package/runtime/go/api_client.go

@@ -0,0 +1,134 @@
+package api
+
+import (
+	"encoding/json"
+	"io"
+	"net/http"
+)
+
+// APIClient is the runtime helper every per-tag impl struct delegates
+// to. Owns the transport-level concerns — http.Client, the
+// interceptor pipeline — and provides one source of truth for status-
+// code dispatch and decoding.
+type APIClient struct {
+	BaseURL      string
+	HTTPClient   *http.Client
+	Interceptors []func(*http.Request) (*http.Request, error)
+	Auth         map[string]Auth
+}
+
+// NewAPIClient returns a client with the default http.Client and an
+// empty interceptors / auth slice / map. Callers may set fields
+// directly afterward to customize.
+func NewAPIClient(baseURL string) *APIClient {
+	return &APIClient{
+		BaseURL:    baseURL,
+		HTTPClient: http.DefaultClient,
+		Auth:       map[string]Auth{},
+	}
+}
+
+// Execute sends the request, runs the validator/transformer pipeline,
+// and JSON-decodes a 2xx body into a value of T. Caller picks T —
+// for object schemas pass *Pet, for collections pass []Pet or
+// map[string]int. Returns *APIError for non-2xx / transport /
+// encoding / decoding failures.
+func Execute[T any](client *APIClient, req *http.Request, opts RequestOptions) (T, error) {
+	var zero T
+	body, _, err := sendAndDispatch(client, req, opts)
+	if err != nil {
+		return zero, err
+	}
+	var value T
+	if err := json.Unmarshal(body, &value); err != nil {
+		return zero, Wrap(APIErrorKindDecoding, err)
+	}
+	return value, nil
+}
+
+// ExecuteWithResponse is Execute + the raw *http.Response.
+func ExecuteWithResponse[T any](client *APIClient, req *http.Request, opts RequestOptions) (T, *http.Response, error) {
+	var zero T
+	body, resp, err := sendAndDispatch(client, req, opts)
+	if err != nil {
+		return zero, nil, err
+	}
+	var value T
+	if err := json.Unmarshal(body, &value); err != nil {
+		return zero, nil, Wrap(APIErrorKindDecoding, err)
+	}
+	return value, resp, nil
+}
+
+// ExecuteUnit sends the request and discards the body — for ops with
+// no successful return type.
+func ExecuteUnit(client *APIClient, req *http.Request, opts RequestOptions) error {
+	_, _, err := sendAndDispatch(client, req, opts)
+	return err
+}
+
+// ExecuteUnitWithResponse is ExecuteUnit + the raw *http.Response.
+func ExecuteUnitWithResponse(client *APIClient, req *http.Request, opts RequestOptions) (*http.Response, error) {
+	_, resp, err := sendAndDispatch(client, req, opts)
+	return resp, err
+}
+
+// ExecuteRaw is the lowest-level execute — runs interceptors, sends,
+// status-dispatches, applies validator + transformer, hands the
+// (transformed) body + response back without decoding. Generated
+// methods reach for this when the operation has multiple 2xx response
+// schemas: the impl needs the status code to pick which type to decode.
+func ExecuteRaw(client *APIClient, req *http.Request, opts RequestOptions) ([]byte, *http.Response, error) {
+	return sendAndDispatch(client, req, opts)
+}
+
+func sendAndDispatch(client *APIClient, req *http.Request, opts RequestOptions) ([]byte, *http.Response, error) {
+	ctx, cancel := opts.applyTimeout(req.Context())
+	defer cancel()
+	req = req.WithContext(ctx)
+
+	for _, interceptor := range client.Interceptors {
+		next, err := interceptor(req)
+		if err != nil {
+			return nil, nil, Wrap(APIErrorKindTransport, err)
+		}
+		req = next
+	}
+	for _, interceptor := range opts.RequestInterceptors {
+		next, err := interceptor(req)
+		if err != nil {
+			return nil, nil, Wrap(APIErrorKindTransport, err)
+		}
+		req = next
+	}
+
+	resp, err := client.HTTPClient.Do(req)
+	if err != nil {
+		return nil, nil, Wrap(APIErrorKindTransport, err)
+	}
+	defer resp.Body.Close()
+
+	body, err := io.ReadAll(resp.Body)
+	if err != nil {
+		return nil, resp, Wrap(APIErrorKindTransport, err)
+	}
+
+	if resp.StatusCode < 200 || resp.StatusCode >= 300 {
+		return nil, resp, HTTPError(resp.StatusCode, body)
+	}
+
+	if opts.ResponseValidator != nil {
+		if err := opts.ResponseValidator(body, resp); err != nil {
+			return nil, resp, err
+		}
+	}
+	if opts.ResponseTransformer != nil {
+		transformed, err := opts.ResponseTransformer(body)
+		if err != nil {
+			return nil, resp, err
+		}
+		body = transformed
+	}
+
+	return body, resp, nil
+}

package/runtime/go/api_error.go

@@ -0,0 +1,86 @@
+package api
+
+import "fmt"
+
+// APIErrorKind classifies the failure mode an APIError represents.
+type APIErrorKind int
+
+const (
+	APIErrorKindClient APIErrorKind = iota
+	APIErrorKindServer
+	APIErrorKindUnexpected
+	APIErrorKindEncoding
+	APIErrorKindDecoding
+	APIErrorKindTransport
+)
+
+func (k APIErrorKind) String() string {
+	switch k {
+	case APIErrorKindClient:
+		return "client_error"
+	case APIErrorKindServer:
+		return "server_error"
+	case APIErrorKindUnexpected:
+		return "unexpected_status"
+	case APIErrorKindEncoding:
+		return "encoding"
+	case APIErrorKindDecoding:
+		return "decoding"
+	case APIErrorKindTransport:
+		return "transport"
+	default:
+		return fmt.Sprintf("unknown(%d)", int(k))
+	}
+}
+
+// APIError is the typed error every generated method returns.
+//
+//   - Kind tags the failure mode (client / server / unexpected status,
+//     decoding, transport).
+//   - StatusCode + Body are populated for non-2xx HTTP responses.
+//   - Cause wraps an underlying error (network, json, etc.); use
+//     errors.Is / errors.As to inspect.
+type APIError struct {
+	Kind       APIErrorKind
+	StatusCode int    // populated for ClientError / ServerError / Unexpected
+	Body       []byte // raw response body for HTTP errors
+	Cause      error  // underlying error for transport / encoding / decoding
+}
+
+func (e *APIError) Error() string {
+	if e.StatusCode != 0 {
+		return fmt.Sprintf("%s: status %d", e.Kind, e.StatusCode)
+	}
+	if e.Cause != nil {
+		return fmt.Sprintf("%s: %v", e.Kind, e.Cause)
+	}
+	return e.Kind.String()
+}
+
+func (e *APIError) Unwrap() error { return e.Cause }
+
+// Wrap is a convenience constructor for transient (non-HTTP) failures.
+func Wrap(kind APIErrorKind, cause error) *APIError {
+	return &APIError{Kind: kind, Cause: cause}
+}
+
+// HTTPError builds an APIError for a non-2xx response. The kind is
+// derived from the status range — 4xx → Client, 5xx → Server,
+// otherwise Unexpected.
+func HTTPError(statusCode int, body []byte) *APIError {
+	var kind APIErrorKind
+	switch {
+	case statusCode >= 400 && statusCode < 500:
+		kind = APIErrorKindClient
+	case statusCode >= 500 && statusCode < 600:
+		kind = APIErrorKindServer
+	default:
+		kind = APIErrorKindUnexpected
+	}
+	return &APIError{Kind: kind, StatusCode: statusCode, Body: body}
+}
+
+// Unexpected — sugar for APIError on an unrecognized status code.
+func Unexpected(statusCode int, body []byte) *APIError {
+	return &APIError{Kind: APIErrorKindUnexpected, StatusCode: statusCode, Body: body}
+}

package/runtime/go/api_key_location.go

@@ -0,0 +1,10 @@
+package api
+
+// APIKeyLocation matches the OpenAPI securitySchemes.<name>.in field.
+type APIKeyLocation int
+
+const (
+	APIKeyHeader APIKeyLocation = iota
+	APIKeyQuery
+	APIKeyCookie
+)

package/runtime/go/auth.go

@@ -0,0 +1,66 @@
+package api
+
+import (
+	"encoding/base64"
+	"fmt"
+	"net/http"
+	"net/url"
+)
+
+// Auth is the interface implemented by Bearer / APIKey / Basic. Per-
+// operation auto-wiring (when the spec declares securitySchemes) walks
+// the configured client.Auth map and calls Apply on the matching scheme.
+//
+// Apply mutates the request in-place for header / cookie auth and
+// returns the (possibly rewritten) URL for query auth. Generated impl
+// code re-attaches the URL via req.URL = u after the loop.
+type Auth interface {
+	Apply(req *http.Request, u *url.URL) *url.URL
+}
+
+// BearerAuth — Authorization: Bearer <token>.
+type BearerAuth struct{ Token string }
+
+func (a BearerAuth) Apply(req *http.Request, u *url.URL) *url.URL {
+	req.Header.Set("Authorization", "Bearer "+a.Token)
+	return u
+}
+
+// APIKeyAuth — header / query / cookie placement of <name>=<value>.
+type APIKeyAuth struct {
+	Name     string
+	Value    string
+	Location APIKeyLocation
+}
+
+func (a APIKeyAuth) Apply(req *http.Request, u *url.URL) *url.URL {
+	switch a.Location {
+	case APIKeyHeader:
+		req.Header.Set(a.Name, a.Value)
+		return u
+	case APIKeyQuery:
+		q := u.Query()
+		q.Set(a.Name, a.Value)
+		u2 := *u
+		u2.RawQuery = q.Encode()
+		return &u2
+	case APIKeyCookie:
+		existing := req.Header.Get("Cookie")
+		cookie := fmt.Sprintf("%s=%s", a.Name, a.Value)
+		if existing != "" {
+			cookie = existing + "; " + cookie
+		}
+		req.Header.Set("Cookie", cookie)
+		return u
+	}
+	return u
+}
+
+// BasicAuth — Authorization: Basic base64(user:pass).
+type BasicAuth struct{ Username, Password string }
+
+func (a BasicAuth) Apply(req *http.Request, u *url.URL) *url.URL {
+	creds := base64.StdEncoding.EncodeToString([]byte(a.Username + ":" + a.Password))
+	req.Header.Set("Authorization", "Basic "+creds)
+	return u
+}

package/runtime/go/go.mod

@@ -0,0 +1,3 @@
+module github.com/ahmedrowaihi/ir-kit/packages/ir-kit/runtime/go
+
+go 1.22

package/runtime/go/multipart_form_body.go

@@ -0,0 +1,48 @@
+package api
+
+import (
+	"bytes"
+	"mime/multipart"
+)
+
+// MultipartFormBody assembles a multipart/form-data request body.
+// Mirrors the runtime helper Swift / Kotlin generators ship; thin
+// wrapper over the stdlib mime/multipart writer, kept around so the
+// generated impl reads symmetric across languages.
+type MultipartFormBody struct {
+	buf    *bytes.Buffer
+	writer *multipart.Writer
+}
+
+// NewMultipartFormBody constructs an empty multipart body.
+func NewMultipartFormBody() *MultipartFormBody {
+	buf := &bytes.Buffer{}
+	return &MultipartFormBody{buf: buf, writer: multipart.NewWriter(buf)}
+}
+
+// AppendText writes a text form field.
+func (m *MultipartFormBody) AppendText(name, value string) error {
+	return m.writer.WriteField(name, value)
+}
+
+// AppendFile writes a binary form field. Uses CreateFormFile so name
+// and filename are properly escaped/quoted.
+func (m *MultipartFormBody) AppendFile(name, filename string, content []byte) error {
+	w, err := m.writer.CreateFormFile(name, filename)
+	if err != nil {
+		return err
+	}
+	_, err = w.Write(content)
+	return err
+}
+
+// ContentType returns the multipart/form-data Content-Type header
+// including the boundary string.
+func (m *MultipartFormBody) ContentType() string { return m.writer.FormDataContentType() }
+
+// Bytes finalizes the multipart body and returns the assembled bytes.
+// Subsequent AppendText / AppendFile calls have undefined behavior.
+func (m *MultipartFormBody) Bytes() []byte {
+	_ = m.writer.Close()
+	return m.buf.Bytes()
+}

package/runtime/go/query_style.go

@@ -0,0 +1,12 @@
+package api
+
+// QueryStyle controls how array-valued query parameters are
+// serialized when explode is false. Matches the OpenAPI 3 `style`
+// field. The default is QueryStyleForm with explode=true.
+type QueryStyle int
+
+const (
+	QueryStyleForm QueryStyle = iota
+	QueryStyleSpaceDelimited
+	QueryStylePipeDelimited
+)

package/runtime/go/request_options.go

@@ -0,0 +1,41 @@
+package api
+
+import (
+	"context"
+	"net/http"
+	"time"
+)
+
+// RequestOptions is the per-call options bag every generated method
+// takes as its trailing argument. Mirrors hey-api's TS SDK options
+// shape.
+//
+//   - Client overrides the impl's bound *APIClient for one call.
+//   - BaseURL overrides client.BaseURL for one call.
+//   - Timeout, when non-zero, derives a context with that deadline
+//     from the call's ctx. Use ctx.WithDeadline yourself for finer
+//     control; this is the convenience knob.
+//   - Headers are extra/override headers, applied last (so callers
+//     can override Content-Type / auth headers if they want).
+//   - RequestInterceptors run after client-level ones.
+//   - ResponseValidator runs after a 2xx response; returning an error
+//     converts the call into a failure.
+//   - ResponseTransformer rewrites the response body before decoding.
+type RequestOptions struct {
+	Client              *APIClient
+	BaseURL             string
+	Timeout             time.Duration
+	Headers             map[string]string
+	RequestInterceptors []func(*http.Request) (*http.Request, error)
+	ResponseValidator   func(body []byte, resp *http.Response) error
+	ResponseTransformer func(body []byte) ([]byte, error)
+}
+
+// applyTimeout returns a context derived from ctx with opts.Timeout
+// as a deadline. Returns ctx unchanged when Timeout is zero.
+func (opts RequestOptions) applyTimeout(ctx context.Context) (context.Context, context.CancelFunc) {
+	if opts.Timeout <= 0 {
+		return ctx, func() {}
+	}
+	return context.WithTimeout(ctx, opts.Timeout)
+}

package/runtime/go/url_encoding.go

@@ -0,0 +1,68 @@
+package api
+
+import (
+	"fmt"
+	"net/url"
+	"reflect"
+	"strings"
+)
+
+// URLEncoding helpers used by generated impl methods to add OpenAPI-
+// shaped query parameters onto a url.Values without each call site
+// having to know the style/explode rules.
+var URLEncoding = urlEncoding{}
+
+type urlEncoding struct{}
+
+// AddScalar appends a single key/value pair, skipping nil pointers
+// and empty optional values.
+func (urlEncoding) AddScalar(q url.Values, name string, value any) {
+	if value == nil {
+		return
+	}
+	v := reflect.ValueOf(value)
+	if v.Kind() == reflect.Ptr {
+		if v.IsNil() {
+			return
+		}
+		v = v.Elem()
+	}
+	q.Set(name, fmt.Sprint(v.Interface()))
+}
+
+// AddArray appends an array-valued query parameter following the
+// OpenAPI `style` + `explode` rules. explode=true emits one
+// `?name=v` per element; explode=false joins per the style separator.
+func (urlEncoding) AddArray(q url.Values, name string, values any, style QueryStyle, explode bool) {
+	v := reflect.ValueOf(values)
+	if v.Kind() == reflect.Ptr {
+		if v.IsNil() {
+			return
+		}
+		v = v.Elem()
+	}
+	if v.Kind() != reflect.Slice && v.Kind() != reflect.Array {
+		return
+	}
+	if v.Len() == 0 {
+		return
+	}
+	if explode {
+		for i := 0; i < v.Len(); i++ {
+			q.Add(name, fmt.Sprint(v.Index(i).Interface()))
+		}
+		return
+	}
+	sep := ","
+	switch style {
+	case QueryStyleSpaceDelimited:
+		sep = " "
+	case QueryStylePipeDelimited:
+		sep = "|"
+	}
+	parts := make([]string, v.Len())
+	for i := 0; i < v.Len(); i++ {
+		parts[i] = fmt.Sprint(v.Index(i).Interface())
+	}
+	q.Set(name, strings.Join(parts, sep))
+}