{"id":41915459,"url":"https://github.com/origadmin/runtime","last_synced_at":"2026-01-25T16:22:02.689Z","repository":{"id":265242480,"uuid":"895423994","full_name":"origadmin/runtime","owner":"origadmin","description":null,"archived":false,"fork":false,"pushed_at":"2026-01-21T10:00:27.000Z","size":6351,"stargazers_count":1,"open_issues_count":6,"forks_count":0,"subscribers_count":1,"default_branch":"main","last_synced_at":"2026-01-21T21:28:14.732Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"language":"Go","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/origadmin.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":".github/CODE_OF_CONDUCT.md","threat_model":null,"audit":null,"citation":null,"codeowners":".github/CODEOWNERS","security":".github/SECURITY.md","support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2024-11-28T07:23:16.000Z","updated_at":"2026-01-21T10:00:43.000Z","dependencies_parsed_at":"2024-12-30T19:19:12.505Z","dependency_job_id":"b3677381-7272-41a0-b2a9-4892c1f1d22c","html_url":"https://github.com/origadmin/runtime","commit_stats":null,"previous_names":["origadmin/runtime"],"tags_count":90,"template":false,"template_full_name":"origadmin/.github","purl":"pkg:github/origadmin/runtime","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/origadmin%2Fruntime","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/origadmin%2Fruntime/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/origadmin%2Fruntime/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/origadmin%2Fruntime/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/origadmin","download_url":"https://codeload.github.com/origadmin/runtime/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/origadmin%2Fruntime/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":28755230,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-01-25T13:59:49.818Z","status":"ssl_error","status_checked_at":"2026-01-25T13:59:33.728Z","response_time":113,"last_error":"SSL_read: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2026-01-25T16:22:01.913Z","updated_at":"2026-01-25T16:22:02.662Z","avatar_url":"https://github.com/origadmin.png","language":"Go","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Runtime Package\n\n## Introduction\n\nThe `@/runtime` package serves as the foundational implementation for building **distributed-ready services** within our system, **leveraging the Kratos microservice framework**. It provides a set of core abstractions and utilities that **simplify the development and management of Kratos-based services**, enabling developers to write business logic independent of the underlying deployment model.\n\nThis design ensures that services developed using this package are inherently **loosely coupled** and **independently deployable**. Whether initially deployed as part of a monolithic application or as standalone microservices, the transition between these deployment modes can be achieved seamlessly by simply changing the underlying infrastructure implementations, without requiring modifications to the core business code.\n\nThe `Runtime` component centralizes the management of essential resources required for service operation, including configuration, logging, monitoring, caching, and data storage, **all integrated within the Kratos ecosystem.**\n\n## Core Philosophy / Design Principles\n\n1.  **Kratos-Native Development**: The `@/runtime` package is built upon the Kratos framework, providing a streamlined and opinionated way to develop Kratos-based microservices. It aims to reduce boilerplate and enforce best practices within the Kratos ecosystem.\n2.  **Deployment Agnosticism**: Business logic should be decoupled from deployment concerns. By leveraging Kratos's robust capabilities, the `@/runtime` package provides abstractions that allow services to run equally well in a single process (monolithic deployment) or across multiple nodes (distributed deployment).\n3.  **Loose Coupling by Design**: Through standardized interfaces and explicit communication mechanisms (e.g., API contracts, gRPC), the package, in conjunction with Kratos's service discovery and communication patterns, encourages and facilitates the development of services that are inherently loosely coupled, making them easier to test, maintain, and evolve independently.\n4.  **Infrastructure Simplification \u0026 Swappability**: It abstracts away the complexities of underlying infrastructure components (e.g., configuration sources, logging backends, service discovery mechanisms). This allows for easy swapping of different infrastructure implementations (e.g., from local file-based config to a distributed config center) as the system scales, without impacting the service's core logic, **all while integrating seamlessly with Kratos's extension points.**\n5.  **Standardization \u0026 Consistency**: The package provides a consistent set of patterns and tools for common cross-cutting concerns, ensuring a standardized development and operational experience across all services built on this architecture, **adhering to Kratos's architectural principles.**\n\n## Naming Conventions\n\nTo ensure clarity and consistency within the `@/runtime` package, especially given its close integration with the Kratos framework, we adhere to the following naming conventions:\n\n1.  **Kratos-Specific Elements**: Any type, interface, or struct that is directly from the Kratos framework, or is a direct wrapper/alias/bridge implementation of a Kratos element within `@/runtime`, **must be prefixed with `K`**.\n    *   **Purpose**: This clearly indicates that the element is Kratos-native or directly interacts with Kratos.\n    *   **Examples**: `KRegistrar`, `KDiscovery`, `KApp`, `KServer`.\n\n2.  **@/runtime Abstractions**: Any type, interface, or struct defined within `@/runtime` that represents a general-purpose abstraction or utility, even if its underlying implementation uses Kratos, **should NOT be prefixed with `K`**.\n    *   **Purpose**: These are the public-facing APIs of the `@/runtime` package, designed to be used by business logic without direct Kratos dependency at the interface level.\n    *   **Examples**: `Sender` (for mail), `StorageProvider`, `ConfigLoader`.\n\nThis distinction helps developers quickly understand the nature and scope of each component, promoting better code readability and maintainability.\n\n### Before You Start\n\nBefore you start using the Runtime package, ensure that you have the following prerequisites:\nIn order to prevent import conflicts caused by packages with the same name as `kratos`, packages with the same name in\nthis database will import the export content from `kratos`.\nAll type definitions will be prefixed with the `K` fixed prefix.\nNote: Only `type` declarations are prefixed, not functions.\n\n### Available Packages\n\n- **[bootstrap](bootstrap)**: The bootstrap package contains Configuration file reading and writing, initialization\n  variable declaration, etc\n- **[cmd](cmd)**: Contains command-line utilities or example main packages for the runtime.\n- **[config](config)**: The files in this directory define the basic configuration of the service runtime, as well as\n  the loading of the run configuration.\n- **[context](context)**: The context directory defines the context interface and the context implementation.\n- **[gen](gen)**: This directory contains **generated code** (e.g., Go structs, gRPC service stubs) derived from the Protocol Buffer (`.proto`) definition files.\n- **[internal](internal)**: Contains internal packages and helper utilities not intended for external consumption.\n- **[log](log)**: Provides logging interfaces and implementations for the runtime, integrated with Kratos's logging system.\n- **[mail](mail)**: The mail directory defines the email interface and the email implementation.\n- **[middleware](middleware)**: The middleware directory defines the middleware interface and the middleware **implementation for common cross-cutting concerns like authentication, logging, and rate limiting.**\n- **[proto](proto)**: This directory contains the **original Protocol Buffer (`.proto`) definition files** that define the service interfaces and data structures. These files are used to generate code for various languages, ensuring compatibility and strong typing across different services.\n- **[registry](registry)**: This directory defines an alias for 'kratos/v2/registry', primarily for backward\n  compatibility and for placing import error paths.\n- **[service](service)**: The service directory contains the definition of the service interface, which is used to\n  define the interface of the service and the implementation of the service.\n- **[storage](storage)**: This directory provides **abstractions and implementations for various data storage mechanisms**, including caching, databases, and file storage. It centralizes data access concerns, allowing services to easily swap underlying storage technologies.\n- **[third_party](third_party)**: Contains vendored or third-party code dependencies.\n\n### Top-Level Files\n\n- **`runtime.go`**: The main entry point and core logic for the runtime package, orchestrating the initialization and lifecycle of services.\n- **`generate.go`**: Defines `go generate` commands used for automated code generation tasks, such as generating protobuf code.\n- **`buf.lock`**: A lock file generated by Buf, ensuring reproducible builds of Protocol Buffers.\n- **`buf.yaml`**: The main configuration file for Buf, defining linting rules, formatting, and other settings for `.proto` files.\n- **`buf.gen.yaml`**: Configuration for Buf's code generation, specifying how `.proto` files are compiled into code for different languages (e.g., Go).\n\n## Getting Started\n\nTo incorporate the Toolkit into your project, follow these steps:\n\n1. **Add the dependency**: Add the Toolkit as a dependency in your `go.mod` file, specifying the latest version:\n\n```bash\n\ngo get github.com/origadmin/runtime@vX.Y.Z\n\n```\n\nReplace `vX.Y.Z` with the desired version or `latest` to fetch the most recent release.\n\n2. **Import required packages**: In your Go source files, import the necessary packages from the Toolkit:\n\n```go\nimport (\n\"github.com/origadmin/runtime\"\n\"github.com/origadmin/runtime/config\"\n\"github.com/origadmin/runtime/registry\"\n)\n\n// NewDiscovery creates a new discovery.\nfunc NewDiscovery(registryConfig *config.RegistryConfig) registry.Discovery {\nif registryConfig == nil {\npanic(\"no registry config\")\n}\ndiscovery, err := runtime.NewDiscovery(registryConfig)\nif err != nil {\npanic(err)\n}\nreturn discovery\n}\n\n// NewRegistrar creates a new registrar.\nfunc NewRegistrar(registryConfig *config.RegistryConfig) registry.Registrar {\nif registryConfig == nil {\npanic(\"no registry config\")\n}\nregistrar, err := runtime.NewRegistrar(registryConfig)\nif err != nil {\npanic(err)\n}\nreturn registrar\n}\n\n```\n\n## Contributing\n\nWe welcome contributions from the community to improve and expand the Toolkit. To contribute, please follow these\nguidelines:\n\n1. **Familiarize yourself with the project**: Read the [CONTRIBUTING] file for details on the contribution process, code\n   style, and Pull Request requirements.\n2. **Submit an issue or proposal**: If you encounter any bugs, have feature suggestions, or want to discuss potential\n   changes, create an issue in the [GitHub repository](https://github.com/origadmin/toolkit).\n3. **Create a Pull Request**: After implementing your changes, submit a Pull Request following the guidelines outlined\n   in [CONTRIBUTING].\n\n## Contributors\n\n### Code of Conduct\n\nAll contributors and participants are expected to abide by the [Contributor Covenant][ContributorHomepage],\nversion [2.1][v2.1]. This document outlines the expected behavior when interacting with the Toolkit community.\n\n## License\n\nThe Toolkit is distributed under the terms of the [MIT]. This permissive license allows for free use, modification, and\ndistribution of the toolkit in both commercial and non-commercial contexts.\n\n[CONTRIBUTING]: CONTRIBUTING.md\n\n[ContributorHomepage]: https://www.contributor-covenant.org\n\n[v2.1]: https://www.contributor-covenant.org/version/2/1/code_of_conduct.html\n\n[MIT]: LICENSE\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Forigadmin%2Fruntime","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Forigadmin%2Fruntime","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Forigadmin%2Fruntime/lists"}