Look, HTML
"), + }) + }) + ``` + + The attachment will then be accessible on the Issue Details page. + +- Add sampling decision to trace envelope header ([#666](https://github.com/getsentry/sentry-go/pull/666)) +- Expose SpanFromContext function ([#672](https://github.com/getsentry/sentry-go/pull/672)) + +### Bug fixes + +- Make `Span.Finish` a no-op when the span is already finished ([#660](https://github.com/getsentry/sentry-go/pull/660)) + +## 0.22.0 + +The Sentry SDK team is happy to announce the immediate availability of Sentry Go SDK v0.22.0. + +This release contains initial [profiling](https://docs.sentry.io/product/profiling/) support, as well as a few bug fixes and improvements. + +### Features + +- Initial (alpha) support for [profiling](https://docs.sentry.io/product/profiling/) ([#626](https://github.com/getsentry/sentry-go/pull/626)) + + Profiling is disabled by default. To enable it, configure both `TracesSampleRate` and `ProfilesSampleRate` when initializing the SDK: + + ```go + err := sentry.Init(sentry.ClientOptions{ + Dsn: "__DSN__", + EnableTracing: true, + TracesSampleRate: 1.0, + // The sampling rate for profiling is relative to TracesSampleRate. In this case, we'll capture profiles for 100% of transactions. + ProfilesSampleRate: 1.0, + }) + ``` + + More documentation on profiling and current limitations [can be found here](https://docs.sentry.io/platforms/go/profiling/). + +- Add transactions/tracing support go the Gin integration ([#644](https://github.com/getsentry/sentry-go/pull/644)) + +### Bug fixes + +- Always set a valid source on transactions ([#637](https://github.com/getsentry/sentry-go/pull/637)) +- Clone scope.Context in more places to avoid panics on concurrent reads and writes ([#638](https://github.com/getsentry/sentry-go/pull/638)) + - Fixes [#570](https://github.com/getsentry/sentry-go/issues/570) +- Fix frames recognized as not being in-app still showing as in-app ([#647](https://github.com/getsentry/sentry-go/pull/647)) + +## 0.21.0 + +The Sentry SDK team is happy to announce the immediate availability of Sentry Go SDK v0.21.0. + +Note: this release includes one **breaking change** and some **deprecations**, which are listed below. + +### Breaking Changes + +**This change does not apply if you use [https://sentry.io](https://sentry.io)** + +- Remove support for the `/store` endpoint ([#631](https://github.com/getsentry/sentry-go/pull/631)) + - This change requires a self-hosted version of Sentry 20.6.0 or higher. If you are using a version of [self-hosted Sentry](https://develop.sentry.dev/self-hosted/) (aka *on-premise*) older than 20.6.0, then you will need to [upgrade](https://develop.sentry.dev/self-hosted/releases/) your instance. + +### Features + +- Rename four span option functions ([#611](https://github.com/getsentry/sentry-go/pull/611), [#624](https://github.com/getsentry/sentry-go/pull/624)) + - `TransctionSource` -> `WithTransactionSource` + - `SpanSampled` -> `WithSpanSampled` + - `OpName` -> `WithOpName` + - `TransactionName` -> `WithTransactionName` + - Old functions `TransctionSource`, `SpanSampled`, `OpName`, and `TransactionName` are still available but are now **deprecated** and will be removed in a future release. +- Make `client.EventFromMessage` and `client.EventFromException` methods public ([#607](https://github.com/getsentry/sentry-go/pull/607)) +- Add `client.SetException` method ([#607](https://github.com/getsentry/sentry-go/pull/607)) + - This allows to set or add errors to an existing `Event`. + +### Bug Fixes + +- Protect from panics while doing concurrent reads/writes to Span data fields ([#609](https://github.com/getsentry/sentry-go/pull/609)) +- [otel] Improve detection of Sentry-related spans ([#632](https://github.com/getsentry/sentry-go/pull/632), [#636](https://github.com/getsentry/sentry-go/pull/636)) + - Fixes cases when HTTP spans containing requests to Sentry were captured by Sentry ([#627](https://github.com/getsentry/sentry-go/issues/627)) + +### Misc + +- Drop testing in (legacy) GOPATH mode ([#618](https://github.com/getsentry/sentry-go/pull/618)) +- Remove outdated documentation from https://pkg.go.dev/github.com/getsentry/sentry-go ([#623](https://github.com/getsentry/sentry-go/pull/623)) + +## 0.20.0 + +The Sentry SDK team is happy to announce the immediate availability of Sentry Go SDK v0.20.0. + +Note: this release has some **breaking changes**, which are listed below. + +### Breaking Changes + +- Remove the following methods: `Scope.SetTransaction()`, `Scope.Transaction()` ([#605](https://github.com/getsentry/sentry-go/pull/605)) + + Span.Name should be used instead to access the transaction's name. + + For example, the following [`TracesSampler`](https://docs.sentry.io/platforms/go/configuration/sampling/#setting-a-sampling-function) function should be now written as follows: + + **Before:** + ```go + TracesSampler: func(ctx sentry.SamplingContext) float64 { + hub := sentry.GetHubFromContext(ctx.Span.Context()) + if hub.Scope().Transaction() == "GET /health" { + return 0 + } + return 1 + }, + ``` + + **After:** + ```go + TracesSampler: func(ctx sentry.SamplingContext) float64 { + if ctx.Span.Name == "GET /health" { + return 0 + } + return 1 + }, + ``` + +### Features + +- Add `Span.SetContext()` method ([#599](https://github.com/getsentry/sentry-go/pull/599/)) + - It is recommended to use it instead of `hub.Scope().SetContext` when setting or updating context on transactions. +- Add `DebugMeta` interface to `Event` and extend `Frame` structure with more fields ([#606](https://github.com/getsentry/sentry-go/pull/606)) + - More about DebugMeta interface [here](https://develop.sentry.dev/sdk/event-payloads/debugmeta/). + +### Bug Fixes + +- [otel] Fix missing OpenTelemetry context on some events ([#599](https://github.com/getsentry/sentry-go/pull/599), [#605](https://github.com/getsentry/sentry-go/pull/605)) + - Fixes ([#596](https://github.com/getsentry/sentry-go/issues/596)). +- [otel] Better handling for HTTP span attributes ([#610](https://github.com/getsentry/sentry-go/pull/610)) + +### Misc + +- Bump minimum versions: `github.com/kataras/iris/v12` to 12.2.0, `github.com/labstack/echo/v4` to v4.10.0 ([#595](https://github.com/getsentry/sentry-go/pull/595)) + - Resolves [GO-2022-1144 / CVE-2022-41717](https://deps.dev/advisory/osv/GO-2022-1144), [GO-2023-1495 / CVE-2022-41721](https://deps.dev/advisory/osv/GO-2023-1495), [GO-2022-1059 / CVE-2022-32149](https://deps.dev/advisory/osv/GO-2022-1059). +- Bump `google.golang.org/protobuf` minimum required version to 1.29.1 ([#604](https://github.com/getsentry/sentry-go/pull/604)) + - This fixes a potential denial of service issue ([CVE-2023-24535](https://github.com/advisories/GHSA-hw7c-3rfg-p46j)). +- Exclude the `otel` module when building in GOPATH mode ([#615](https://github.com/getsentry/sentry-go/pull/615)) + +## 0.19.0 + +The Sentry SDK team is happy to announce the immediate availability of Sentry Go SDK v0.19.0. + +### Features + +- Add support for exception mechanism metadata ([#564](https://github.com/getsentry/sentry-go/pull/564/)) + - More about exception mechanisms [here](https://develop.sentry.dev/sdk/event-payloads/exception/#exception-mechanism). + +### Bug Fixes +- [otel] Use the correct "trace" context when sending a Sentry error ([#580](https://github.com/getsentry/sentry-go/pull/580/)) + + +### Misc +- Drop support for Go 1.17, add support for Go 1.20 ([#563](https://github.com/getsentry/sentry-go/pull/563/)) + - According to our policy, we're officially supporting the last three minor releases of Go. +- Switch repository license to MIT ([#583](https://github.com/getsentry/sentry-go/pull/583/)) + - More about Sentry licensing [here](https://open.sentry.io/licensing/). +- Bump `golang.org/x/text` minimum required version to 0.3.8 ([#586](https://github.com/getsentry/sentry-go/pull/586)) + - This fixes [CVE-2022-32149](https://github.com/advisories/GHSA-69ch-w2m2-3vjp) vulnerability. + +## 0.18.0 + +The Sentry SDK team is happy to announce the immediate availability of Sentry Go SDK v0.18.0. +This release contains initial support for [OpenTelemetry](https://opentelemetry.io/) and various other bug fixes and improvements. + +**Note**: This is the last release supporting Go 1.17. + +### Features + +- Initial support for [OpenTelemetry](https://opentelemetry.io/). + You can now send all your OpenTelemetry spans to Sentry. + + Install the `otel` module + + ```bash + go get github.com/getsentry/sentry-go \ + github.com/getsentry/sentry-go/otel + ``` + + Configure the Sentry and OpenTelemetry SDKs + + ```go + import ( + "go.opentelemetry.io/otel" + sdktrace "go.opentelemetry.io/otel/sdk/trace" + "github.com/getsentry/sentry-go" + "github.com/getsentry/sentry-go/otel" + // ... + ) + + // Initlaize the Sentry SDK + sentry.Init(sentry.ClientOptions{ + Dsn: "__DSN__", + EnableTracing: true, + TracesSampleRate: 1.0, + }) + + // Set up the Sentry span processor + tp := sdktrace.NewTracerProvider( + sdktrace.WithSpanProcessor(sentryotel.NewSentrySpanProcessor()), + // ... + ) + otel.SetTracerProvider(tp) + + // Set up the Sentry propagator + otel.SetTextMapPropagator(sentryotel.NewSentryPropagator()) + ``` + + You can read more about using OpenTelemetry with Sentry in our [docs](https://docs.sentry.io/platforms/go/performance/instrumentation/opentelemetry/). + +### Bug Fixes + +- Do not freeze the Dynamic Sampling Context when no Sentry values are present in the baggage header ([#532](https://github.com/getsentry/sentry-go/pull/532)) +- Create a frozen Dynamic Sampling Context when calling `span.ToBaggage()` ([#566](https://github.com/getsentry/sentry-go/pull/566)) +- Fix baggage parsing and encoding in vendored otel package ([#568](https://github.com/getsentry/sentry-go/pull/568)) + +### Misc + +- Add `Span.SetDynamicSamplingContext()` ([#539](https://github.com/getsentry/sentry-go/pull/539/)) +- Add various getters for `Dsn` ([#540](https://github.com/getsentry/sentry-go/pull/540)) +- Add `SpanOption::SpanSampled` ([#546](https://github.com/getsentry/sentry-go/pull/546)) +- Add `Span.SetData()` ([#542](https://github.com/getsentry/sentry-go/pull/542)) +- Add `Span.IsTransaction()` ([#543](https://github.com/getsentry/sentry-go/pull/543)) +- Add `Span.GetTransaction()` method ([#558](https://github.com/getsentry/sentry-go/pull/558)) + +## 0.17.0 + +The Sentry SDK team is happy to announce the immediate availability of Sentry Go SDK v0.17.0. +This release contains a new `BeforeSendTransaction` hook option and corrects two regressions introduced in `0.16.0`. + +### Features + +- Add `BeforeSendTransaction` hook to `ClientOptions` ([#517](https://github.com/getsentry/sentry-go/pull/517)) + - Here's [an example](https://github.com/getsentry/sentry-go/blob/master/_examples/http/main.go#L56-L66) of how BeforeSendTransaction can be used to modify or drop transaction events. + +### Bug Fixes + +- Do not crash in Span.Finish() when the Client is empty [#520](https://github.com/getsentry/sentry-go/pull/520) + - Fixes [#518](https://github.com/getsentry/sentry-go/issues/518) +- Attach non-PII/non-sensitive request headers to events when `ClientOptions.SendDefaultPii` is set to `false` ([#524](https://github.com/getsentry/sentry-go/pull/524)) + - Fixes [#523](https://github.com/getsentry/sentry-go/issues/523) + +### Misc + +- Clarify how to handle logrus.Fatalf events ([#501](https://github.com/getsentry/sentry-go/pull/501/)) +- Rename the `examples` directory to `_examples` ([#521](https://github.com/getsentry/sentry-go/pull/521)) + - This removes an indirect dependency to `github.com/golang-jwt/jwt` + +## 0.16.0 + +The Sentry SDK team is happy to announce the immediate availability of Sentry Go SDK v0.16.0. +Due to ongoing work towards a stable API for `v1.0.0`, we sadly had to include **two breaking changes** in this release. + +### Breaking Changes + +- Add `EnableTracing`, a boolean option flag to enable performance monitoring (`false` by default). + - If you're using `TracesSampleRate` or `TracesSampler`, this option is **required** to enable performance monitoring. + + ```go + sentry.Init(sentry.ClientOptions{ + EnableTracing: true, + TracesSampleRate: 1.0, + }) + ``` +- Unify TracesSampler [#498](https://github.com/getsentry/sentry-go/pull/498) + - `TracesSampler` was changed to a callback that must return a `float64` between `0.0` and `1.0`. + + For example, you can apply a sample rate of `1.0` (100%) to all `/api` transactions, and a sample rate of `0.5` (50%) to all other transactions. + You can read more about this in our [SDK docs](https://docs.sentry.io/platforms/go/configuration/filtering/#using-sampling-to-filter-transaction-events). + + ```go + sentry.Init(sentry.ClientOptions{ + TracesSampler: sentry.TracesSampler(func(ctx sentry.SamplingContext) float64 { + hub := sentry.GetHubFromContext(ctx.Span.Context()) + name := hub.Scope().Transaction() + + if strings.HasPrefix(name, "GET /api") { + return 1.0 + } + + return 0.5 + }), + } + ``` + +### Features + +- Send errors logged with [Logrus](https://github.com/sirupsen/logrus) to Sentry. + - Have a look at our [logrus examples](https://github.com/getsentry/sentry-go/blob/master/_examples/logrus/main.go) on how to use the integration. +- Add support for Dynamic Sampling [#491](https://github.com/getsentry/sentry-go/pull/491) + - You can read more about Dynamic Sampling in our [product docs](https://docs.sentry.io/product/data-management-settings/dynamic-sampling/). +- Add detailed logging about the reason transactions are being dropped. + - You can enable SDK logging via `sentry.ClientOptions.Debug: true`. + +### Bug Fixes + +- Do not clone the hub when calling `StartTransaction` [#505](https://github.com/getsentry/sentry-go/pull/505) + - Fixes [#502](https://github.com/getsentry/sentry-go/issues/502) + +## 0.15.0 + +- fix: Scope values should not override Event values (#446) +- feat: Make maximum amount of spans configurable (#460) +- feat: Add a method to start a transaction (#482) +- feat: Extend User interface by adding Data, Name and Segment (#483) +- feat: Add ClientOptions.SendDefaultPII (#485) + +## 0.14.0 + +- feat: Add function to continue from trace string (#434) +- feat: Add `max-depth` options (#428) +- *[breaking]* ref: Use a `Context` type mapping to a `map[string]interface{}` for all event contexts (#444) +- *[breaking]* ref: Replace deprecated `ioutil` pkg with `os` & `io` (#454) +- ref: Optimize `stacktrace.go` from size and speed (#467) +- ci: Test against `go1.19` and `go1.18`, drop `go1.16` and `go1.15` support (#432, #477) +- deps: Dependency update to fix CVEs (#462, #464, #477) + +_NOTE:_ This version drops support for Go 1.16 and Go 1.15. The currently supported Go versions are the last 3 stable releases: 1.19, 1.18 and 1.17. + +## v0.13.0 + +- ref: Change DSN ProjectID to be a string (#420) +- fix: When extracting PCs from stack frames, try the `PC` field (#393) +- build: Bump gin-gonic/gin from v1.4.0 to v1.7.7 (#412) +- build: Bump Go version in go.mod (#410) +- ci: Bump golangci-lint version in GH workflow (#419) +- ci: Update GraphQL config with appropriate permissions (#417) +- ci: ci: Add craft release automation (#422) + +## v0.12.0 + +- feat: Automatic Release detection (#363, #369, #386, #400) +- fix: Do not change Hub.lastEventID for transactions (#379) +- fix: Do not clear LastEventID when events are dropped (#382) +- Updates to documentation (#366, #385) + +_NOTE:_ +This version drops support for Go 1.14, however no changes have been made that would make the SDK not work with Go 1.14. The currently supported Go versions are the last 3 stable releases: 1.15, 1.16 and 1.17. +There are two behavior changes related to `LastEventID`, both of which were intended to align the behavior of the Sentry Go SDK with other Sentry SDKs. +The new [automatic release detection feature](https://github.com/getsentry/sentry-go/issues/335) makes it easier to use Sentry and separate events per release without requiring extra work from users. We intend to improve this functionality in a future release by utilizing information that will be available in runtime starting with Go 1.18. The tracking issue is [#401](https://github.com/getsentry/sentry-go/issues/401). + +## v0.11.0 + +- feat(transports): Category-based Rate Limiting ([#354](https://github.com/getsentry/sentry-go/pull/354)) +- feat(transports): Report User-Agent identifying SDK ([#357](https://github.com/getsentry/sentry-go/pull/357)) +- fix(scope): Include event processors in clone ([#349](https://github.com/getsentry/sentry-go/pull/349)) +- Improvements to `go doc` documentation ([#344](https://github.com/getsentry/sentry-go/pull/344), [#350](https://github.com/getsentry/sentry-go/pull/350), [#351](https://github.com/getsentry/sentry-go/pull/351)) +- Miscellaneous changes to our testing infrastructure with GitHub Actions + ([57123a40](https://github.com/getsentry/sentry-go/commit/57123a409be55f61b1d5a6da93c176c55a399ad0), [#128](https://github.com/getsentry/sentry-go/pull/128), [#338](https://github.com/getsentry/sentry-go/pull/338), [#345](https://github.com/getsentry/sentry-go/pull/345), [#346](https://github.com/getsentry/sentry-go/pull/346), [#352](https://github.com/getsentry/sentry-go/pull/352), [#353](https://github.com/getsentry/sentry-go/pull/353), [#355](https://github.com/getsentry/sentry-go/pull/355)) + +_NOTE:_ +This version drops support for Go 1.13. The currently supported Go versions are the last 3 stable releases: 1.14, 1.15 and 1.16. +Users of the tracing functionality (`StartSpan`, etc) should upgrade to this version to benefit from separate rate limits for errors and transactions. +There are no breaking changes and upgrading should be a smooth experience for all users. + +## v0.10.0 + +- feat: Debug connection reuse (#323) +- fix: Send root span data as `Event.Extra` (#329) +- fix: Do not double sample transactions (#328) +- fix: Do not override trace context of transactions (#327) +- fix: Drain and close API response bodies (#322) +- ci: Run tests against Go tip (#319) +- ci: Move away from Travis in favor of GitHub Actions (#314) (#321) + +## v0.9.0 + +- feat: Initial tracing and performance monitoring support (#285) +- doc: Revamp sentryhttp documentation (#304) +- fix: Hub.PopScope never empties the scope stack (#300) +- ref: Report Event.Timestamp in local time (#299) +- ref: Report Breadcrumb.Timestamp in local time (#299) + +_NOTE:_ +This version introduces support for [Sentry's Performance Monitoring](https://docs.sentry.io/platforms/go/performance/). +The new tracing capabilities are beta, and we plan to expand them on future versions. Feedback is welcome, please open new issues on GitHub. +The `sentryhttp` package got better API docs, an [updated usage example](https://github.com/getsentry/sentry-go/tree/master/_examples/http) and support for creating automatic transactions as part of Performance Monitoring. + +## v0.8.0 + +- build: Bump required version of Iris (#296) +- fix: avoid unnecessary allocation in Client.processEvent (#293) +- doc: Remove deprecation of sentryhttp.HandleFunc (#284) +- ref: Update sentryhttp example (#283) +- doc: Improve documentation of sentryhttp package (#282) +- doc: Clarify SampleRate documentation (#279) +- fix: Remove RawStacktrace (#278) +- docs: Add example of custom HTTP transport +- ci: Test against go1.15, drop go1.12 support (#271) + +_NOTE:_ +This version comes with a few updates. Some examples and documentation have been +improved. We've bumped the supported version of the Iris framework to avoid +LGPL-licensed modules in the module dependency graph. +The `Exception.RawStacktrace` and `Thread.RawStacktrace` fields have been +removed to conform to Sentry's ingestion protocol, only `Exception.Stacktrace` +and `Thread.Stacktrace` should appear in user code. + +## v0.7.0 + +- feat: Include original error when event cannot be encoded as JSON (#258) +- feat: Use Hub from request context when available (#217, #259) +- feat: Extract stack frames from golang.org/x/xerrors (#262) +- feat: Make Environment Integration preserve existing context data (#261) +- feat: Recover and RecoverWithContext with arbitrary types (#268) +- feat: Report bad usage of CaptureMessage and CaptureEvent (#269) +- feat: Send debug logging to stderr by default (#266) +- feat: Several improvements to documentation (#223, #245, #250, #265) +- feat: Example of Recover followed by panic (#241, #247) +- feat: Add Transactions and Spans (to support OpenTelemetry Sentry Exporter) (#235, #243, #254) +- fix: Set either Frame.Filename or Frame.AbsPath (#233) +- fix: Clone requestBody to new Scope (#244) +- fix: Synchronize access and mutation of Hub.lastEventID (#264) +- fix: Avoid repeated syscalls in prepareEvent (#256) +- fix: Do not allocate new RNG for every event (#256) +- fix: Remove stale replace directive in go.mod (#255) +- fix(http): Deprecate HandleFunc, remove duplication (#260) + +_NOTE:_ +This version comes packed with several fixes and improvements and no breaking +changes. +Notably, there is a change in how the SDK reports file names in stack traces +that should resolve any ambiguity when looking at stack traces and using the +Suspect Commits feature. +We recommend all users to upgrade. + +## v0.6.1 + +- fix: Use NewEvent to init Event struct (#220) + +_NOTE:_ +A change introduced in v0.6.0 with the intent of avoiding allocations made a +pattern used in official examples break in certain circumstances (attempting +to write to a nil map). +This release reverts the change such that maps in the Event struct are always +allocated. + +## v0.6.0 + +- feat: Read module dependencies from runtime/debug (#199) +- feat: Support chained errors using Unwrap (#206) +- feat: Report chain of errors when available (#185) +- **[breaking]** fix: Accept http.RoundTripper to customize transport (#205) + Before the SDK accepted a concrete value of type `*http.Transport` in + `ClientOptions`, now it accepts any value implementing the `http.RoundTripper` + interface. Note that `*http.Transport` implements `http.RoundTripper`, so most + code bases will continue to work unchanged. + Users of custom transport gain the ability to pass in other implementations of + `http.RoundTripper` and may be able to simplify their code bases. +- fix: Do not panic when scope event processor drops event (#192) +- **[breaking]** fix: Use time.Time for timestamps (#191) + Users of sentry-go typically do not need to manipulate timestamps manually. + For those who do, the field type changed from `int64` to `time.Time`, which + should be more convenient to use. The recommended way to get the current time + is `time.Now().UTC()`. +- fix: Report usage error including stack trace (#189) +- feat: Add Exception.ThreadID field (#183) +- ci: Test against Go 1.14, drop 1.11 (#170) +- feat: Limit reading bytes from request bodies (#168) +- **[breaking]** fix: Rename fasthttp integration package sentryhttp => sentryfasthttp + The current recommendation is to use a named import, in which case existing + code should not require any change: + ```go + package main + + import ( + "fmt" + + "github.com/getsentry/sentry-go" + sentryfasthttp "github.com/getsentry/sentry-go/fasthttp" + "github.com/valyala/fasthttp" + ) + ``` + +_NOTE:_ +This version includes some new features and a few breaking changes, none of +which should pose troubles with upgrading. Most code bases should be able to +upgrade without any changes. + +## v0.5.1 + +- fix: Ignore err.Cause() when it is nil (#160) + +## v0.5.0 + +- fix: Synchronize access to HTTPTransport.disabledUntil (#158) +- docs: Update Flush documentation (#153) +- fix: HTTPTransport.Flush panic and data race (#140) + +_NOTE:_ +This version changes the implementation of the default transport, modifying the +behavior of `sentry.Flush`. The previous behavior was to wait until there were +no buffered events; new concurrent events kept `Flush` from returning. The new +behavior is to wait until the last event prior to the call to `Flush` has been +sent or the timeout; new concurrent events have no effect. The new behavior is +inline with the [Unified API +Guidelines](https://docs.sentry.io/development/sdk-dev/unified-api/). + +We have updated the documentation and examples to clarify that `Flush` is meant +to be called typically only once before program termination, to wait for +in-flight events to be sent to Sentry. Calling `Flush` after every event is not +recommended, as it introduces unnecessary latency to the surrounding function. +Please verify the usage of `sentry.Flush` in your code base. + +## v0.4.0 + +- fix(stacktrace): Correctly report package names (#127) +- fix(stacktrace): Do not rely on AbsPath of files (#123) +- build: Require github.com/ugorji/go@v1.1.7 (#110) +- fix: Correctly store last event id (#99) +- fix: Include request body in event payload (#94) +- build: Reset go.mod version to 1.11 (#109) +- fix: Eliminate data race in modules integration (#105) +- feat: Add support for path prefixes in the DSN (#102) +- feat: Add HTTPClient option (#86) +- feat: Extract correct type and value from top-most error (#85) +- feat: Check for broken pipe errors in Gin integration (#82) +- fix: Client.CaptureMessage accept nil EventModifier (#72) + +## v0.3.1 + +- feat: Send extra information exposed by the Go runtime (#76) +- fix: Handle new lines in module integration (#65) +- fix: Make sure that cache is locked when updating for contextifyFramesIntegration +- ref: Update Iris integration and example to version 12 +- misc: Remove indirect dependencies in order to move them to separate go.mod files + +## v0.3.0 + +- feat: Retry event marshaling without contextual data if the first pass fails +- fix: Include `url.Parse` error in `DsnParseError` +- fix: Make more `Scope` methods safe for concurrency +- fix: Synchronize concurrent access to `Hub.client` +- ref: Remove mutex from `Scope` exported API +- ref: Remove mutex from `Hub` exported API +- ref: Compile regexps for `filterFrames` only once +- ref: Change `SampleRate` type to `float64` +- doc: `Scope.Clear` not safe for concurrent use +- ci: Test sentry-go with `go1.13`, drop `go1.10` + +_NOTE:_ +This version removes some of the internal APIs that landed publicly (namely `Hub/Scope` mutex structs) and may require (but shouldn't) some changes to your code. +It's not done through major version update, as we are still in `0.x` stage. + +## v0.2.1 + +- fix: Run `Contextify` integration on `Threads` as well + +## v0.2.0 + +- feat: Add `SetTransaction()` method on the `Scope` +- feat: `fasthttp` framework support with `sentryfasthttp` package +- fix: Add `RWMutex` locks to internal `Hub` and `Scope` changes + +## v0.1.3 + +- feat: Move frames context reading into `contextifyFramesIntegration` (#28) + +_NOTE:_ +In case of any performance issues due to source contexts IO, you can let us know and turn off the integration in the meantime with: + +```go +sentry.Init(sentry.ClientOptions{ + Integrations: func(integrations []sentry.Integration) []sentry.Integration { + var filteredIntegrations []sentry.Integration + for _, integration := range integrations { + if integration.Name() == "ContextifyFrames" { + continue + } + filteredIntegrations = append(filteredIntegrations, integration) + } + return filteredIntegrations + }, +}) +``` + +## v0.1.2 + +- feat: Better source code location resolution and more useful inapp frames (#26) +- feat: Use `noopTransport` when no `Dsn` provided (#27) +- ref: Allow empty `Dsn` instead of returning an error (#22) +- fix: Use `NewScope` instead of literal struct inside a `scope.Clear` call (#24) +- fix: Add to `WaitGroup` before the request is put inside a buffer (#25) + +## v0.1.1 + +- fix: Check for initialized `Client` in `AddBreadcrumbs` (#20) +- build: Bump version when releasing with Craft (#19) + +## v0.1.0 + +- First stable release! \o/ + +## v0.0.1-beta.5 + +- feat: **[breaking]** Add `NewHTTPTransport` and `NewHTTPSyncTransport` which accepts all transport options +- feat: New `HTTPSyncTransport` that blocks after each call +- feat: New `Echo` integration +- ref: **[breaking]** Remove `BufferSize` option from `ClientOptions` and move it to `HTTPTransport` instead +- ref: Export default `HTTPTransport` +- ref: Export `net/http` integration handler +- ref: Set `Request` instantly in the package handlers, not in `recoverWithSentry` so it can be accessed later on +- ci: Add craft config + +## v0.0.1-beta.4 + +- feat: `IgnoreErrors` client option and corresponding integration +- ref: Reworked `net/http` integration, wrote better example and complete readme +- ref: Reworked `Gin` integration, wrote better example and complete readme +- ref: Reworked `Iris` integration, wrote better example and complete readme +- ref: Reworked `Negroni` integration, wrote better example and complete readme +- ref: Reworked `Martini` integration, wrote better example and complete readme +- ref: Remove `Handle()` from frameworks handlers and return it directly from New + +## v0.0.1-beta.3 + +- feat: `Iris` framework support with `sentryiris` package +- feat: `Gin` framework support with `sentrygin` package +- feat: `Martini` framework support with `sentrymartini` package +- feat: `Negroni` framework support with `sentrynegroni` package +- feat: Add `Hub.Clone()` for easier frameworks integration +- feat: Return `EventID` from `Recovery` methods +- feat: Add `NewScope` and `NewEvent` functions and use them in the whole codebase +- feat: Add `AddEventProcessor` to the `Client` +- fix: Operate on requests body copy instead of the original +- ref: Try to read source files from the root directory, based on the filename as well, to make it work on AWS Lambda +- ref: Remove `gocertifi` dependence and document how to provide your own certificates +- ref: **[breaking]** Remove `Decorate` and `DecorateFunc` methods in favor of `sentryhttp` package +- ref: **[breaking]** Allow for integrations to live on the client, by passing client instance in `SetupOnce` method +- ref: **[breaking]** Remove `GetIntegration` from the `Hub` +- ref: **[breaking]** Remove `GlobalEventProcessors` getter from the public API + +## v0.0.1-beta.2 + +- feat: Add `AttachStacktrace` client option to include stacktrace for messages +- feat: Add `BufferSize` client option to configure transport buffer size +- feat: Add `SetRequest` method on a `Scope` to control `Request` context data +- feat: Add `FromHTTPRequest` for `Request` type for easier extraction +- ref: Extract `Request` information more accurately +- fix: Attach `ServerName`, `Release`, `Dist`, `Environment` options to the event +- fix: Don't log events dropped due to full transport buffer as sent +- fix: Don't panic and create an appropriate event when called `CaptureException` or `Recover` with `nil` value + +## v0.0.1-beta + +- Initial release diff --git a/vendor/github.com/getsentry/sentry-go/CONTRIBUTING.md b/vendor/github.com/getsentry/sentry-go/CONTRIBUTING.md new file mode 100644 index 0000000..9808f18 --- /dev/null +++ b/vendor/github.com/getsentry/sentry-go/CONTRIBUTING.md @@ -0,0 +1,98 @@ +# Contributing to sentry-go + +Hey, thank you if you're reading this, we welcome your contribution! + +## Sending a Pull Request + +Please help us save time when reviewing your PR by following this simple +process: + +1. Is your PR a simple typo fix? Read no further, **click that green "Create + pull request" button**! + +2. For more complex PRs that involve behavior changes or new APIs, please + consider [opening an **issue**][new-issue] describing the problem you're + trying to solve if there's not one already. + + A PR is often one specific solution to a problem and sometimes talking about + the problem unfolds new possible solutions. Remember we will be responsible + for maintaining the changes later. + +3. Fixing a bug and changing a behavior? Please add automated tests to prevent + future regression. + +4. Practice writing good commit messages. We have [commit + guidelines][commit-guide]. + +5. We have [guidelines for PR submitters][pr-guide]. A short summary: + + - Good PR descriptions are very helpful and most of the time they include + **why** something is done and why done in this particular way. Also list + other possible solutions that were considered and discarded. + - Be your own first reviewer. Make sure your code compiles and passes the + existing tests. + +[new-issue]: https://github.com/getsentry/sentry-go/issues/new/choose +[commit-guide]: https://develop.sentry.dev/code-review/#commit-guidelines +[pr-guide]: https://develop.sentry.dev/code-review/#guidelines-for-submitters + +Please also read through our [SDK Development docs](https://develop.sentry.dev/sdk/). +It contains information about SDK features, expected payloads and best practices for +contributing to Sentry SDKs. + +## Community + +The public-facing channels for support and development of Sentry SDKs can be found on [Discord](https://discord.gg/Ww9hbqr). + +## Testing + +```console +$ go test +``` + +### Watch mode + +Use: https://github.com/cespare/reflex + +```console +$ reflex -g '*.go' -d "none" -- sh -c 'printf "\n"; go test' +``` + +### With data race detection + +```console +$ go test -race +``` + +### Coverage + +```console +$ go test -race -coverprofile=coverage.txt -covermode=atomic && go tool cover -html coverage.txt +``` + +## Linting + +Lint with [`golangci-lint`](https://github.com/golangci/golangci-lint): + +```console +$ golangci-lint run +``` + +## Release + +1. Update `CHANGELOG.md` with new version in `vX.X.X` format title and list of changes. + + The command below can be used to get a list of changes since the last tag, with the format used in `CHANGELOG.md`: + + ```console + $ git log --no-merges --format=%s $(git describe --abbrev=0).. | sed 's/^/- /' + ``` + +2. Commit with `misc: vX.X.X changelog` commit message and push to `master`. + +3. Let [`craft`](https://github.com/getsentry/craft) do the rest: + + ```console + $ craft prepare X.X.X + $ craft publish X.X.X + ``` diff --git a/vendor/github.com/getsentry/sentry-go/LICENSE b/vendor/github.com/getsentry/sentry-go/LICENSE new file mode 100644 index 0000000..b1b358e --- /dev/null +++ b/vendor/github.com/getsentry/sentry-go/LICENSE @@ -0,0 +1,21 @@ +MIT License + +Copyright (c) 2019 Functional Software, Inc. dba Sentry + +Permission is hereby granted, free of charge, to any person obtaining a copy +of this software and associated documentation files (the "Software"), to deal +in the Software without restriction, including without limitation the rights +to use, copy, modify, merge, publish, distribute, sublicense, and/or sell +copies of the Software, and to permit persons to whom the Software is +furnished to do so, subject to the following conditions: + +The above copyright notice and this permission notice shall be included in all +copies or substantial portions of the Software. + +THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR +IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, +FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE +AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER +LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, +OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE +SOFTWARE. diff --git a/vendor/github.com/getsentry/sentry-go/MIGRATION.md b/vendor/github.com/getsentry/sentry-go/MIGRATION.md new file mode 100644 index 0000000..2c30d62 --- /dev/null +++ b/vendor/github.com/getsentry/sentry-go/MIGRATION.md @@ -0,0 +1,3 @@ +# `raven-go` to `sentry-go` Migration Guide + +A [`raven-go` to `sentry-go` migration guide](https://docs.sentry.io/platforms/go/migration/) is available at the official Sentry documentation site. diff --git a/vendor/github.com/getsentry/sentry-go/Makefile b/vendor/github.com/getsentry/sentry-go/Makefile new file mode 100644 index 0000000..9ef0e9c --- /dev/null +++ b/vendor/github.com/getsentry/sentry-go/Makefile @@ -0,0 +1,93 @@ +.DEFAULT_GOAL := help + +MKFILE_PATH := $(abspath $(lastword $(MAKEFILE_LIST))) +MKFILE_DIR := $(dir $(MKFILE_PATH)) +ALL_GO_MOD_DIRS := $(shell find . -type f -name 'go.mod' -exec dirname {} \; | sort) +GO = go +TIMEOUT = 300 + +# Parse Makefile and display the help +help: ## Show help + @grep -E '^[a-zA-Z_-]+:.*?## .*$$' $(MAKEFILE_LIST) | sort | awk 'BEGIN {FS = ":.*?## "}; {printf "\033[36m%-30s\033[0m %s\n", $$1, $$2}' +.PHONY: help + +build: ## Build everything + for dir in $(ALL_GO_MOD_DIRS); do \ + cd "$${dir}"; \ + echo ">>> Running 'go build' for module: $${dir}"; \ + go build ./...; \ + done; +.PHONY: build + +### Tests (inspired by https://github.com/open-telemetry/opentelemetry-go/blob/main/Makefile) +TEST_TARGETS := test-short test-verbose test-race +test-race: ARGS=-race +test-short: ARGS=-short +test-verbose: ARGS=-v -race +$(TEST_TARGETS): test +test: $(ALL_GO_MOD_DIRS:%=test/%) ## Run tests +test/%: DIR=$* +test/%: + @echo ">>> Running tests for module: $(DIR)" + @# We use '-count=1' to disable test caching. + (cd $(DIR) && $(GO) test -count=1 -timeout $(TIMEOUT)s $(ARGS) ./...) +.PHONY: $(TEST_TARGETS) test + +# Coverage +COVERAGE_MODE = atomic +COVERAGE_PROFILE = coverage.out +COVERAGE_REPORT_DIR = .coverage +COVERAGE_REPORT_DIR_ABS = "$(MKFILE_DIR)/$(COVERAGE_REPORT_DIR)" +$(COVERAGE_REPORT_DIR): + mkdir -p $(COVERAGE_REPORT_DIR) +clean-report-dir: $(COVERAGE_REPORT_DIR) + test $(COVERAGE_REPORT_DIR) && rm -f $(COVERAGE_REPORT_DIR)/* +test-coverage: $(COVERAGE_REPORT_DIR) clean-report-dir ## Test with coverage enabled + set -e ; \ + for dir in $(ALL_GO_MOD_DIRS); do \ + echo ">>> Running tests with coverage for module: $${dir}"; \ + DIR_ABS=$$(python -c 'import os, sys; print(os.path.realpath(sys.argv[1]))' $${dir}) ; \ + REPORT_NAME=$$(basename $${DIR_ABS}); \ + (cd "$${dir}" && \ + $(GO) test -count=1 -timeout $(TIMEOUT)s -coverpkg=./... -covermode=$(COVERAGE_MODE) -coverprofile="$(COVERAGE_PROFILE)" ./... && \ + cp $(COVERAGE_PROFILE) "$(COVERAGE_REPORT_DIR_ABS)/$${REPORT_NAME}_$(COVERAGE_PROFILE)" && \ + $(GO) tool cover -html=$(COVERAGE_PROFILE) -o coverage.html); \ + done; +.PHONY: test-coverage clean-report-dir +test-race-coverage: $(COVERAGE_REPORT_DIR) clean-report-dir ## Run tests with race detection and coverage + set -e ; \ + for dir in $(ALL_GO_MOD_DIRS); do \ + echo ">>> Running tests with race detection and coverage for module: $${dir}"; \ + DIR_ABS=$$(python -c 'import os, sys; print(os.path.realpath(sys.argv[1]))' $${dir}) ; \ + REPORT_NAME=$$(basename $${DIR_ABS}); \ + (cd "$${dir}" && \ + $(GO) test -count=1 -timeout $(TIMEOUT)s -race -coverpkg=./... -covermode=$(COVERAGE_MODE) -coverprofile="$(COVERAGE_PROFILE)" ./... && \ + cp $(COVERAGE_PROFILE) "$(COVERAGE_REPORT_DIR_ABS)/$${REPORT_NAME}_$(COVERAGE_PROFILE)" && \ + $(GO) tool cover -html=$(COVERAGE_PROFILE) -o coverage.html); \ + done; +.PHONY: test-race-coverage +mod-tidy: ## Check go.mod tidiness + set -e ; \ + for dir in $(ALL_GO_MOD_DIRS); do \ + echo ">>> Running 'go mod tidy' for module: $${dir}"; \ + (cd "$${dir}" && go mod tidy -go=1.22 -compat=1.22); \ + done; \ + git diff --exit-code; +.PHONY: mod-tidy + +vet: ## Run "go vet" + set -e ; \ + for dir in $(ALL_GO_MOD_DIRS); do \ + echo ">>> Running 'go vet' for module: $${dir}"; \ + (cd "$${dir}" && go vet ./...); \ + done; +.PHONY: vet + + +lint: ## Lint (using "golangci-lint") + golangci-lint run +.PHONY: lint + +fmt: ## Format all Go files + gofmt -l -w -s . +.PHONY: fmt diff --git a/vendor/github.com/getsentry/sentry-go/README.md b/vendor/github.com/getsentry/sentry-go/README.md new file mode 100644 index 0000000..59a989d --- /dev/null +++ b/vendor/github.com/getsentry/sentry-go/README.md @@ -0,0 +1,106 @@ +
+
+ 
+
](https://gophers.slack.com/archives/CQ7T0T1FW)
+
+## Quick Start
+
+```
+go get github.com/go-co-op/gocron/v2
+```
+
+```golang
+package main
+
+import (
+ "fmt"
+ "time"
+
+ "github.com/go-co-op/gocron/v2"
+)
+
+func main() {
+ // create a scheduler
+ s, err := gocron.NewScheduler()
+ if err != nil {
+ // handle error
+ }
+
+ // add a job to the scheduler
+ j, err := s.NewJob(
+ gocron.DurationJob(
+ 10*time.Second,
+ ),
+ gocron.NewTask(
+ func(a string, b int) {
+ // do things
+ },
+ "hello",
+ 1,
+ ),
+ )
+ if err != nil {
+ // handle error
+ }
+ // each job has a unique id
+ fmt.Println(j.ID())
+
+ // start the scheduler
+ s.Start()
+
+ // block until you are ready to shut down
+ select {
+ case <-time.After(time.Minute):
+ }
+
+ // when you're done, shut it down
+ err = s.Shutdown()
+ if err != nil {
+ // handle error
+ }
+}
+```
+
+## Examples
+
+- [Go doc examples](https://pkg.go.dev/github.com/go-co-op/gocron/v2#pkg-examples)
+- [Examples directory](examples)
+
+## Concepts
+
+- **Job**: The job encapsulates a "task", which is made up of a go function and any function parameters. The Job then
+ provides the scheduler with the time the job should next be scheduled to run.
+- **Scheduler**: The scheduler keeps track of all the jobs and sends each job to the executor when
+ it is ready to be run.
+- **Executor**: The executor calls the job's task and manages the complexities of different job
+ execution timing requirements (e.g. singletons that shouldn't overrun each other, limiting the max number of jobs running)
+
+
+## Features
+
+### Job types
+Jobs can be run at various intervals.
+- [**Duration**](https://pkg.go.dev/github.com/go-co-op/gocron/v2#DurationJob):
+Jobs can be run at a fixed `time.Duration`.
+- [**Random duration**](https://pkg.go.dev/github.com/go-co-op/gocron/v2#DurationRandomJob):
+Jobs can be run at a random `time.Duration` between a min and max.
+- [**Cron**](https://pkg.go.dev/github.com/go-co-op/gocron/v2#CronJob):
+Jobs can be run using a crontab.
+- [**Daily**](https://pkg.go.dev/github.com/go-co-op/gocron/v2#DailyJob):
+Jobs can be run every x days at specific times.
+- [**Weekly**](https://pkg.go.dev/github.com/go-co-op/gocron/v2#WeeklyJob):
+Jobs can be run every x weeks on specific days of the week and at specific times.
+- [**Monthly**](https://pkg.go.dev/github.com/go-co-op/gocron/v2#MonthlyJob):
+Jobs can be run every x months on specific days of the month and at specific times.
+- [**One time**](https://pkg.go.dev/github.com/go-co-op/gocron/v2#OneTimeJob):
+Jobs can be run at specific time(s) (either once or many times).
+
+### Concurrency Limits
+Jobs can be limited individually or across the entire scheduler.
+- [**Per job limiting with singleton mode**](https://pkg.go.dev/github.com/go-co-op/gocron/v2#WithSingletonMode):
+Jobs can be limited to a single concurrent execution that either reschedules (skips overlapping executions)
+or queues (waits for the previous execution to finish).
+- [**Per scheduler limiting with limit mode**](https://pkg.go.dev/github.com/go-co-op/gocron/v2#WithLimitConcurrentJobs):
+Jobs can be limited to a certain number of concurrent executions across the entire scheduler
+using either reschedule (skip when the limit is met) or queue (jobs are added to a queue to
+wait for the limit to be available).
+- **Note:** A scheduler limit and a job limit can both be enabled.
+
+### Distributed instances of gocron
+Multiple instances of gocron can be run.
+- [**Elector**](https://pkg.go.dev/github.com/go-co-op/gocron/v2#WithDistributedElector):
+An elector can be used to elect a single instance of gocron to run as the primary with the
+other instances checking to see if a new leader needs to be elected.
+ - Implementations: [go-co-op electors](https://github.com/go-co-op?q=-elector&type=all&language=&sort=)
+ (don't see what you need? request on slack to get a repo created to contribute it!)
+- [**Locker**](https://pkg.go.dev/github.com/go-co-op/gocron/v2#WithDistributedLocker):
+A locker can be used to lock each run of a job to a single instance of gocron.
+Locker can be at job or scheduler, if it is defined both at job and scheduler then locker of job will take precedence.
+ - See Notes in the doc for [Locker](https://pkg.go.dev/github.com/go-co-op/gocron/v2#Locker) for
+ details and limitations of the locker design.
+ - Implementations: [go-co-op lockers](https://github.com/go-co-op?q=-lock&type=all&language=&sort=)
+ (don't see what you need? request on slack to get a repo created to contribute it!)
+
+### Events
+Job events can trigger actions.
+- [**Listeners**](https://pkg.go.dev/github.com/go-co-op/gocron/v2#WithEventListeners):
+Can be added to a job, with [event listeners](https://pkg.go.dev/github.com/go-co-op/gocron/v2#EventListener),
+or all jobs across the
+[scheduler](https://pkg.go.dev/github.com/go-co-op/gocron/v2#WithGlobalJobOptions)
+to listen for job events and trigger actions.
+
+### Options
+Many job and scheduler options are available.
+- [**Job options**](https://pkg.go.dev/github.com/go-co-op/gocron/v2#JobOption):
+Job options can be set when creating a job using `NewJob`.
+- [**Global job options**](https://pkg.go.dev/github.com/go-co-op/gocron/v2#WithGlobalJobOptions):
+Global job options can be set when creating a scheduler using `NewScheduler`
+and the `WithGlobalJobOptions` option.
+- [**Scheduler options**](https://pkg.go.dev/github.com/go-co-op/gocron/v2#SchedulerOption):
+Scheduler options can be set when creating a scheduler using `NewScheduler`.
+
+### Logging
+Logs can be enabled.
+- [Logger](https://pkg.go.dev/github.com/go-co-op/gocron/v2#Logger):
+The Logger interface can be implemented with your desired logging library.
+The provided NewLogger uses the standard library's log package.
+
+### Metrics
+Metrics may be collected from the execution of each job.
+- [**Monitor**](https://pkg.go.dev/github.com/go-co-op/gocron/v2#Monitor):
+- [**MonitorStatus**](https://pkg.go.dev/github.com/go-co-op/gocron/v2#MonitorStatus) (includes status and error (if any) of the Job)
+A monitor can be used to collect metrics for each job from a scheduler.
+ - Implementations: [go-co-op monitors](https://github.com/go-co-op?q=-monitor&type=all&language=&sort=)
+ (don't see what you need? request on slack to get a repo created to contribute it!)
+
+### Testing
+The gocron library is set up to enable testing.
+- Mocks are provided in [the mock package](mocks) using [gomock](https://github.com/uber-go/mock).
+- Time can be mocked by passing in a [FakeClock](https://pkg.go.dev/github.com/jonboulle/clockwork#FakeClock)
+to [WithClock](https://pkg.go.dev/github.com/go-co-op/gocron/v2#WithClock) -
+see the [example on WithClock](https://pkg.go.dev/github.com/go-co-op/gocron/v2#example-WithClock).
+
+## Supporters
+
+We appreciate the support for free and open source software!
+
+This project is supported by:
+
+[JetBrains](https://www.jetbrains.com/?from=gocron)
+
+
+ 
+ 
+ ](https://gophers.slack.com/archives/CQ7T0T1FW)
+
+We will do our best to address any vulnerabilities in an expeditious manner.
diff --git a/vendor/github.com/go-co-op/gocron/v2/distributed.go b/vendor/github.com/go-co-op/gocron/v2/distributed.go
new file mode 100644
index 0000000..98e906e
--- /dev/null
+++ b/vendor/github.com/go-co-op/gocron/v2/distributed.go
@@ -0,0 +1,45 @@
+//go:generate mockgen -destination=mocks/distributed.go -package=gocronmocks . Elector,Locker,Lock
+package gocron
+
+import (
+ "context"
+)
+
+// Elector determines the leader from instances asking to be the leader. Only
+// the leader runs jobs. If the leader goes down, a new leader will be elected.
+type Elector interface {
+ // IsLeader should return nil if the job should be scheduled by the instance
+ // making the request and an error if the job should not be scheduled.
+ IsLeader(context.Context) error
+}
+
+// Locker represents the required interface to lock jobs when running multiple schedulers.
+// The lock is held for the duration of the job's run, and it is expected that the
+// locker implementation handles time splay between schedulers.
+// The lock key passed is the job's name - which, if not set, defaults to the
+// go function's name, e.g. "pkg.myJob" for func myJob() {} in pkg
+//
+// Notes: The locker and scheduler do not handle synchronization of run times across
+// schedulers.
+//
+// 1. If you are using duration based jobs (DurationJob), you can utilize the JobOption
+// WithStartAt to set a start time for the job to the nearest time rounded to your
+// duration. For example, if you have a job that runs every 5 minutes, you can set
+// the start time to the nearest 5 minute e.g. 12:05, 12:10.
+//
+// 2. For all jobs, the implementation is still vulnerable to clockskew between scheduler
+// instances. This may result in a single scheduler instance running the majority of the
+// jobs.
+//
+// For distributed jobs, consider utilizing the Elector option if these notes are not acceptable
+// to your use case.
+type Locker interface {
+ // Lock if an error is returned by lock, the job will not be scheduled.
+ Lock(ctx context.Context, key string) (Lock, error)
+}
+
+// Lock represents an obtained lock. The lock is released after the execution of the job
+// by the scheduler.
+type Lock interface {
+ Unlock(ctx context.Context) error
+}
diff --git a/vendor/github.com/go-co-op/gocron/v2/errors.go b/vendor/github.com/go-co-op/gocron/v2/errors.go
new file mode 100644
index 0000000..94c1f87
--- /dev/null
+++ b/vendor/github.com/go-co-op/gocron/v2/errors.go
@@ -0,0 +1,67 @@
+package gocron
+
+import (
+ "errors"
+)
+
+// Public error definitions
+var (
+ ErrCronJobInvalid = errors.New("gocron: CronJob: invalid crontab")
+ ErrCronJobParse = errors.New("gocron: CronJob: crontab parse failure")
+ ErrDailyJobAtTimeNil = errors.New("gocron: DailyJob: atTime within atTimes must not be nil")
+ ErrDailyJobAtTimesNil = errors.New("gocron: DailyJob: atTimes must not be nil")
+ ErrDailyJobHours = errors.New("gocron: DailyJob: atTimes hours must be between 0 and 23 inclusive")
+ ErrDailyJobZeroInterval = errors.New("gocron: DailyJob: interval must be greater than 0")
+ ErrDailyJobMinutesSeconds = errors.New("gocron: DailyJob: atTimes minutes and seconds must be between 0 and 59 inclusive")
+ ErrDurationJobIntervalZero = errors.New("gocron: DurationJob: time interval is 0")
+ ErrDurationRandomJobMinMax = errors.New("gocron: DurationRandomJob: minimum duration must be less than maximum duration")
+ ErrEventListenerFuncNil = errors.New("gocron: eventListenerFunc must not be nil")
+ ErrJobNotFound = errors.New("gocron: job not found")
+ ErrJobRunNowFailed = errors.New("gocron: Job: RunNow: scheduler unreachable")
+ ErrMonthlyJobDays = errors.New("gocron: MonthlyJob: daysOfTheMonth must be between 31 and -31 inclusive, and not 0")
+ ErrMonthlyJobAtTimeNil = errors.New("gocron: MonthlyJob: atTime within atTimes must not be nil")
+ ErrMonthlyJobAtTimesNil = errors.New("gocron: MonthlyJob: atTimes must not be nil")
+ ErrMonthlyJobDaysNil = errors.New("gocron: MonthlyJob: daysOfTheMonth must not be nil")
+ ErrMonthlyJobHours = errors.New("gocron: MonthlyJob: atTimes hours must be between 0 and 23 inclusive")
+ ErrMonthlyJobZeroInterval = errors.New("gocron: MonthlyJob: interval must be greater than 0")
+ ErrMonthlyJobMinutesSeconds = errors.New("gocron: MonthlyJob: atTimes minutes and seconds must be between 0 and 59 inclusive")
+ ErrNewJobTaskNil = errors.New("gocron: NewJob: Task must not be nil")
+ ErrNewJobTaskNotFunc = errors.New("gocron: NewJob: Task.Function must be of kind reflect.Func")
+ ErrNewJobWrongNumberOfParameters = errors.New("gocron: NewJob: Number of provided parameters does not match expected")
+ ErrNewJobWrongTypeOfParameters = errors.New("gocron: NewJob: Type of provided parameters does not match expected")
+ ErrOneTimeJobStartDateTimePast = errors.New("gocron: OneTimeJob: start must not be in the past")
+ ErrStopExecutorTimedOut = errors.New("gocron: timed out waiting for executor to stop")
+ ErrStopJobsTimedOut = errors.New("gocron: timed out waiting for jobs to finish")
+ ErrStopSchedulerTimedOut = errors.New("gocron: timed out waiting for scheduler to stop")
+ ErrWeeklyJobAtTimeNil = errors.New("gocron: WeeklyJob: atTime within atTimes must not be nil")
+ ErrWeeklyJobAtTimesNil = errors.New("gocron: WeeklyJob: atTimes must not be nil")
+ ErrWeeklyJobDaysOfTheWeekNil = errors.New("gocron: WeeklyJob: daysOfTheWeek must not be nil")
+ ErrWeeklyJobHours = errors.New("gocron: WeeklyJob: atTimes hours must be between 0 and 23 inclusive")
+ ErrWeeklyJobZeroInterval = errors.New("gocron: WeeklyJob: interval must be greater than 0")
+ ErrWeeklyJobMinutesSeconds = errors.New("gocron: WeeklyJob: atTimes minutes and seconds must be between 0 and 59 inclusive")
+ ErrPanicRecovered = errors.New("gocron: panic recovered")
+ ErrWithClockNil = errors.New("gocron: WithClock: clock must not be nil")
+ ErrWithContextNil = errors.New("gocron: WithContext: context must not be nil")
+ ErrWithDistributedElectorNil = errors.New("gocron: WithDistributedElector: elector must not be nil")
+ ErrWithDistributedLockerNil = errors.New("gocron: WithDistributedLocker: locker must not be nil")
+ ErrWithDistributedJobLockerNil = errors.New("gocron: WithDistributedJobLocker: locker must not be nil")
+ ErrWithIdentifierNil = errors.New("gocron: WithIdentifier: identifier must not be nil")
+ ErrWithLimitConcurrentJobsZero = errors.New("gocron: WithLimitConcurrentJobs: limit must be greater than 0")
+ ErrWithLocationNil = errors.New("gocron: WithLocation: location must not be nil")
+ ErrWithLoggerNil = errors.New("gocron: WithLogger: logger must not be nil")
+ ErrWithMonitorNil = errors.New("gocron: WithMonitor: monitor must not be nil")
+ ErrWithNameEmpty = errors.New("gocron: WithName: name must not be empty")
+ ErrWithStartDateTimePast = errors.New("gocron: WithStartDateTime: start must not be in the past")
+ ErrWithStopDateTimePast = errors.New("gocron: WithStopDateTime: end must not be in the past")
+ ErrStartTimeLaterThanEndTime = errors.New("gocron: WithStartDateTime: start must not be later than end")
+ ErrStopTimeEarlierThanStartTime = errors.New("gocron: WithStopDateTime: end must not be earlier than start")
+ ErrWithStopTimeoutZeroOrNegative = errors.New("gocron: WithStopTimeout: timeout must be greater than 0")
+)
+
+// internal errors
+var (
+ errAtTimeNil = errors.New("errAtTimeNil")
+ errAtTimesNil = errors.New("errAtTimesNil")
+ errAtTimeHours = errors.New("errAtTimeHours")
+ errAtTimeMinSec = errors.New("errAtTimeMinSec")
+)
diff --git a/vendor/github.com/go-co-op/gocron/v2/executor.go b/vendor/github.com/go-co-op/gocron/v2/executor.go
new file mode 100644
index 0000000..594d5ea
--- /dev/null
+++ b/vendor/github.com/go-co-op/gocron/v2/executor.go
@@ -0,0 +1,562 @@
+package gocron
+
+import (
+ "context"
+ "fmt"
+ "strconv"
+ "sync"
+ "time"
+
+ "github.com/jonboulle/clockwork"
+
+ "github.com/google/uuid"
+)
+
+type executor struct {
+ // context used for shutting down
+ ctx context.Context
+ // cancel used by the executor to signal a stop of it's functions
+ cancel context.CancelFunc
+ // clock used for regular time or mocking time
+ clock clockwork.Clock
+ // the executor's logger
+ logger Logger
+
+ // receives jobs scheduled to execute
+ jobsIn chan jobIn
+ // sends out jobs for rescheduling
+ jobsOutForRescheduling chan uuid.UUID
+ // sends out jobs once completed
+ jobsOutCompleted chan uuid.UUID
+ // used to request jobs from the scheduler
+ jobOutRequest chan *jobOutRequest
+
+ // sends out job needs to update the next runs
+ jobUpdateNextRuns chan uuid.UUID
+
+ // used by the executor to receive a stop signal from the scheduler
+ stopCh chan struct{}
+ // ensure that stop runs before the next call to start and only runs once
+ stopOnce *sync.Once
+ // the timeout value when stopping
+ stopTimeout time.Duration
+ // used to signal that the executor has completed shutdown
+ done chan error
+
+ // runners for any singleton type jobs
+ // map[uuid.UUID]singletonRunner
+ singletonRunners *sync.Map
+ // config for limit mode
+ limitMode *limitModeConfig
+ // the elector when running distributed instances
+ elector Elector
+ // the locker when running distributed instances
+ locker Locker
+ // monitor for reporting metrics
+ monitor Monitor
+ // monitorStatus for reporting metrics
+ monitorStatus MonitorStatus
+}
+
+type jobIn struct {
+ id uuid.UUID
+ shouldSendOut bool
+}
+
+type singletonRunner struct {
+ in chan jobIn
+ rescheduleLimiter chan struct{}
+}
+
+type limitModeConfig struct {
+ started bool
+ mode LimitMode
+ limit uint
+ rescheduleLimiter chan struct{}
+ in chan jobIn
+ // singletonJobs is used to track singleton jobs that are running
+ // in the limit mode runner. This is used to prevent the same job
+ // from running multiple times across limit mode runners when both
+ // a limit mode and singleton mode are enabled.
+ singletonJobs map[uuid.UUID]struct{}
+ singletonJobsMu sync.Mutex
+}
+
+func (e *executor) start() {
+ e.logger.Debug("gocron: executor started")
+
+ // creating the executor's context here as the executor
+ // is the only goroutine that should access this context
+ // any other uses within the executor should create a context
+ // using the executor context as parent.
+ e.ctx, e.cancel = context.WithCancel(context.Background())
+ e.stopOnce = &sync.Once{}
+
+ // the standardJobsWg tracks
+ standardJobsWg := &waitGroupWithMutex{}
+
+ singletonJobsWg := &waitGroupWithMutex{}
+
+ limitModeJobsWg := &waitGroupWithMutex{}
+
+ // create a fresh map for tracking singleton runners
+ e.singletonRunners = &sync.Map{}
+
+ // start the for leap that is the executor
+ // selecting on channels for work to do
+ for {
+ select {
+ // job ids in are sent from 1 of 2 places:
+ // 1. the scheduler sends directly when jobs
+ // are run immediately.
+ // 2. sent from time.AfterFuncs in which job schedules
+ // are spun up by the scheduler
+ case jIn := <-e.jobsIn:
+ select {
+ case <-e.stopCh:
+ e.stop(standardJobsWg, singletonJobsWg, limitModeJobsWg)
+ return
+ default:
+ }
+ // this context is used to handle cancellation of the executor
+ // on requests for a job to the scheduler via requestJobCtx
+ ctx, cancel := context.WithCancel(e.ctx)
+
+ if e.limitMode != nil && !e.limitMode.started {
+ // check if we are already running the limit mode runners
+ // if not, spin up the required number i.e. limit!
+ e.limitMode.started = true
+ for i := e.limitMode.limit; i > 0; i-- {
+ limitModeJobsWg.Add(1)
+ go e.limitModeRunner("limitMode-"+strconv.Itoa(int(i)), e.limitMode.in, limitModeJobsWg, e.limitMode.mode, e.limitMode.rescheduleLimiter)
+ }
+ }
+
+ // spin off into a goroutine to unblock the executor and
+ // allow for processing for more work
+ go func(executorCtx context.Context) {
+ // make sure to cancel the above context per the docs
+ // // Canceling this context releases resources associated with it, so code should
+ // // call cancel as soon as the operations running in this Context complete.
+ defer cancel()
+
+ // check for limit mode - this spins up a separate runner which handles
+ // limiting the total number of concurrently running jobs
+ if e.limitMode != nil {
+ if e.limitMode.mode == LimitModeReschedule {
+ select {
+ // rescheduleLimiter is a channel the size of the limit
+ // this blocks publishing to the channel and keeps
+ // the executor from building up a waiting queue
+ // and forces rescheduling
+ case e.limitMode.rescheduleLimiter <- struct{}{}:
+ e.limitMode.in <- jIn
+ default:
+ // all runners are busy, reschedule the work for later
+ // which means we just skip it here and do nothing
+ // TODO when metrics are added, this should increment a rescheduled metric
+ e.sendOutForRescheduling(&jIn)
+ }
+ } else {
+ // since we're not using LimitModeReschedule, but instead using LimitModeWait
+ // we do want to queue up the work to the limit mode runners and allow them
+ // to work through the channel backlog. A hard limit of 1000 is in place
+ // at which point this call would block.
+ // TODO when metrics are added, this should increment a wait metric
+ e.sendOutForRescheduling(&jIn)
+ e.limitMode.in <- jIn
+ }
+ } else {
+ // no limit mode, so we're either running a regular job or
+ // a job with a singleton mode
+ //
+ // get the job, so we can figure out what kind it is and how
+ // to execute it
+ j := requestJobCtx(ctx, jIn.id, e.jobOutRequest)
+ if j == nil {
+ // safety check as it'd be strange bug if this occurred
+ return
+ }
+ if j.singletonMode {
+ // for singleton mode, get the existing runner for the job
+ // or spin up a new one
+ runner := &singletonRunner{}
+ runnerSrc, ok := e.singletonRunners.Load(jIn.id)
+ if !ok {
+ runner.in = make(chan jobIn, 1000)
+ if j.singletonLimitMode == LimitModeReschedule {
+ runner.rescheduleLimiter = make(chan struct{}, 1)
+ }
+ e.singletonRunners.Store(jIn.id, runner)
+ singletonJobsWg.Add(1)
+ go e.singletonModeRunner("singleton-"+jIn.id.String(), runner.in, singletonJobsWg, j.singletonLimitMode, runner.rescheduleLimiter)
+ } else {
+ runner = runnerSrc.(*singletonRunner)
+ }
+
+ if j.singletonLimitMode == LimitModeReschedule {
+ // reschedule mode uses the limiter channel to check
+ // for a running job and reschedules if the channel is full.
+ select {
+ case runner.rescheduleLimiter <- struct{}{}:
+ runner.in <- jIn
+ e.sendOutForRescheduling(&jIn)
+ default:
+ // runner is busy, reschedule the work for later
+ // which means we just skip it here and do nothing
+ e.incrementJobCounter(*j, SingletonRescheduled)
+ e.sendOutForRescheduling(&jIn)
+ }
+ } else {
+ // wait mode, fill up that queue (buffered channel, so it's ok)
+ runner.in <- jIn
+ e.sendOutForRescheduling(&jIn)
+ }
+ } else {
+ select {
+ case <-executorCtx.Done():
+ return
+ default:
+ }
+ // we've gotten to the basic / standard jobs --
+ // the ones without anything special that just want
+ // to be run. Add to the WaitGroup so that
+ // stopping or shutting down can wait for the jobs to
+ // complete.
+ standardJobsWg.Add(1)
+ go func(j internalJob) {
+ e.runJob(j, jIn)
+ standardJobsWg.Done()
+ }(*j)
+ }
+ }
+ }(e.ctx)
+ case <-e.stopCh:
+ e.stop(standardJobsWg, singletonJobsWg, limitModeJobsWg)
+ return
+ }
+ }
+}
+
+func (e *executor) sendOutForRescheduling(jIn *jobIn) {
+ if jIn.shouldSendOut {
+ select {
+ case e.jobsOutForRescheduling <- jIn.id:
+ case <-e.ctx.Done():
+ return
+ }
+ }
+ // we need to set this to false now, because to handle
+ // non-limit jobs, we send out from the e.runJob function
+ // and in this case we don't want to send out twice.
+ jIn.shouldSendOut = false
+}
+
+func (e *executor) sendOutForNextRunUpdate(jIn *jobIn) {
+ select {
+ case e.jobUpdateNextRuns <- jIn.id:
+ case <-e.ctx.Done():
+ return
+ }
+}
+
+func (e *executor) limitModeRunner(name string, in chan jobIn, wg *waitGroupWithMutex, limitMode LimitMode, rescheduleLimiter chan struct{}) {
+ e.logger.Debug("gocron: limitModeRunner starting", "name", name)
+ for {
+ select {
+ case jIn := <-in:
+ select {
+ case <-e.ctx.Done():
+ e.logger.Debug("gocron: limitModeRunner shutting down", "name", name)
+ wg.Done()
+ return
+ default:
+ }
+
+ ctx, cancel := context.WithCancel(e.ctx)
+ j := requestJobCtx(ctx, jIn.id, e.jobOutRequest)
+ cancel()
+ if j != nil {
+ if j.singletonMode {
+ e.limitMode.singletonJobsMu.Lock()
+ _, ok := e.limitMode.singletonJobs[jIn.id]
+ if ok {
+ // this job is already running, so don't run it
+ // but instead reschedule it
+ e.limitMode.singletonJobsMu.Unlock()
+ if jIn.shouldSendOut {
+ select {
+ case <-e.ctx.Done():
+ return
+ case <-j.ctx.Done():
+ return
+ case e.jobsOutForRescheduling <- j.id:
+ }
+ }
+ // remove the limiter block, as this particular job
+ // was a singleton already running, and we want to
+ // allow another job to be scheduled
+ if limitMode == LimitModeReschedule {
+ <-rescheduleLimiter
+ }
+ continue
+ }
+ e.limitMode.singletonJobs[jIn.id] = struct{}{}
+ e.limitMode.singletonJobsMu.Unlock()
+ }
+ e.runJob(*j, jIn)
+
+ if j.singletonMode {
+ e.limitMode.singletonJobsMu.Lock()
+ delete(e.limitMode.singletonJobs, jIn.id)
+ e.limitMode.singletonJobsMu.Unlock()
+ }
+ }
+
+ // remove the limiter block to allow another job to be scheduled
+ if limitMode == LimitModeReschedule {
+ <-rescheduleLimiter
+ }
+ case <-e.ctx.Done():
+ e.logger.Debug("limitModeRunner shutting down", "name", name)
+ wg.Done()
+ return
+ }
+ }
+}
+
+func (e *executor) singletonModeRunner(name string, in chan jobIn, wg *waitGroupWithMutex, limitMode LimitMode, rescheduleLimiter chan struct{}) {
+ e.logger.Debug("gocron: singletonModeRunner starting", "name", name)
+ for {
+ select {
+ case jIn := <-in:
+ select {
+ case <-e.ctx.Done():
+ e.logger.Debug("gocron: singletonModeRunner shutting down", "name", name)
+ wg.Done()
+ return
+ default:
+ }
+
+ ctx, cancel := context.WithCancel(e.ctx)
+ j := requestJobCtx(ctx, jIn.id, e.jobOutRequest)
+ cancel()
+ if j != nil {
+ // need to set shouldSendOut = false here, as there is a duplicative call to sendOutForRescheduling
+ // inside the runJob function that needs to be skipped. sendOutForRescheduling is previously called
+ // when the job is sent to the singleton mode runner.
+ jIn.shouldSendOut = false
+ e.runJob(*j, jIn)
+ }
+
+ // remove the limiter block to allow another job to be scheduled
+ if limitMode == LimitModeReschedule {
+ <-rescheduleLimiter
+ }
+ case <-e.ctx.Done():
+ e.logger.Debug("singletonModeRunner shutting down", "name", name)
+ wg.Done()
+ return
+ }
+ }
+}
+
+func (e *executor) runJob(j internalJob, jIn jobIn) {
+ if j.ctx == nil {
+ return
+ }
+ select {
+ case <-e.ctx.Done():
+ return
+ case <-j.ctx.Done():
+ return
+ default:
+ }
+
+ if j.stopTimeReached(e.clock.Now()) {
+ return
+ }
+
+ if e.elector != nil {
+ if err := e.elector.IsLeader(j.ctx); err != nil {
+ e.sendOutForRescheduling(&jIn)
+ e.incrementJobCounter(j, Skip)
+ return
+ }
+ } else if !j.disabledLocker && j.locker != nil {
+ lock, err := j.locker.Lock(j.ctx, j.name)
+ if err != nil {
+ _ = callJobFuncWithParams(j.afterLockError, j.id, j.name, err)
+ e.sendOutForRescheduling(&jIn)
+ e.incrementJobCounter(j, Skip)
+ e.sendOutForNextRunUpdate(&jIn)
+ return
+ }
+ defer func() { _ = lock.Unlock(j.ctx) }()
+ } else if !j.disabledLocker && e.locker != nil {
+ lock, err := e.locker.Lock(j.ctx, j.name)
+ if err != nil {
+ _ = callJobFuncWithParams(j.afterLockError, j.id, j.name, err)
+ e.sendOutForRescheduling(&jIn)
+ e.incrementJobCounter(j, Skip)
+ e.sendOutForNextRunUpdate(&jIn)
+ return
+ }
+ defer func() { _ = lock.Unlock(j.ctx) }()
+ }
+
+ _ = callJobFuncWithParams(j.beforeJobRuns, j.id, j.name)
+
+ err := callJobFuncWithParams(j.beforeJobRunsSkipIfBeforeFuncErrors, j.id, j.name)
+ if err != nil {
+ e.sendOutForRescheduling(&jIn)
+
+ select {
+ case e.jobsOutCompleted <- j.id:
+ case <-e.ctx.Done():
+ }
+
+ return
+ }
+
+ e.sendOutForRescheduling(&jIn)
+ select {
+ case e.jobsOutCompleted <- j.id:
+ case <-e.ctx.Done():
+ }
+
+ startTime := time.Now()
+ if j.afterJobRunsWithPanic != nil {
+ err = e.callJobWithRecover(j)
+ } else {
+ err = callJobFuncWithParams(j.function, j.parameters...)
+ }
+ e.recordJobTiming(startTime, time.Now(), j)
+ if err != nil {
+ _ = callJobFuncWithParams(j.afterJobRunsWithError, j.id, j.name, err)
+ e.incrementJobCounter(j, Fail)
+ e.recordJobTimingWithStatus(startTime, time.Now(), j, Fail, err)
+ } else {
+ _ = callJobFuncWithParams(j.afterJobRuns, j.id, j.name)
+ e.incrementJobCounter(j, Success)
+ e.recordJobTimingWithStatus(startTime, time.Now(), j, Success, nil)
+ }
+}
+
+func (e *executor) callJobWithRecover(j internalJob) (err error) {
+ defer func() {
+ if recoverData := recover(); recoverData != nil {
+ _ = callJobFuncWithParams(j.afterJobRunsWithPanic, j.id, j.name, recoverData)
+
+ // if panic is occurred, we should return an error
+ err = fmt.Errorf("%w from %v", ErrPanicRecovered, recoverData)
+ }
+ }()
+
+ return callJobFuncWithParams(j.function, j.parameters...)
+}
+
+func (e *executor) recordJobTiming(start time.Time, end time.Time, j internalJob) {
+ if e.monitor != nil {
+ e.monitor.RecordJobTiming(start, end, j.id, j.name, j.tags)
+ }
+}
+
+func (e *executor) recordJobTimingWithStatus(start time.Time, end time.Time, j internalJob, status JobStatus, err error) {
+ if e.monitorStatus != nil {
+ e.monitorStatus.RecordJobTimingWithStatus(start, end, j.id, j.name, j.tags, status, err)
+ }
+}
+
+func (e *executor) incrementJobCounter(j internalJob, status JobStatus) {
+ if e.monitor != nil {
+ e.monitor.IncrementJob(j.id, j.name, j.tags, status)
+ }
+}
+
+func (e *executor) stop(standardJobsWg, singletonJobsWg, limitModeJobsWg *waitGroupWithMutex) {
+ e.stopOnce.Do(func() {
+ e.logger.Debug("gocron: stopping executor")
+ // we've been asked to stop. This is either because the scheduler has been told
+ // to stop all jobs or the scheduler has been asked to completely shutdown.
+ //
+ // cancel tells all the functions to stop their work and send in a done response
+ e.cancel()
+
+ // the wait for job channels are used to report back whether we successfully waited
+ // for all jobs to complete or if we hit the configured timeout.
+ waitForJobs := make(chan struct{}, 1)
+ waitForSingletons := make(chan struct{}, 1)
+ waitForLimitMode := make(chan struct{}, 1)
+
+ // the waiter context is used to cancel the functions waiting on jobs.
+ // this is done to avoid goroutine leaks.
+ waiterCtx, waiterCancel := context.WithCancel(context.Background())
+
+ // wait for standard jobs to complete
+ go func() {
+ e.logger.Debug("gocron: waiting for standard jobs to complete")
+ go func() {
+ // this is done in a separate goroutine, so we aren't
+ // blocked by the WaitGroup's Wait call in the event
+ // that the waiter context is cancelled.
+ // This particular goroutine could leak in the event that
+ // some long-running standard job doesn't complete.
+ standardJobsWg.Wait()
+ e.logger.Debug("gocron: standard jobs completed")
+ waitForJobs <- struct{}{}
+ }()
+ <-waiterCtx.Done()
+ }()
+
+ // wait for per job singleton limit mode runner jobs to complete
+ go func() {
+ e.logger.Debug("gocron: waiting for singleton jobs to complete")
+ go func() {
+ singletonJobsWg.Wait()
+ e.logger.Debug("gocron: singleton jobs completed")
+ waitForSingletons <- struct{}{}
+ }()
+ <-waiterCtx.Done()
+ }()
+
+ // wait for limit mode runners to complete
+ go func() {
+ e.logger.Debug("gocron: waiting for limit mode jobs to complete")
+ go func() {
+ limitModeJobsWg.Wait()
+ e.logger.Debug("gocron: limitMode jobs completed")
+ waitForLimitMode <- struct{}{}
+ }()
+ <-waiterCtx.Done()
+ }()
+
+ // now either wait for all the jobs to complete,
+ // or hit the timeout.
+ var count int
+ timeout := time.Now().Add(e.stopTimeout)
+ for time.Now().Before(timeout) && count < 3 {
+ select {
+ case <-waitForJobs:
+ count++
+ case <-waitForSingletons:
+ count++
+ case <-waitForLimitMode:
+ count++
+ default:
+ }
+ }
+ if count < 3 {
+ e.done <- ErrStopJobsTimedOut
+ e.logger.Debug("gocron: executor stopped - timed out")
+ } else {
+ e.done <- nil
+ e.logger.Debug("gocron: executor stopped")
+ }
+ waiterCancel()
+
+ if e.limitMode != nil {
+ e.limitMode.started = false
+ }
+ })
+}
diff --git a/vendor/github.com/go-co-op/gocron/v2/job.go b/vendor/github.com/go-co-op/gocron/v2/job.go
new file mode 100644
index 0000000..4c4e1bd
--- /dev/null
+++ b/vendor/github.com/go-co-op/gocron/v2/job.go
@@ -0,0 +1,1226 @@
+//go:generate mockgen -destination=mocks/job.go -package=gocronmocks . Job
+package gocron
+
+import (
+ "context"
+ "errors"
+ "fmt"
+ "math/rand"
+ "slices"
+ "strings"
+ "time"
+
+ "github.com/google/uuid"
+ "github.com/jonboulle/clockwork"
+ "github.com/robfig/cron/v3"
+)
+
+// internalJob stores the information needed by the scheduler
+// to manage scheduling, starting and stopping the job
+type internalJob struct {
+ ctx context.Context
+ parentCtx context.Context
+ cancel context.CancelFunc
+ id uuid.UUID
+ name string
+ tags []string
+ cron Cron
+ jobSchedule
+
+ // as some jobs may queue up, it's possible to
+ // have multiple nextScheduled times
+ nextScheduled []time.Time
+
+ lastRun time.Time
+ function any
+ parameters []any
+ timer clockwork.Timer
+ singletonMode bool
+ singletonLimitMode LimitMode
+ limitRunsTo *limitRunsTo
+ startTime time.Time
+ startImmediately bool
+ stopTime time.Time
+ // event listeners
+ afterJobRuns func(jobID uuid.UUID, jobName string)
+ beforeJobRuns func(jobID uuid.UUID, jobName string)
+ beforeJobRunsSkipIfBeforeFuncErrors func(jobID uuid.UUID, jobName string) error
+ afterJobRunsWithError func(jobID uuid.UUID, jobName string, err error)
+ afterJobRunsWithPanic func(jobID uuid.UUID, jobName string, recoverData any)
+ afterLockError func(jobID uuid.UUID, jobName string, err error)
+ disabledLocker bool
+
+ locker Locker
+}
+
+// stop is used to stop the job's timer and cancel the context
+// stopping the timer is critical for cleaning up jobs that are
+// sleeping in a time.AfterFunc timer when the job is being stopped.
+// cancelling the context keeps the executor from continuing to try
+// and run the job.
+func (j *internalJob) stop() {
+ if j.timer != nil {
+ j.timer.Stop()
+ }
+ j.cancel()
+}
+
+func (j *internalJob) stopTimeReached(now time.Time) bool {
+ if j.stopTime.IsZero() {
+ return false
+ }
+ return j.stopTime.Before(now)
+}
+
+// task stores the function and parameters
+// that are actually run when the job is executed.
+type task struct {
+ function any
+ parameters []any
+}
+
+// Task defines a function that returns the task
+// function and parameters.
+type Task func() task
+
+// NewTask provides the job's task function and parameters.
+// If you set the first argument of your Task func to be a context.Context,
+// gocron will pass in a context (either the default Job context, or one
+// provided via WithContext) to the job and will cancel the context on shutdown.
+// This allows you to listen for and handle cancellation within your job.
+func NewTask(function any, parameters ...any) Task {
+ return func() task {
+ return task{
+ function: function,
+ parameters: parameters,
+ }
+ }
+}
+
+// limitRunsTo is used for managing the number of runs
+// when the user only wants the job to run a certain
+// number of times and then be removed from the scheduler.
+type limitRunsTo struct {
+ limit uint
+ runCount uint
+}
+
+// -----------------------------------------------
+// -----------------------------------------------
+// --------------- Custom Cron -------------------
+// -----------------------------------------------
+// -----------------------------------------------
+
+// Cron defines the interface that must be
+// implemented to provide a custom cron implementation for
+// the job. Pass in the implementation using the JobOption WithCronImplementation.
+type Cron interface {
+ IsValid(crontab string, location *time.Location, now time.Time) error
+ Next(lastRun time.Time) time.Time
+}
+
+// -----------------------------------------------
+// -----------------------------------------------
+// --------------- Job Variants ------------------
+// -----------------------------------------------
+// -----------------------------------------------
+
+// JobDefinition defines the interface that must be
+// implemented to create a job from the definition.
+type JobDefinition interface {
+ setup(j *internalJob, l *time.Location, now time.Time) error
+}
+
+// Default cron implementation
+
+func newDefaultCronImplementation(withSeconds bool) Cron {
+ return &defaultCron{
+ withSeconds: withSeconds,
+ }
+}
+
+var _ Cron = (*defaultCron)(nil)
+
+type defaultCron struct {
+ cronSchedule cron.Schedule
+ withSeconds bool
+}
+
+func (c *defaultCron) IsValid(crontab string, location *time.Location, now time.Time) error {
+ var withLocation string
+ if strings.HasPrefix(crontab, "TZ=") || strings.HasPrefix(crontab, "CRON_TZ=") {
+ withLocation = crontab
+ } else {
+ // since the user didn't provide a timezone default to the location
+ // passed in by the scheduler. Default: time.Local
+ withLocation = fmt.Sprintf("CRON_TZ=%s %s", location.String(), crontab)
+ }
+
+ var (
+ cronSchedule cron.Schedule
+ err error
+ )
+
+ if c.withSeconds {
+ p := cron.NewParser(cron.SecondOptional | cron.Minute | cron.Hour | cron.Dom | cron.Month | cron.Dow | cron.Descriptor)
+ cronSchedule, err = p.Parse(withLocation)
+ } else {
+ cronSchedule, err = cron.ParseStandard(withLocation)
+ }
+ if err != nil {
+ return errors.Join(ErrCronJobParse, err)
+ }
+ if cronSchedule.Next(now).IsZero() {
+ return ErrCronJobInvalid
+ }
+ c.cronSchedule = cronSchedule
+ return nil
+}
+
+func (c *defaultCron) Next(lastRun time.Time) time.Time {
+ return c.cronSchedule.Next(lastRun)
+}
+
+// default cron job implementation
+var _ JobDefinition = (*cronJobDefinition)(nil)
+
+type cronJobDefinition struct {
+ crontab string
+ cron Cron
+}
+
+func (c cronJobDefinition) setup(j *internalJob, location *time.Location, now time.Time) error {
+ if j.cron != nil {
+ c.cron = j.cron
+ }
+
+ if err := c.cron.IsValid(c.crontab, location, now); err != nil {
+ return err
+ }
+
+ j.jobSchedule = &cronJob{crontab: c.crontab, cronSchedule: c.cron}
+ return nil
+}
+
+// CronJob defines a new job using the crontab syntax: `* * * * *`.
+// An optional 6th field can be used at the beginning if withSeconds
+// is set to true: `* * * * * *`.
+// The timezone can be set on the Scheduler using WithLocation, or in the
+// crontab in the form `TZ=America/Chicago * * * * *` or
+// `CRON_TZ=America/Chicago * * * * *`
+func CronJob(crontab string, withSeconds bool) JobDefinition {
+ return cronJobDefinition{
+ crontab: crontab,
+ cron: newDefaultCronImplementation(withSeconds),
+ }
+}
+
+var _ JobDefinition = (*durationJobDefinition)(nil)
+
+type durationJobDefinition struct {
+ duration time.Duration
+}
+
+func (d durationJobDefinition) setup(j *internalJob, _ *time.Location, _ time.Time) error {
+ if d.duration == 0 {
+ return ErrDurationJobIntervalZero
+ }
+ j.jobSchedule = &durationJob{duration: d.duration}
+ return nil
+}
+
+// DurationJob defines a new job using time.Duration
+// for the interval.
+func DurationJob(duration time.Duration) JobDefinition {
+ return durationJobDefinition{
+ duration: duration,
+ }
+}
+
+var _ JobDefinition = (*durationRandomJobDefinition)(nil)
+
+type durationRandomJobDefinition struct {
+ min, max time.Duration
+}
+
+func (d durationRandomJobDefinition) setup(j *internalJob, _ *time.Location, _ time.Time) error {
+ if d.min >= d.max {
+ return ErrDurationRandomJobMinMax
+ }
+
+ j.jobSchedule = &durationRandomJob{
+ min: d.min,
+ max: d.max,
+ rand: rand.New(rand.NewSource(time.Now().UnixNano())), // nolint:gosec
+ }
+ return nil
+}
+
+// DurationRandomJob defines a new job that runs on a random interval
+// between the min and max duration values provided.
+//
+// To achieve a similar behavior as tools that use a splay/jitter technique
+// consider the median value as the baseline and the difference between the
+// max-median or median-min as the splay/jitter.
+//
+// For example, if you want a job to run every 5 minutes, but want to add
+// up to 1 min of jitter to the interval, you could use
+// DurationRandomJob(4*time.Minute, 6*time.Minute)
+func DurationRandomJob(minDuration, maxDuration time.Duration) JobDefinition {
+ return durationRandomJobDefinition{
+ min: minDuration,
+ max: maxDuration,
+ }
+}
+
+// DailyJob runs the job on the interval of days, and at the set times.
+// By default, the job will start the next available day, considering the last run to be now,
+// and the time and day based on the interval and times you input. This means, if you
+// select an interval greater than 1, your job by default will run X (interval) days from now
+// if there are no atTimes left in the current day. You can use WithStartAt to tell the
+// scheduler to start the job sooner.
+func DailyJob(interval uint, atTimes AtTimes) JobDefinition {
+ return dailyJobDefinition{
+ interval: interval,
+ atTimes: atTimes,
+ }
+}
+
+var _ JobDefinition = (*dailyJobDefinition)(nil)
+
+type dailyJobDefinition struct {
+ interval uint
+ atTimes AtTimes
+}
+
+func (d dailyJobDefinition) setup(j *internalJob, location *time.Location, _ time.Time) error {
+ atTimesDate, err := convertAtTimesToDateTime(d.atTimes, location)
+ switch {
+ case errors.Is(err, errAtTimesNil):
+ return ErrDailyJobAtTimesNil
+ case errors.Is(err, errAtTimeNil):
+ return ErrDailyJobAtTimeNil
+ case errors.Is(err, errAtTimeHours):
+ return ErrDailyJobHours
+ case errors.Is(err, errAtTimeMinSec):
+ return ErrDailyJobMinutesSeconds
+ }
+
+ if d.interval == 0 {
+ return ErrDailyJobZeroInterval
+ }
+
+ ds := dailyJob{
+ interval: d.interval,
+ atTimes: atTimesDate,
+ }
+ j.jobSchedule = ds
+ return nil
+}
+
+var _ JobDefinition = (*weeklyJobDefinition)(nil)
+
+type weeklyJobDefinition struct {
+ interval uint
+ daysOfTheWeek Weekdays
+ atTimes AtTimes
+}
+
+func (w weeklyJobDefinition) setup(j *internalJob, location *time.Location, _ time.Time) error {
+ var ws weeklyJob
+ if w.interval == 0 {
+ return ErrWeeklyJobZeroInterval
+ }
+ ws.interval = w.interval
+
+ if w.daysOfTheWeek == nil {
+ return ErrWeeklyJobDaysOfTheWeekNil
+ }
+
+ daysOfTheWeek := w.daysOfTheWeek()
+
+ slices.Sort(daysOfTheWeek)
+ ws.daysOfWeek = daysOfTheWeek
+
+ atTimesDate, err := convertAtTimesToDateTime(w.atTimes, location)
+ switch {
+ case errors.Is(err, errAtTimesNil):
+ return ErrWeeklyJobAtTimesNil
+ case errors.Is(err, errAtTimeNil):
+ return ErrWeeklyJobAtTimeNil
+ case errors.Is(err, errAtTimeHours):
+ return ErrWeeklyJobHours
+ case errors.Is(err, errAtTimeMinSec):
+ return ErrWeeklyJobMinutesSeconds
+ }
+ ws.atTimes = atTimesDate
+
+ j.jobSchedule = ws
+ return nil
+}
+
+// Weekdays defines a function that returns a list of week days.
+type Weekdays func() []time.Weekday
+
+// NewWeekdays provide the days of the week the job should run.
+func NewWeekdays(weekday time.Weekday, weekdays ...time.Weekday) Weekdays {
+ return func() []time.Weekday {
+ return append([]time.Weekday{weekday}, weekdays...)
+ }
+}
+
+// WeeklyJob runs the job on the interval of weeks, on the specific days of the week
+// specified, and at the set times.
+//
+// By default, the job will start the next available day, considering the last run to be now,
+// and the time and day based on the interval, days and times you input. This means, if you
+// select an interval greater than 1, your job by default will run X (interval) weeks from now
+// if there are no daysOfTheWeek left in the current week. You can use WithStartAt to tell the
+// scheduler to start the job sooner.
+func WeeklyJob(interval uint, daysOfTheWeek Weekdays, atTimes AtTimes) JobDefinition {
+ return weeklyJobDefinition{
+ interval: interval,
+ daysOfTheWeek: daysOfTheWeek,
+ atTimes: atTimes,
+ }
+}
+
+var _ JobDefinition = (*monthlyJobDefinition)(nil)
+
+type monthlyJobDefinition struct {
+ interval uint
+ daysOfTheMonth DaysOfTheMonth
+ atTimes AtTimes
+}
+
+func (m monthlyJobDefinition) setup(j *internalJob, location *time.Location, _ time.Time) error {
+ var ms monthlyJob
+ if m.interval == 0 {
+ return ErrMonthlyJobZeroInterval
+ }
+ ms.interval = m.interval
+
+ if m.daysOfTheMonth == nil {
+ return ErrMonthlyJobDaysNil
+ }
+
+ var daysStart, daysEnd []int
+ for _, day := range m.daysOfTheMonth() {
+ if day > 31 || day == 0 || day < -31 {
+ return ErrMonthlyJobDays
+ }
+ if day > 0 {
+ daysStart = append(daysStart, day)
+ } else {
+ daysEnd = append(daysEnd, day)
+ }
+ }
+ daysStart = removeSliceDuplicatesInt(daysStart)
+ ms.days = daysStart
+
+ daysEnd = removeSliceDuplicatesInt(daysEnd)
+ ms.daysFromEnd = daysEnd
+
+ atTimesDate, err := convertAtTimesToDateTime(m.atTimes, location)
+ switch {
+ case errors.Is(err, errAtTimesNil):
+ return ErrMonthlyJobAtTimesNil
+ case errors.Is(err, errAtTimeNil):
+ return ErrMonthlyJobAtTimeNil
+ case errors.Is(err, errAtTimeHours):
+ return ErrMonthlyJobHours
+ case errors.Is(err, errAtTimeMinSec):
+ return ErrMonthlyJobMinutesSeconds
+ }
+ ms.atTimes = atTimesDate
+
+ j.jobSchedule = ms
+ return nil
+}
+
+type days []int
+
+// DaysOfTheMonth defines a function that returns a list of days.
+type DaysOfTheMonth func() days
+
+// NewDaysOfTheMonth provide the days of the month the job should
+// run. The days can be positive 1 to 31 and/or negative -31 to -1.
+// Negative values count backwards from the end of the month.
+// For example: -1 == the last day of the month.
+//
+// -5 == 5 days before the end of the month.
+func NewDaysOfTheMonth(day int, moreDays ...int) DaysOfTheMonth {
+ return func() days {
+ return append([]int{day}, moreDays...)
+ }
+}
+
+type atTime struct {
+ hours, minutes, seconds uint
+}
+
+func (a atTime) time(location *time.Location) time.Time {
+ return time.Date(0, 0, 0, int(a.hours), int(a.minutes), int(a.seconds), 0, location)
+}
+
+// TimeFromAtTime is a helper function to allow converting AtTime into a time.Time value
+// Note: the time.Time value will have zero values for all Time fields except Hours, Minutes, Seconds.
+//
+// For example: time.Date(0, 0, 0, 1, 1, 1, 0, time.UTC)
+func TimeFromAtTime(at AtTime, loc *time.Location) time.Time {
+ return at().time(loc)
+}
+
+// AtTime defines a function that returns the internal atTime
+type AtTime func() atTime
+
+// NewAtTime provide the hours, minutes and seconds at which
+// the job should be run
+func NewAtTime(hours, minutes, seconds uint) AtTime {
+ return func() atTime {
+ return atTime{hours: hours, minutes: minutes, seconds: seconds}
+ }
+}
+
+// AtTimes define a list of AtTime
+type AtTimes func() []AtTime
+
+// NewAtTimes provide the hours, minutes and seconds at which
+// the job should be run
+func NewAtTimes(atTime AtTime, atTimes ...AtTime) AtTimes {
+ return func() []AtTime {
+ return append([]AtTime{atTime}, atTimes...)
+ }
+}
+
+// MonthlyJob runs the job on the interval of months, on the specific days of the month
+// specified, and at the set times. Days of the month can be 1 to 31 or negative (-1 to -31), which
+// count backwards from the end of the month. E.g. -1 is the last day of the month.
+//
+// If a day of the month is selected that does not exist in all months (e.g. 31st)
+// any month that does not have that day will be skipped.
+//
+// By default, the job will start the next available day, considering the last run to be now,
+// and the time and month based on the interval, days and times you input.
+// This means, if you select an interval greater than 1, your job by default will run
+// X (interval) months from now if there are no daysOfTheMonth left in the current month.
+// You can use WithStartAt to tell the scheduler to start the job sooner.
+//
+// Carefully consider your configuration!
+// - For example: an interval of 2 months on the 31st of each month, starting 12/31
+// would skip Feb, April, June, and next run would be in August.
+func MonthlyJob(interval uint, daysOfTheMonth DaysOfTheMonth, atTimes AtTimes) JobDefinition {
+ return monthlyJobDefinition{
+ interval: interval,
+ daysOfTheMonth: daysOfTheMonth,
+ atTimes: atTimes,
+ }
+}
+
+var _ JobDefinition = (*oneTimeJobDefinition)(nil)
+
+type oneTimeJobDefinition struct {
+ startAt OneTimeJobStartAtOption
+}
+
+func (o oneTimeJobDefinition) setup(j *internalJob, _ *time.Location, now time.Time) error {
+ sortedTimes := o.startAt(j)
+ slices.SortStableFunc(sortedTimes, ascendingTime)
+ // deduplicate the times
+ sortedTimes = removeSliceDuplicatesTimeOnSortedSlice(sortedTimes)
+ // keep only schedules that are in the future
+ idx, found := slices.BinarySearchFunc(sortedTimes, now, ascendingTime)
+ if found {
+ idx++
+ }
+ sortedTimes = sortedTimes[idx:]
+ if !j.startImmediately && len(sortedTimes) == 0 {
+ return ErrOneTimeJobStartDateTimePast
+ }
+ j.jobSchedule = oneTimeJob{sortedTimes: sortedTimes}
+ return nil
+}
+
+func removeSliceDuplicatesTimeOnSortedSlice(times []time.Time) []time.Time {
+ ret := make([]time.Time, 0, len(times))
+ for i, t := range times {
+ if i == 0 || t != times[i-1] {
+ ret = append(ret, t)
+ }
+ }
+ return ret
+}
+
+// OneTimeJobStartAtOption defines when the one time job is run
+type OneTimeJobStartAtOption func(*internalJob) []time.Time
+
+// OneTimeJobStartImmediately tells the scheduler to run the one time job immediately.
+func OneTimeJobStartImmediately() OneTimeJobStartAtOption {
+ return func(j *internalJob) []time.Time {
+ j.startImmediately = true
+ return []time.Time{}
+ }
+}
+
+// OneTimeJobStartDateTime sets the date & time at which the job should run.
+// This datetime must be in the future (according to the scheduler clock).
+func OneTimeJobStartDateTime(start time.Time) OneTimeJobStartAtOption {
+ return func(_ *internalJob) []time.Time {
+ return []time.Time{start}
+ }
+}
+
+// OneTimeJobStartDateTimes sets the date & times at which the job should run.
+// At least one of the date/times must be in the future (according to the scheduler clock).
+func OneTimeJobStartDateTimes(times ...time.Time) OneTimeJobStartAtOption {
+ return func(_ *internalJob) []time.Time {
+ return times
+ }
+}
+
+// OneTimeJob is to run a job once at a specified time and not on
+// any regular schedule.
+func OneTimeJob(startAt OneTimeJobStartAtOption) JobDefinition {
+ return oneTimeJobDefinition{
+ startAt: startAt,
+ }
+}
+
+// -----------------------------------------------
+// -----------------------------------------------
+// ----------------- Job Options -----------------
+// -----------------------------------------------
+// -----------------------------------------------
+
+// JobOption defines the constructor for job options.
+type JobOption func(*internalJob, time.Time) error
+
+// WithDistributedJobLocker sets the locker to be used by multiple
+// Scheduler instances to ensure that only one instance of each
+// job is run.
+func WithDistributedJobLocker(locker Locker) JobOption {
+ return func(j *internalJob, _ time.Time) error {
+ if locker == nil {
+ return ErrWithDistributedJobLockerNil
+ }
+ j.locker = locker
+ return nil
+ }
+}
+
+// WithDisabledDistributedJobLocker disables the distributed job locker.
+// This is useful when a global distributed locker has been set on the scheduler
+// level using WithDistributedLocker and need to be disabled for specific jobs.
+func WithDisabledDistributedJobLocker(disabled bool) JobOption {
+ return func(j *internalJob, _ time.Time) error {
+ j.disabledLocker = disabled
+ return nil
+ }
+}
+
+// WithEventListeners sets the event listeners that should be
+// run for the job.
+func WithEventListeners(eventListeners ...EventListener) JobOption {
+ return func(j *internalJob, _ time.Time) error {
+ for _, eventListener := range eventListeners {
+ if err := eventListener(j); err != nil {
+ return err
+ }
+ }
+ return nil
+ }
+}
+
+// WithLimitedRuns limits the number of executions of this job to n.
+// Upon reaching the limit, the job is removed from the scheduler.
+func WithLimitedRuns(limit uint) JobOption {
+ return func(j *internalJob, _ time.Time) error {
+ j.limitRunsTo = &limitRunsTo{
+ limit: limit,
+ runCount: 0,
+ }
+ return nil
+ }
+}
+
+// WithName sets the name of the job. Name provides
+// a human-readable identifier for the job.
+func WithName(name string) JobOption {
+ return func(j *internalJob, _ time.Time) error {
+ if name == "" {
+ return ErrWithNameEmpty
+ }
+ j.name = name
+ return nil
+ }
+}
+
+// WithCronImplementation sets the custom Cron implementation for the job.
+// This is only utilized for the CronJob type.
+func WithCronImplementation(c Cron) JobOption {
+ return func(j *internalJob, _ time.Time) error {
+ j.cron = c
+ return nil
+ }
+}
+
+// WithSingletonMode keeps the job from running again if it is already running.
+// This is useful for jobs that should not overlap, and that occasionally
+// (but not consistently) run longer than the interval between job runs.
+func WithSingletonMode(mode LimitMode) JobOption {
+ return func(j *internalJob, _ time.Time) error {
+ j.singletonMode = true
+ j.singletonLimitMode = mode
+ return nil
+ }
+}
+
+// WithStartAt sets the option for starting the job at
+// a specific datetime.
+func WithStartAt(option StartAtOption) JobOption {
+ return func(j *internalJob, now time.Time) error {
+ return option(j, now)
+ }
+}
+
+// StartAtOption defines options for starting the job
+type StartAtOption func(*internalJob, time.Time) error
+
+// WithStartImmediately tells the scheduler to run the job immediately
+// regardless of the type or schedule of job. After this immediate run
+// the job is scheduled from this time based on the job definition.
+func WithStartImmediately() StartAtOption {
+ return func(j *internalJob, _ time.Time) error {
+ j.startImmediately = true
+ return nil
+ }
+}
+
+// WithStartDateTime sets the first date & time at which the job should run.
+// This datetime must be in the future.
+func WithStartDateTime(start time.Time) StartAtOption {
+ return func(j *internalJob, now time.Time) error {
+ if start.IsZero() || start.Before(now) {
+ return ErrWithStartDateTimePast
+ }
+ if !j.stopTime.IsZero() && j.stopTime.Before(start) {
+ return ErrStartTimeLaterThanEndTime
+ }
+ j.startTime = start
+ return nil
+ }
+}
+
+// WithStopAt sets the option for stopping the job from running
+// after the specified time.
+func WithStopAt(option StopAtOption) JobOption {
+ return func(j *internalJob, now time.Time) error {
+ return option(j, now)
+ }
+}
+
+// StopAtOption defines options for stopping the job
+type StopAtOption func(*internalJob, time.Time) error
+
+// WithStopDateTime sets the final date & time after which the job should stop.
+// This must be in the future and should be after the startTime (if specified).
+// The job's final run may be at the stop time, but not after.
+func WithStopDateTime(end time.Time) StopAtOption {
+ return func(j *internalJob, now time.Time) error {
+ if end.IsZero() || end.Before(now) {
+ return ErrWithStopDateTimePast
+ }
+ if end.Before(j.startTime) {
+ return ErrStopTimeEarlierThanStartTime
+ }
+ j.stopTime = end
+ return nil
+ }
+}
+
+// WithTags sets the tags for the job. Tags provide
+// a way to identify jobs by a set of tags and remove
+// multiple jobs by tag.
+func WithTags(tags ...string) JobOption {
+ return func(j *internalJob, _ time.Time) error {
+ j.tags = tags
+ return nil
+ }
+}
+
+// WithIdentifier sets the identifier for the job. The identifier
+// is used to uniquely identify the job and is used for logging
+// and metrics.
+func WithIdentifier(id uuid.UUID) JobOption {
+ return func(j *internalJob, _ time.Time) error {
+ if id == uuid.Nil {
+ return ErrWithIdentifierNil
+ }
+
+ j.id = id
+ return nil
+ }
+}
+
+// WithContext sets the parent context for the job.
+// If you set the first argument of your Task func to be a context.Context,
+// gocron will pass in the provided context to the job and will cancel the
+// context on shutdown. If you cancel the context the job will no longer be
+// scheduled as well. This allows you to both control the job via a context
+// and listen for and handle cancellation within your job.
+func WithContext(ctx context.Context) JobOption {
+ return func(j *internalJob, _ time.Time) error {
+ if ctx == nil {
+ return ErrWithContextNil
+ }
+ j.parentCtx = ctx
+ return nil
+ }
+}
+
+// -----------------------------------------------
+// -----------------------------------------------
+// ------------- Job Event Listeners -------------
+// -----------------------------------------------
+// -----------------------------------------------
+
+// EventListener defines the constructor for event
+// listeners that can be used to listen for job events.
+type EventListener func(*internalJob) error
+
+// BeforeJobRuns is used to listen for when a job is about to run and
+// then run the provided function.
+func BeforeJobRuns(eventListenerFunc func(jobID uuid.UUID, jobName string)) EventListener {
+ return func(j *internalJob) error {
+ if eventListenerFunc == nil {
+ return ErrEventListenerFuncNil
+ }
+ j.beforeJobRuns = eventListenerFunc
+ return nil
+ }
+}
+
+// BeforeJobRunsSkipIfBeforeFuncErrors is used to listen for when a job is about to run and
+// then runs the provided function. If the provided function returns an error, the job will be
+// rescheduled and the current run will be skipped.
+func BeforeJobRunsSkipIfBeforeFuncErrors(eventListenerFunc func(jobID uuid.UUID, jobName string) error) EventListener {
+ return func(j *internalJob) error {
+ if eventListenerFunc == nil {
+ return ErrEventListenerFuncNil
+ }
+ j.beforeJobRunsSkipIfBeforeFuncErrors = eventListenerFunc
+ return nil
+ }
+}
+
+// AfterJobRuns is used to listen for when a job has run
+// without an error, and then run the provided function.
+func AfterJobRuns(eventListenerFunc func(jobID uuid.UUID, jobName string)) EventListener {
+ return func(j *internalJob) error {
+ if eventListenerFunc == nil {
+ return ErrEventListenerFuncNil
+ }
+ j.afterJobRuns = eventListenerFunc
+ return nil
+ }
+}
+
+// AfterJobRunsWithError is used to listen for when a job has run and
+// returned an error, and then run the provided function.
+func AfterJobRunsWithError(eventListenerFunc func(jobID uuid.UUID, jobName string, err error)) EventListener {
+ return func(j *internalJob) error {
+ if eventListenerFunc == nil {
+ return ErrEventListenerFuncNil
+ }
+ j.afterJobRunsWithError = eventListenerFunc
+ return nil
+ }
+}
+
+// AfterJobRunsWithPanic is used to listen for when a job has run and
+// returned panicked recover data, and then run the provided function.
+func AfterJobRunsWithPanic(eventListenerFunc func(jobID uuid.UUID, jobName string, recoverData any)) EventListener {
+ return func(j *internalJob) error {
+ if eventListenerFunc == nil {
+ return ErrEventListenerFuncNil
+ }
+ j.afterJobRunsWithPanic = eventListenerFunc
+ return nil
+ }
+}
+
+// AfterLockError is used to when the distributed locker returns an error and
+// then run the provided function.
+func AfterLockError(eventListenerFunc func(jobID uuid.UUID, jobName string, err error)) EventListener {
+ return func(j *internalJob) error {
+ if eventListenerFunc == nil {
+ return ErrEventListenerFuncNil
+ }
+ j.afterLockError = eventListenerFunc
+ return nil
+ }
+}
+
+// -----------------------------------------------
+// -----------------------------------------------
+// ---------------- Job Schedules ----------------
+// -----------------------------------------------
+// -----------------------------------------------
+
+type jobSchedule interface {
+ next(lastRun time.Time) time.Time
+}
+
+var _ jobSchedule = (*cronJob)(nil)
+
+type cronJob struct {
+ crontab string
+ cronSchedule Cron
+}
+
+func (j *cronJob) next(lastRun time.Time) time.Time {
+ return j.cronSchedule.Next(lastRun)
+}
+
+var _ jobSchedule = (*durationJob)(nil)
+
+type durationJob struct {
+ duration time.Duration
+}
+
+func (j *durationJob) next(lastRun time.Time) time.Time {
+ return lastRun.Add(j.duration)
+}
+
+var _ jobSchedule = (*durationRandomJob)(nil)
+
+type durationRandomJob struct {
+ min, max time.Duration
+ rand *rand.Rand
+}
+
+func (j *durationRandomJob) next(lastRun time.Time) time.Time {
+ r := j.rand.Int63n(int64(j.max - j.min))
+ return lastRun.Add(j.min + time.Duration(r))
+}
+
+var _ jobSchedule = (*dailyJob)(nil)
+
+type dailyJob struct {
+ interval uint
+ atTimes []time.Time
+}
+
+func (d dailyJob) next(lastRun time.Time) time.Time {
+ firstPass := true
+ next := d.nextDay(lastRun, firstPass)
+ if !next.IsZero() {
+ return next
+ }
+ firstPass = false
+
+ startNextDay := time.Date(lastRun.Year(), lastRun.Month(), lastRun.Day()+int(d.interval), 0, 0, 0, 0, lastRun.Location())
+ return d.nextDay(startNextDay, firstPass)
+}
+
+func (d dailyJob) nextDay(lastRun time.Time, firstPass bool) time.Time {
+ for _, at := range d.atTimes {
+ // sub the at time hour/min/sec onto the lastScheduledRun's values
+ // to use in checks to see if we've got our next run time
+ atDate := time.Date(lastRun.Year(), lastRun.Month(), lastRun.Day(), at.Hour(), at.Minute(), at.Second(), 0, lastRun.Location())
+
+ if firstPass && atDate.After(lastRun) {
+ // checking to see if it is after i.e. greater than,
+ // and not greater or equal as our lastScheduledRun day/time
+ // will be in the loop, and we don't want to select it again
+ return atDate
+ } else if !firstPass && !atDate.Before(lastRun) {
+ // now that we're looking at the next day, it's ok to consider
+ // the same at time that was last run (as lastScheduledRun has been incremented)
+ return atDate
+ }
+ }
+ return time.Time{}
+}
+
+var _ jobSchedule = (*weeklyJob)(nil)
+
+type weeklyJob struct {
+ interval uint
+ daysOfWeek []time.Weekday
+ atTimes []time.Time
+}
+
+func (w weeklyJob) next(lastRun time.Time) time.Time {
+ firstPass := true
+ next := w.nextWeekDayAtTime(lastRun, firstPass)
+ if !next.IsZero() {
+ return next
+ }
+ firstPass = false
+
+ startOfTheNextIntervalWeek := (lastRun.Day() - int(lastRun.Weekday())) + int(w.interval*7)
+ from := time.Date(lastRun.Year(), lastRun.Month(), startOfTheNextIntervalWeek, 0, 0, 0, 0, lastRun.Location())
+ return w.nextWeekDayAtTime(from, firstPass)
+}
+
+func (w weeklyJob) nextWeekDayAtTime(lastRun time.Time, firstPass bool) time.Time {
+ for _, wd := range w.daysOfWeek {
+ // checking if we're on the same day or later in the same week
+ if wd >= lastRun.Weekday() {
+ // weekDayDiff is used to add the correct amount to the atDate day below
+ weekDayDiff := wd - lastRun.Weekday()
+ for _, at := range w.atTimes {
+ // sub the at time hour/min/sec onto the lastScheduledRun's values
+ // to use in checks to see if we've got our next run time
+ atDate := time.Date(lastRun.Year(), lastRun.Month(), lastRun.Day()+int(weekDayDiff), at.Hour(), at.Minute(), at.Second(), 0, lastRun.Location())
+
+ if firstPass && atDate.After(lastRun) {
+ // checking to see if it is after i.e. greater than,
+ // and not greater or equal as our lastScheduledRun day/time
+ // will be in the loop, and we don't want to select it again
+ return atDate
+ } else if !firstPass && !atDate.Before(lastRun) {
+ // now that we're looking at the next week, it's ok to consider
+ // the same at time that was last run (as lastScheduledRun has been incremented)
+ return atDate
+ }
+ }
+ }
+ }
+ return time.Time{}
+}
+
+var _ jobSchedule = (*monthlyJob)(nil)
+
+type monthlyJob struct {
+ interval uint
+ days []int
+ daysFromEnd []int
+ atTimes []time.Time
+}
+
+func (m monthlyJob) next(lastRun time.Time) time.Time {
+ daysList := make([]int, len(m.days))
+ copy(daysList, m.days)
+
+ daysFromEnd := m.handleNegativeDays(lastRun, daysList, m.daysFromEnd)
+ next := m.nextMonthDayAtTime(lastRun, daysFromEnd, true)
+ if !next.IsZero() {
+ return next
+ }
+
+ from := time.Date(lastRun.Year(), lastRun.Month()+time.Month(m.interval), 1, 0, 0, 0, 0, lastRun.Location())
+ for next.IsZero() {
+ daysFromEnd = m.handleNegativeDays(from, daysList, m.daysFromEnd)
+ next = m.nextMonthDayAtTime(from, daysFromEnd, false)
+ from = from.AddDate(0, int(m.interval), 0)
+ }
+
+ return next
+}
+
+func (m monthlyJob) handleNegativeDays(from time.Time, days, negativeDays []int) []int {
+ var out []int
+ // getting a list of the days from the end of the following month
+ // -1 == the last day of the month
+ firstDayNextMonth := time.Date(from.Year(), from.Month()+1, 1, 0, 0, 0, 0, from.Location())
+ for _, daySub := range negativeDays {
+ day := firstDayNextMonth.AddDate(0, 0, daySub).Day()
+ out = append(out, day)
+ }
+ out = append(out, days...)
+ slices.Sort(out)
+ return out
+}
+
+func (m monthlyJob) nextMonthDayAtTime(lastRun time.Time, days []int, firstPass bool) time.Time {
+ // find the next day in the month that should run and then check for an at time
+ for _, day := range days {
+ if day >= lastRun.Day() {
+ for _, at := range m.atTimes {
+ // sub the day, and the at time hour/min/sec onto the lastScheduledRun's values
+ // to use in checks to see if we've got our next run time
+ atDate := time.Date(lastRun.Year(), lastRun.Month(), day, at.Hour(), at.Minute(), at.Second(), 0, lastRun.Location())
+
+ if atDate.Month() != lastRun.Month() {
+ // this check handles if we're setting a day not in the current month
+ // e.g. setting day 31 in Feb results in March 2nd
+ continue
+ }
+
+ if firstPass && atDate.After(lastRun) {
+ // checking to see if it is after i.e. greater than,
+ // and not greater or equal as our lastScheduledRun day/time
+ // will be in the loop, and we don't want to select it again
+ return atDate
+ } else if !firstPass && !atDate.Before(lastRun) {
+ // now that we're looking at the next month, it's ok to consider
+ // the same at time that was lastScheduledRun (as lastScheduledRun has been incremented)
+ return atDate
+ }
+ }
+ continue
+ }
+ }
+ return time.Time{}
+}
+
+var _ jobSchedule = (*oneTimeJob)(nil)
+
+type oneTimeJob struct {
+ sortedTimes []time.Time
+}
+
+// next finds the next item in a sorted list of times using binary-search.
+//
+// example: sortedTimes: [2, 4, 6, 8]
+//
+// lastRun: 1 => [idx=0,found=false] => next is 2 - sorted[idx] idx=0
+// lastRun: 2 => [idx=0,found=true] => next is 4 - sorted[idx+1] idx=1
+// lastRun: 3 => [idx=1,found=false] => next is 4 - sorted[idx] idx=1
+// lastRun: 4 => [idx=1,found=true] => next is 6 - sorted[idx+1] idx=2
+// lastRun: 7 => [idx=3,found=false] => next is 8 - sorted[idx] idx=3
+// lastRun: 8 => [idx=3,found=found] => next is none
+// lastRun: 9 => [idx=3,found=found] => next is none
+func (o oneTimeJob) next(lastRun time.Time) time.Time {
+ idx, found := slices.BinarySearchFunc(o.sortedTimes, lastRun, ascendingTime)
+ // if found, the next run is the following index
+ if found {
+ idx++
+ }
+ // exhausted runs
+ if idx >= len(o.sortedTimes) {
+ return time.Time{}
+ }
+
+ return o.sortedTimes[idx]
+}
+
+// -----------------------------------------------
+// -----------------------------------------------
+// ---------------- Job Interface ----------------
+// -----------------------------------------------
+// -----------------------------------------------
+
+// Job provides the available methods on the job
+// available to the caller.
+type Job interface {
+ // ID returns the job's unique identifier.
+ ID() uuid.UUID
+ // LastRun returns the time of the job's last run
+ LastRun() (time.Time, error)
+ // Name returns the name defined on the job.
+ Name() string
+ // NextRun returns the time of the job's next scheduled run.
+ NextRun() (time.Time, error)
+ // NextRuns returns the requested number of calculated next run values.
+ NextRuns(int) ([]time.Time, error)
+ // RunNow runs the job once, now. This does not alter
+ // the existing run schedule, and will respect all job
+ // and scheduler limits. This means that running a job now may
+ // cause the job's regular interval to be rescheduled due to
+ // the instance being run by RunNow blocking your run limit.
+ RunNow() error
+ // Tags returns the job's string tags.
+ Tags() []string
+}
+
+var _ Job = (*job)(nil)
+
+// job is the internal struct that implements
+// the public interface. This is used to avoid
+// leaking information the caller never needs
+// to have or tinker with.
+type job struct {
+ id uuid.UUID
+ name string
+ tags []string
+ jobOutRequest chan *jobOutRequest
+ runJobRequest chan runJobRequest
+}
+
+func (j job) ID() uuid.UUID {
+ return j.id
+}
+
+func (j job) LastRun() (time.Time, error) {
+ ij := requestJob(j.id, j.jobOutRequest)
+ if ij == nil || ij.id == uuid.Nil {
+ return time.Time{}, ErrJobNotFound
+ }
+ return ij.lastRun, nil
+}
+
+func (j job) Name() string {
+ return j.name
+}
+
+func (j job) NextRun() (time.Time, error) {
+ ij := requestJob(j.id, j.jobOutRequest)
+ if ij == nil || ij.id == uuid.Nil {
+ return time.Time{}, ErrJobNotFound
+ }
+ if len(ij.nextScheduled) == 0 {
+ return time.Time{}, nil
+ }
+ // the first element is the next scheduled run with subsequent
+ // runs following after in the slice
+ return ij.nextScheduled[0], nil
+}
+
+func (j job) NextRuns(count int) ([]time.Time, error) {
+ ij := requestJob(j.id, j.jobOutRequest)
+ if ij == nil || ij.id == uuid.Nil {
+ return nil, ErrJobNotFound
+ }
+
+ lengthNextScheduled := len(ij.nextScheduled)
+ if lengthNextScheduled == 0 {
+ return nil, nil
+ } else if count <= lengthNextScheduled {
+ return ij.nextScheduled[:count], nil
+ }
+
+ out := make([]time.Time, count)
+ for i := 0; i < count; i++ {
+ if i < lengthNextScheduled {
+ out[i] = ij.nextScheduled[i]
+ continue
+ }
+
+ from := out[i-1]
+ out[i] = ij.next(from)
+ }
+
+ return out, nil
+}
+
+func (j job) Tags() []string {
+ return j.tags
+}
+
+func (j job) RunNow() error {
+ ctx, cancel := context.WithTimeout(context.Background(), time.Second)
+ defer cancel()
+ resp := make(chan error, 1)
+
+ t := time.NewTimer(100 * time.Millisecond)
+ select {
+ case j.runJobRequest <- runJobRequest{
+ id: j.id,
+ outChan: resp,
+ }:
+ t.Stop()
+ case <-t.C:
+ return ErrJobRunNowFailed
+ }
+ var err error
+ select {
+ case <-ctx.Done():
+ return ErrJobRunNowFailed
+ case errReceived := <-resp:
+ err = errReceived
+ }
+ return err
+}
diff --git a/vendor/github.com/go-co-op/gocron/v2/logger.go b/vendor/github.com/go-co-op/gocron/v2/logger.go
new file mode 100644
index 0000000..c8ebaf8
--- /dev/null
+++ b/vendor/github.com/go-co-op/gocron/v2/logger.go
@@ -0,0 +1,101 @@
+//go:generate mockgen -destination=mocks/logger.go -package=gocronmocks . Logger
+package gocron
+
+import (
+ "fmt"
+ "log"
+ "os"
+ "strings"
+)
+
+// Logger is the interface that wraps the basic logging methods
+// used by gocron. The methods are modeled after the standard
+// library slog package. The default logger is a no-op logger.
+// To enable logging, use one of the provided New*Logger functions
+// or implement your own Logger. The actual level of Log that is logged
+// is handled by the implementation.
+type Logger interface {
+ Debug(msg string, args ...any)
+ Error(msg string, args ...any)
+ Info(msg string, args ...any)
+ Warn(msg string, args ...any)
+}
+
+var _ Logger = (*noOpLogger)(nil)
+
+type noOpLogger struct{}
+
+func (l noOpLogger) Debug(_ string, _ ...any) {}
+func (l noOpLogger) Error(_ string, _ ...any) {}
+func (l noOpLogger) Info(_ string, _ ...any) {}
+func (l noOpLogger) Warn(_ string, _ ...any) {}
+
+var _ Logger = (*logger)(nil)
+
+// LogLevel is the level of logging that should be logged
+// when using the basic NewLogger.
+type LogLevel int
+
+// The different log levels that can be used.
+const (
+ LogLevelError LogLevel = iota
+ LogLevelWarn
+ LogLevelInfo
+ LogLevelDebug
+)
+
+type logger struct {
+ log *log.Logger
+ level LogLevel
+}
+
+// NewLogger returns a new Logger that logs at the given level.
+func NewLogger(level LogLevel) Logger {
+ l := log.New(os.Stdout, "", log.LstdFlags)
+ return &logger{
+ log: l,
+ level: level,
+ }
+}
+
+func (l *logger) Debug(msg string, args ...any) {
+ if l.level < LogLevelDebug {
+ return
+ }
+ l.log.Printf("DEBUG: %s%s\n", msg, logFormatArgs(args...))
+}
+
+func (l *logger) Error(msg string, args ...any) {
+ if l.level < LogLevelError {
+ return
+ }
+ l.log.Printf("ERROR: %s%s\n", msg, logFormatArgs(args...))
+}
+
+func (l *logger) Info(msg string, args ...any) {
+ if l.level < LogLevelInfo {
+ return
+ }
+ l.log.Printf("INFO: %s%s\n", msg, logFormatArgs(args...))
+}
+
+func (l *logger) Warn(msg string, args ...any) {
+ if l.level < LogLevelWarn {
+ return
+ }
+ l.log.Printf("WARN: %s%s\n", msg, logFormatArgs(args...))
+}
+
+func logFormatArgs(args ...any) string {
+ if len(args) == 0 {
+ return ""
+ }
+ if len(args)%2 != 0 {
+ return ", " + fmt.Sprint(args...)
+ }
+ var pairs []string
+ for i := 0; i < len(args); i += 2 {
+ pairs = append(pairs, fmt.Sprintf("%s=%v", args[i], args[i+1]))
+ }
+ return ", " + strings.Join(pairs, ", ")
+}
diff --git a/vendor/github.com/go-co-op/gocron/v2/monitor.go b/vendor/github.com/go-co-op/gocron/v2/monitor.go
new file mode 100644
index 0000000..4f25fd8
--- /dev/null
+++ b/vendor/github.com/go-co-op/gocron/v2/monitor.go
@@ -0,0 +1,36 @@
+package gocron
+
+import (
+ "time"
+
+ "github.com/google/uuid"
+)
+
+// JobStatus is the status of job run that should be collected with the metric.
+type JobStatus string
+
+// The different statuses of job that can be used.
+const (
+ Fail JobStatus = "fail"
+ Success JobStatus = "success"
+ Skip JobStatus = "skip"
+ SingletonRescheduled JobStatus = "singleton_rescheduled"
+)
+
+// Monitor represents the interface to collect jobs metrics.
+type Monitor interface {
+ // IncrementJob will provide details about the job and expects the underlying implementation
+ // to handle instantiating and incrementing a value
+ IncrementJob(id uuid.UUID, name string, tags []string, status JobStatus)
+ // RecordJobTiming will provide details about the job and the timing and expects the underlying implementation
+ // to handle instantiating and recording the value
+ RecordJobTiming(startTime, endTime time.Time, id uuid.UUID, name string, tags []string)
+}
+
+// MonitorStatus extends RecordJobTiming with the job status.
+type MonitorStatus interface {
+ Monitor
+ // RecordJobTimingWithStatus will provide details about the job, its status, error and the timing and expects the underlying implementation
+ // to handle instantiating and recording the value
+ RecordJobTimingWithStatus(startTime, endTime time.Time, id uuid.UUID, name string, tags []string, status JobStatus, err error)
+}
diff --git a/vendor/github.com/go-co-op/gocron/v2/scheduler.go b/vendor/github.com/go-co-op/gocron/v2/scheduler.go
new file mode 100644
index 0000000..34cce9d
--- /dev/null
+++ b/vendor/github.com/go-co-op/gocron/v2/scheduler.go
@@ -0,0 +1,1027 @@
+//go:generate mockgen -destination=mocks/scheduler.go -package=gocronmocks . Scheduler
+package gocron
+
+import (
+ "context"
+ "reflect"
+ "runtime"
+ "slices"
+ "strings"
+ "time"
+
+ "github.com/google/uuid"
+ "github.com/jonboulle/clockwork"
+)
+
+var _ Scheduler = (*scheduler)(nil)
+
+// Scheduler defines the interface for the Scheduler.
+type Scheduler interface {
+ // Jobs returns all the jobs currently in the scheduler.
+ Jobs() []Job
+ // NewJob creates a new job in the Scheduler. The job is scheduled per the provided
+ // definition when the Scheduler is started. If the Scheduler is already running
+ // the job will be scheduled when the Scheduler is started.
+ // If you set the first argument of your Task func to be a context.Context,
+ // gocron will pass in a context (either the default Job context, or one
+ // provided via WithContext) to the job and will cancel the context on shutdown.
+ // This allows you to listen for and handle cancellation within your job.
+ NewJob(JobDefinition, Task, ...JobOption) (Job, error)
+ // RemoveByTags removes all jobs that have at least one of the provided tags.
+ RemoveByTags(...string)
+ // RemoveJob removes the job with the provided id.
+ RemoveJob(uuid.UUID) error
+ // Shutdown should be called when you no longer need
+ // the Scheduler or Job's as the Scheduler cannot
+ // be restarted after calling Shutdown. This is similar
+ // to a Close or Cleanup method and is often deferred after
+ // starting the scheduler.
+ Shutdown() error
+ // Start begins scheduling jobs for execution based
+ // on each job's definition. Job's added to an already
+ // running scheduler will be scheduled immediately based
+ // on definition. Start is non-blocking.
+ Start()
+ // StopJobs stops the execution of all jobs in the scheduler.
+ // This can be useful in situations where jobs need to be
+ // paused globally and then restarted with Start().
+ StopJobs() error
+ // Update replaces the existing Job's JobDefinition with the provided
+ // JobDefinition. The Job's Job.ID() remains the same.
+ Update(uuid.UUID, JobDefinition, Task, ...JobOption) (Job, error)
+ // JobsWaitingInQueue number of jobs waiting in Queue in case of LimitModeWait
+ // In case of LimitModeReschedule or no limit it will be always zero
+ JobsWaitingInQueue() int
+}
+
+// -----------------------------------------------
+// -----------------------------------------------
+// ----------------- Scheduler -------------------
+// -----------------------------------------------
+// -----------------------------------------------
+
+type scheduler struct {
+ // context used for shutting down
+ shutdownCtx context.Context
+ // cancel used to signal scheduler should shut down
+ shutdownCancel context.CancelFunc
+ // the executor, which actually runs the jobs sent to it via the scheduler
+ exec executor
+ // the map of jobs registered in the scheduler
+ jobs map[uuid.UUID]internalJob
+ // the location used by the scheduler for scheduling when relevant
+ location *time.Location
+ // whether the scheduler has been started or not
+ started bool
+ // globally applied JobOption's set on all jobs added to the scheduler
+ // note: individually set JobOption's take precedence.
+ globalJobOptions []JobOption
+ // the scheduler's logger
+ logger Logger
+
+ // used to tell the scheduler to start
+ startCh chan struct{}
+ // used to report that the scheduler has started
+ startedCh chan struct{}
+ // used to tell the scheduler to stop
+ stopCh chan struct{}
+ // used to report that the scheduler has stopped
+ stopErrCh chan error
+ // used to send all the jobs out when a request is made by the client
+ allJobsOutRequest chan allJobsOutRequest
+ // used to send a jobs out when a request is made by the client
+ jobOutRequestCh chan *jobOutRequest
+ // used to run a job on-demand when requested by the client
+ runJobRequestCh chan runJobRequest
+ // new jobs are received here
+ newJobCh chan newJobIn
+ // requests from the client to remove jobs by ID are received here
+ removeJobCh chan uuid.UUID
+ // requests from the client to remove jobs by tags are received here
+ removeJobsByTagsCh chan []string
+}
+
+type newJobIn struct {
+ ctx context.Context
+ cancel context.CancelFunc
+ job internalJob
+}
+
+type jobOutRequest struct {
+ id uuid.UUID
+ outChan chan internalJob
+}
+
+type runJobRequest struct {
+ id uuid.UUID
+ outChan chan error
+}
+
+type allJobsOutRequest struct {
+ outChan chan []Job
+}
+
+// NewScheduler creates a new Scheduler instance.
+// The Scheduler is not started until Start() is called.
+//
+// NewJob will add jobs to the Scheduler, but they will not
+// be scheduled until Start() is called.
+func NewScheduler(options ...SchedulerOption) (Scheduler, error) {
+ schCtx, cancel := context.WithCancel(context.Background())
+
+ exec := executor{
+ stopCh: make(chan struct{}),
+ stopTimeout: time.Second * 10,
+ singletonRunners: nil,
+ logger: &noOpLogger{},
+ clock: clockwork.NewRealClock(),
+
+ jobsIn: make(chan jobIn),
+ jobsOutForRescheduling: make(chan uuid.UUID),
+ jobUpdateNextRuns: make(chan uuid.UUID),
+ jobsOutCompleted: make(chan uuid.UUID),
+ jobOutRequest: make(chan *jobOutRequest, 100),
+ done: make(chan error, 1),
+ }
+
+ s := &scheduler{
+ shutdownCtx: schCtx,
+ shutdownCancel: cancel,
+ exec: exec,
+ jobs: make(map[uuid.UUID]internalJob),
+ location: time.Local,
+ logger: &noOpLogger{},
+
+ newJobCh: make(chan newJobIn),
+ removeJobCh: make(chan uuid.UUID),
+ removeJobsByTagsCh: make(chan []string),
+ startCh: make(chan struct{}),
+ startedCh: make(chan struct{}),
+ stopCh: make(chan struct{}),
+ stopErrCh: make(chan error, 1),
+ jobOutRequestCh: make(chan *jobOutRequest),
+ runJobRequestCh: make(chan runJobRequest),
+ allJobsOutRequest: make(chan allJobsOutRequest),
+ }
+
+ for _, option := range options {
+ err := option(s)
+ if err != nil {
+ return nil, err
+ }
+ }
+
+ go func() {
+ s.logger.Info("gocron: new scheduler created")
+ for {
+ select {
+ case id := <-s.exec.jobsOutForRescheduling:
+ s.selectExecJobsOutForRescheduling(id)
+ case id := <-s.exec.jobUpdateNextRuns:
+ s.updateNextScheduled(id)
+ case id := <-s.exec.jobsOutCompleted:
+ s.selectExecJobsOutCompleted(id)
+
+ case in := <-s.newJobCh:
+ s.selectNewJob(in)
+
+ case id := <-s.removeJobCh:
+ s.selectRemoveJob(id)
+
+ case tags := <-s.removeJobsByTagsCh:
+ s.selectRemoveJobsByTags(tags)
+
+ case out := <-s.exec.jobOutRequest:
+ s.selectJobOutRequest(out)
+
+ case out := <-s.jobOutRequestCh:
+ s.selectJobOutRequest(out)
+
+ case out := <-s.allJobsOutRequest:
+ s.selectAllJobsOutRequest(out)
+
+ case run := <-s.runJobRequestCh:
+ s.selectRunJobRequest(run)
+
+ case <-s.startCh:
+ s.selectStart()
+
+ case <-s.stopCh:
+ s.stopScheduler()
+
+ case <-s.shutdownCtx.Done():
+ s.stopScheduler()
+ return
+ }
+ }
+ }()
+
+ return s, nil
+}
+
+// -----------------------------------------------
+// -----------------------------------------------
+// --------- Scheduler Channel Methods -----------
+// -----------------------------------------------
+// -----------------------------------------------
+
+// The scheduler's channel functions are broken out here
+// to allow prioritizing within the select blocks. The idea
+// being that we want to make sure that scheduling tasks
+// are not blocked by requests from the caller for information
+// about jobs.
+
+func (s *scheduler) stopScheduler() {
+ s.logger.Debug("gocron: stopping scheduler")
+ if s.started {
+ s.exec.stopCh <- struct{}{}
+ }
+
+ for _, j := range s.jobs {
+ j.stop()
+ }
+ for _, j := range s.jobs {
+ <-j.ctx.Done()
+ }
+ var err error
+ if s.started {
+ t := time.NewTimer(s.exec.stopTimeout + 1*time.Second)
+ select {
+ case err = <-s.exec.done:
+ t.Stop()
+ case <-t.C:
+ err = ErrStopExecutorTimedOut
+ }
+ }
+ for id, j := range s.jobs {
+ oldCtx := j.ctx
+ if j.parentCtx == nil {
+ j.parentCtx = s.shutdownCtx
+ }
+ j.ctx, j.cancel = context.WithCancel(j.parentCtx)
+
+ // also replace the old context with the new one in the parameters
+ if len(j.parameters) > 0 && j.parameters[0] == oldCtx {
+ j.parameters[0] = j.ctx
+ }
+
+ s.jobs[id] = j
+ }
+
+ s.stopErrCh <- err
+ s.started = false
+ s.logger.Debug("gocron: scheduler stopped")
+}
+
+func (s *scheduler) selectAllJobsOutRequest(out allJobsOutRequest) {
+ outJobs := make([]Job, len(s.jobs))
+ var counter int
+ for _, j := range s.jobs {
+ outJobs[counter] = s.jobFromInternalJob(j)
+ counter++
+ }
+ slices.SortFunc(outJobs, func(a, b Job) int {
+ aID, bID := a.ID().String(), b.ID().String()
+ return strings.Compare(aID, bID)
+ })
+ select {
+ case <-s.shutdownCtx.Done():
+ case out.outChan <- outJobs:
+ }
+}
+
+func (s *scheduler) selectRunJobRequest(run runJobRequest) {
+ j, ok := s.jobs[run.id]
+ if !ok {
+ select {
+ case run.outChan <- ErrJobNotFound:
+ default:
+ }
+ return
+ }
+ select {
+ case <-s.shutdownCtx.Done():
+ select {
+ case run.outChan <- ErrJobRunNowFailed:
+ default:
+ }
+ case s.exec.jobsIn <- jobIn{
+ id: j.id,
+ shouldSendOut: false,
+ }:
+ select {
+ case run.outChan <- nil:
+ default:
+ }
+ }
+}
+
+func (s *scheduler) selectRemoveJob(id uuid.UUID) {
+ j, ok := s.jobs[id]
+ if !ok {
+ return
+ }
+ j.stop()
+ delete(s.jobs, id)
+}
+
+// Jobs coming back from the executor to the scheduler that
+// need to be evaluated for rescheduling.
+func (s *scheduler) selectExecJobsOutForRescheduling(id uuid.UUID) {
+ select {
+ case <-s.shutdownCtx.Done():
+ return
+ default:
+ }
+ j, ok := s.jobs[id]
+ if !ok {
+ // the job was removed while it was running, and
+ // so we don't need to reschedule it.
+ return
+ }
+
+ if j.stopTimeReached(s.now()) {
+ return
+ }
+
+ var scheduleFrom time.Time
+ if len(j.nextScheduled) > 0 {
+ // always grab the last element in the slice as that is the furthest
+ // out in the future and the time from which we want to calculate
+ // the subsequent next run time.
+ slices.SortStableFunc(j.nextScheduled, ascendingTime)
+ scheduleFrom = j.nextScheduled[len(j.nextScheduled)-1]
+ }
+
+ if scheduleFrom.IsZero() {
+ scheduleFrom = j.startTime
+ }
+
+ next := j.next(scheduleFrom)
+ if next.IsZero() {
+ // the job's next function will return zero for OneTime jobs.
+ // since they are one time only, they do not need rescheduling.
+ return
+ }
+
+ if next.Before(s.now()) {
+ // in some cases the next run time can be in the past, for example:
+ // - the time on the machine was incorrect and has been synced with ntp
+ // - the machine went to sleep, and woke up some time later
+ // in those cases, we want to increment to the next run in the future
+ // and schedule the job for that time.
+ for next.Before(s.now()) {
+ next = j.next(next)
+ }
+ }
+
+ if slices.Contains(j.nextScheduled, next) {
+ // if the next value is a duplicate of what's already in the nextScheduled slice, for example:
+ // - the job is being rescheduled off the same next run value as before
+ // increment to the next, next value
+ for slices.Contains(j.nextScheduled, next) {
+ next = j.next(next)
+ }
+ }
+
+ // Clean up any existing timer to prevent leaks
+ if j.timer != nil {
+ j.timer.Stop()
+ j.timer = nil // Ensure timer is cleared for GC
+ }
+
+ j.nextScheduled = append(j.nextScheduled, next)
+ j.timer = s.exec.clock.AfterFunc(next.Sub(s.now()), func() {
+ // set the actual timer on the job here and listen for
+ // shut down events so that the job doesn't attempt to
+ // run if the scheduler has been shutdown.
+ select {
+ case <-s.shutdownCtx.Done():
+ return
+ case s.exec.jobsIn <- jobIn{
+ id: j.id,
+ shouldSendOut: true,
+ }:
+ }
+ })
+ // update the job with its new next and last run times and timer.
+ s.jobs[id] = j
+}
+
+func (s *scheduler) updateNextScheduled(id uuid.UUID) {
+ j, ok := s.jobs[id]
+ if !ok {
+ return
+ }
+ var newNextScheduled []time.Time
+ for _, t := range j.nextScheduled {
+ if t.Before(s.now()) {
+ continue
+ }
+ newNextScheduled = append(newNextScheduled, t)
+ }
+ j.nextScheduled = newNextScheduled
+ s.jobs[id] = j
+}
+
+func (s *scheduler) selectExecJobsOutCompleted(id uuid.UUID) {
+ j, ok := s.jobs[id]
+ if !ok {
+ return
+ }
+
+ // if the job has nextScheduled time in the past,
+ // we need to remove any that are in the past.
+ var newNextScheduled []time.Time
+ for _, t := range j.nextScheduled {
+ if t.Before(s.now()) {
+ continue
+ }
+ newNextScheduled = append(newNextScheduled, t)
+ }
+ j.nextScheduled = newNextScheduled
+
+ // if the job has a limited number of runs set, we need to
+ // check how many runs have occurred and stop running this
+ // job if it has reached the limit.
+ if j.limitRunsTo != nil {
+ j.limitRunsTo.runCount = j.limitRunsTo.runCount + 1
+ if j.limitRunsTo.runCount == j.limitRunsTo.limit {
+ go func() {
+ select {
+ case <-s.shutdownCtx.Done():
+ return
+ case s.removeJobCh <- id:
+ }
+ }()
+ return
+ }
+ }
+
+ j.lastRun = s.now()
+ s.jobs[id] = j
+}
+
+func (s *scheduler) selectJobOutRequest(out *jobOutRequest) {
+ if j, ok := s.jobs[out.id]; ok {
+ select {
+ case out.outChan <- j:
+ case <-s.shutdownCtx.Done():
+ }
+ }
+ close(out.outChan)
+}
+
+func (s *scheduler) selectNewJob(in newJobIn) {
+ j := in.job
+ if s.started {
+ next := j.startTime
+ if j.startImmediately {
+ next = s.now()
+ select {
+ case <-s.shutdownCtx.Done():
+ case s.exec.jobsIn <- jobIn{
+ id: j.id,
+ shouldSendOut: true,
+ }:
+ }
+ } else {
+ if next.IsZero() {
+ next = j.next(s.now())
+ }
+
+ id := j.id
+ j.timer = s.exec.clock.AfterFunc(next.Sub(s.now()), func() {
+ select {
+ case <-s.shutdownCtx.Done():
+ case s.exec.jobsIn <- jobIn{
+ id: id,
+ shouldSendOut: true,
+ }:
+ }
+ })
+ }
+ j.startTime = next
+ j.nextScheduled = append(j.nextScheduled, next)
+ }
+
+ s.jobs[j.id] = j
+ in.cancel()
+}
+
+func (s *scheduler) selectRemoveJobsByTags(tags []string) {
+ for _, j := range s.jobs {
+ for _, tag := range tags {
+ if slices.Contains(j.tags, tag) {
+ j.stop()
+ delete(s.jobs, j.id)
+ break
+ }
+ }
+ }
+}
+
+func (s *scheduler) selectStart() {
+ s.logger.Debug("gocron: scheduler starting")
+ go s.exec.start()
+
+ s.started = true
+ for id, j := range s.jobs {
+ next := j.startTime
+ if j.startImmediately {
+ next = s.now()
+ select {
+ case <-s.shutdownCtx.Done():
+ case s.exec.jobsIn <- jobIn{
+ id: id,
+ shouldSendOut: true,
+ }:
+ }
+ } else {
+ if next.IsZero() {
+ next = j.next(s.now())
+ }
+
+ jobID := id
+ j.timer = s.exec.clock.AfterFunc(next.Sub(s.now()), func() {
+ select {
+ case <-s.shutdownCtx.Done():
+ case s.exec.jobsIn <- jobIn{
+ id: jobID,
+ shouldSendOut: true,
+ }:
+ }
+ })
+ }
+ j.startTime = next
+ j.nextScheduled = append(j.nextScheduled, next)
+ s.jobs[id] = j
+ }
+ select {
+ case <-s.shutdownCtx.Done():
+ case s.startedCh <- struct{}{}:
+ s.logger.Info("gocron: scheduler started")
+ }
+}
+
+// -----------------------------------------------
+// -----------------------------------------------
+// ------------- Scheduler Methods ---------------
+// -----------------------------------------------
+// -----------------------------------------------
+
+func (s *scheduler) now() time.Time {
+ return s.exec.clock.Now().In(s.location)
+}
+
+func (s *scheduler) jobFromInternalJob(in internalJob) job {
+ return job{
+ in.id,
+ in.name,
+ slices.Clone(in.tags),
+ s.jobOutRequestCh,
+ s.runJobRequestCh,
+ }
+}
+
+func (s *scheduler) Jobs() []Job {
+ outChan := make(chan []Job)
+ select {
+ case <-s.shutdownCtx.Done():
+ case s.allJobsOutRequest <- allJobsOutRequest{outChan: outChan}:
+ }
+
+ var jobs []Job
+ select {
+ case <-s.shutdownCtx.Done():
+ case jobs = <-outChan:
+ }
+
+ return jobs
+}
+
+func (s *scheduler) NewJob(jobDefinition JobDefinition, task Task, options ...JobOption) (Job, error) {
+ return s.addOrUpdateJob(uuid.Nil, jobDefinition, task, options)
+}
+
+func (s *scheduler) verifyInterfaceVariadic(taskFunc reflect.Value, tsk task, variadicStart int) error {
+ ifaceType := taskFunc.Type().In(variadicStart).Elem()
+ for i := variadicStart; i < len(tsk.parameters); i++ {
+ if !reflect.TypeOf(tsk.parameters[i]).Implements(ifaceType) {
+ return ErrNewJobWrongTypeOfParameters
+ }
+ }
+ return nil
+}
+
+func (s *scheduler) verifyVariadic(taskFunc reflect.Value, tsk task, variadicStart int) error {
+ if err := s.verifyNonVariadic(taskFunc, tsk, variadicStart); err != nil {
+ return err
+ }
+ parameterType := taskFunc.Type().In(variadicStart).Elem().Kind()
+ if parameterType == reflect.Interface {
+ return s.verifyInterfaceVariadic(taskFunc, tsk, variadicStart)
+ }
+ if parameterType == reflect.Pointer {
+ parameterType = reflect.Indirect(reflect.ValueOf(taskFunc.Type().In(variadicStart))).Kind()
+ }
+
+ for i := variadicStart; i < len(tsk.parameters); i++ {
+ argumentType := reflect.TypeOf(tsk.parameters[i]).Kind()
+ if argumentType == reflect.Interface || argumentType == reflect.Pointer {
+ argumentType = reflect.TypeOf(tsk.parameters[i]).Elem().Kind()
+ }
+ if argumentType != parameterType {
+ return ErrNewJobWrongTypeOfParameters
+ }
+ }
+ return nil
+}
+
+func (s *scheduler) verifyNonVariadic(taskFunc reflect.Value, tsk task, length int) error {
+ for i := 0; i < length; i++ {
+ t1 := reflect.TypeOf(tsk.parameters[i]).Kind()
+ if t1 == reflect.Interface || t1 == reflect.Pointer {
+ t1 = reflect.TypeOf(tsk.parameters[i]).Elem().Kind()
+ }
+ t2 := reflect.New(taskFunc.Type().In(i)).Elem().Kind()
+ if t2 == reflect.Interface || t2 == reflect.Pointer {
+ t2 = reflect.Indirect(reflect.ValueOf(taskFunc.Type().In(i))).Kind()
+ }
+ if t1 != t2 {
+ return ErrNewJobWrongTypeOfParameters
+ }
+ }
+ return nil
+}
+
+func (s *scheduler) verifyParameterType(taskFunc reflect.Value, tsk task) error {
+ isVariadic := taskFunc.Type().IsVariadic()
+ if isVariadic {
+ variadicStart := taskFunc.Type().NumIn() - 1
+ return s.verifyVariadic(taskFunc, tsk, variadicStart)
+ }
+ expectedParameterLength := taskFunc.Type().NumIn()
+ if len(tsk.parameters) != expectedParameterLength {
+ return ErrNewJobWrongNumberOfParameters
+ }
+ return s.verifyNonVariadic(taskFunc, tsk, expectedParameterLength)
+}
+
+func (s *scheduler) addOrUpdateJob(id uuid.UUID, definition JobDefinition, taskWrapper Task, options []JobOption) (Job, error) {
+ j := internalJob{}
+ if id == uuid.Nil {
+ j.id = uuid.New()
+ } else {
+ currentJob := requestJobCtx(s.shutdownCtx, id, s.jobOutRequestCh)
+ if currentJob != nil && currentJob.id != uuid.Nil {
+ select {
+ case <-s.shutdownCtx.Done():
+ return nil, nil
+ case s.removeJobCh <- id:
+ <-currentJob.ctx.Done()
+ }
+ }
+
+ j.id = id
+ }
+
+ if taskWrapper == nil {
+ return nil, ErrNewJobTaskNil
+ }
+
+ tsk := taskWrapper()
+ taskFunc := reflect.ValueOf(tsk.function)
+ for taskFunc.Kind() == reflect.Ptr {
+ taskFunc = taskFunc.Elem()
+ }
+
+ if taskFunc.Kind() != reflect.Func {
+ return nil, ErrNewJobTaskNotFunc
+ }
+
+ j.name = runtime.FuncForPC(taskFunc.Pointer()).Name()
+ j.function = tsk.function
+ j.parameters = tsk.parameters
+
+ // apply global job options
+ for _, option := range s.globalJobOptions {
+ if err := option(&j, s.now()); err != nil {
+ return nil, err
+ }
+ }
+
+ // apply job specific options, which take precedence
+ for _, option := range options {
+ if err := option(&j, s.now()); err != nil {
+ return nil, err
+ }
+ }
+
+ if j.parentCtx == nil {
+ j.parentCtx = s.shutdownCtx
+ }
+ j.ctx, j.cancel = context.WithCancel(j.parentCtx)
+
+ if !taskFunc.IsZero() && taskFunc.Type().NumIn() > 0 {
+ // if the first parameter is a context.Context and params have no context.Context, add current ctx to the params
+ if taskFunc.Type().In(0) == reflect.TypeOf((*context.Context)(nil)).Elem() {
+ if len(tsk.parameters) == 0 {
+ tsk.parameters = []any{j.ctx}
+ j.parameters = []any{j.ctx}
+ } else if _, ok := tsk.parameters[0].(context.Context); !ok {
+ tsk.parameters = append([]any{j.ctx}, tsk.parameters...)
+ j.parameters = append([]any{j.ctx}, j.parameters...)
+ }
+ }
+ }
+
+ if err := s.verifyParameterType(taskFunc, tsk); err != nil {
+ j.cancel()
+ return nil, err
+ }
+
+ if err := definition.setup(&j, s.location, s.exec.clock.Now()); err != nil {
+ j.cancel()
+ return nil, err
+ }
+
+ newJobCtx, newJobCancel := context.WithCancel(context.Background())
+ select {
+ case <-s.shutdownCtx.Done():
+ newJobCancel()
+ case s.newJobCh <- newJobIn{
+ ctx: newJobCtx,
+ cancel: newJobCancel,
+ job: j,
+ }:
+ }
+
+ select {
+ case <-newJobCtx.Done():
+ case <-s.shutdownCtx.Done():
+ newJobCancel()
+ }
+
+ out := s.jobFromInternalJob(j)
+ return &out, nil
+}
+
+func (s *scheduler) RemoveByTags(tags ...string) {
+ select {
+ case <-s.shutdownCtx.Done():
+ case s.removeJobsByTagsCh <- tags:
+ }
+}
+
+func (s *scheduler) RemoveJob(id uuid.UUID) error {
+ j := requestJobCtx(s.shutdownCtx, id, s.jobOutRequestCh)
+ if j == nil || j.id == uuid.Nil {
+ return ErrJobNotFound
+ }
+ select {
+ case <-s.shutdownCtx.Done():
+ case s.removeJobCh <- id:
+ }
+
+ return nil
+}
+
+func (s *scheduler) Start() {
+ select {
+ case <-s.shutdownCtx.Done():
+ case s.startCh <- struct{}{}:
+ <-s.startedCh
+ }
+}
+
+func (s *scheduler) StopJobs() error {
+ select {
+ case <-s.shutdownCtx.Done():
+ return nil
+ case s.stopCh <- struct{}{}:
+ }
+
+ t := time.NewTimer(s.exec.stopTimeout + 2*time.Second)
+ select {
+ case err := <-s.stopErrCh:
+ t.Stop()
+ return err
+ case <-t.C:
+ return ErrStopSchedulerTimedOut
+ }
+}
+
+func (s *scheduler) Shutdown() error {
+ s.shutdownCancel()
+
+ t := time.NewTimer(s.exec.stopTimeout + 2*time.Second)
+ select {
+ case err := <-s.stopErrCh:
+
+ t.Stop()
+ return err
+ case <-t.C:
+ return ErrStopSchedulerTimedOut
+ }
+}
+
+func (s *scheduler) Update(id uuid.UUID, jobDefinition JobDefinition, task Task, options ...JobOption) (Job, error) {
+ return s.addOrUpdateJob(id, jobDefinition, task, options)
+}
+
+func (s *scheduler) JobsWaitingInQueue() int {
+ if s.exec.limitMode != nil && s.exec.limitMode.mode == LimitModeWait {
+ return len(s.exec.limitMode.in)
+ }
+ return 0
+}
+
+// -----------------------------------------------
+// -----------------------------------------------
+// ------------- Scheduler Options ---------------
+// -----------------------------------------------
+// -----------------------------------------------
+
+// SchedulerOption defines the function for setting
+// options on the Scheduler.
+type SchedulerOption func(*scheduler) error
+
+// WithClock sets the clock used by the Scheduler
+// to the clock provided. See https://github.com/jonboulle/clockwork
+func WithClock(clock clockwork.Clock) SchedulerOption {
+ return func(s *scheduler) error {
+ if clock == nil {
+ return ErrWithClockNil
+ }
+ s.exec.clock = clock
+ return nil
+ }
+}
+
+// WithDistributedElector sets the elector to be used by multiple
+// Scheduler instances to determine who should be the leader.
+// Only the leader runs jobs, while non-leaders wait and continue
+// to check if a new leader has been elected.
+func WithDistributedElector(elector Elector) SchedulerOption {
+ return func(s *scheduler) error {
+ if elector == nil {
+ return ErrWithDistributedElectorNil
+ }
+ s.exec.elector = elector
+ return nil
+ }
+}
+
+// WithDistributedLocker sets the locker to be used by multiple
+// Scheduler instances to ensure that only one instance of each
+// job is run.
+// To disable this global locker for specific jobs, see
+// WithDisabledDistributedJobLocker.
+func WithDistributedLocker(locker Locker) SchedulerOption {
+ return func(s *scheduler) error {
+ if locker == nil {
+ return ErrWithDistributedLockerNil
+ }
+ s.exec.locker = locker
+ return nil
+ }
+}
+
+// WithGlobalJobOptions sets JobOption's that will be applied to
+// all jobs added to the scheduler. JobOption's set on the job
+// itself will override if the same JobOption is set globally.
+func WithGlobalJobOptions(jobOptions ...JobOption) SchedulerOption {
+ return func(s *scheduler) error {
+ s.globalJobOptions = jobOptions
+ return nil
+ }
+}
+
+// LimitMode defines the modes used for handling jobs that reach
+// the limit provided in WithLimitConcurrentJobs
+type LimitMode int
+
+const (
+ // LimitModeReschedule causes jobs reaching the limit set in
+ // WithLimitConcurrentJobs or WithSingletonMode to be skipped
+ // and rescheduled for the next run time rather than being
+ // queued up to wait.
+ LimitModeReschedule = 1
+
+ // LimitModeWait causes jobs reaching the limit set in
+ // WithLimitConcurrentJobs or WithSingletonMode to wait
+ // in a queue until a slot becomes available to run.
+ //
+ // Note: this mode can produce unpredictable results as
+ // job execution order isn't guaranteed. For example, a job that
+ // executes frequently may pile up in the wait queue and be executed
+ // many times back to back when the queue opens.
+ //
+ // Warning: do not use this mode if your jobs will continue to stack
+ // up beyond the ability of the limit workers to keep up. An example of
+ // what NOT to do:
+ //
+ // s, _ := gocron.NewScheduler(gocron.WithLimitConcurrentJobs)
+ // s.NewJob(
+ // gocron.DurationJob(
+ // time.Second,
+ // Task{
+ // Function: func() {
+ // time.Sleep(10 * time.Second)
+ // },
+ // },
+ // ),
+ // )
+ LimitModeWait = 2
+)
+
+// WithLimitConcurrentJobs sets the limit and mode to be used by the
+// Scheduler for limiting the number of jobs that may be running at
+// a given time.
+//
+// Note: the limit mode selected for WithLimitConcurrentJobs takes initial
+// precedence in the event you are also running a limit mode at the job level
+// using WithSingletonMode.
+//
+// Warning: a single time consuming job can dominate your limit in the event
+// you are running both the scheduler limit WithLimitConcurrentJobs(1, LimitModeWait)
+// and a job limit WithSingletonMode(LimitModeReschedule).
+func WithLimitConcurrentJobs(limit uint, mode LimitMode) SchedulerOption {
+ return func(s *scheduler) error {
+ if limit == 0 {
+ return ErrWithLimitConcurrentJobsZero
+ }
+ s.exec.limitMode = &limitModeConfig{
+ mode: mode,
+ limit: limit,
+ in: make(chan jobIn, 1000),
+ singletonJobs: make(map[uuid.UUID]struct{}),
+ }
+ if mode == LimitModeReschedule {
+ s.exec.limitMode.rescheduleLimiter = make(chan struct{}, limit)
+ }
+ return nil
+ }
+}
+
+// WithLocation sets the location (i.e. timezone) that the scheduler
+// should operate within. In many systems time.Local is UTC.
+// Default: time.Local
+func WithLocation(location *time.Location) SchedulerOption {
+ return func(s *scheduler) error {
+ if location == nil {
+ return ErrWithLocationNil
+ }
+ s.location = location
+ return nil
+ }
+}
+
+// WithLogger sets the logger to be used by the Scheduler.
+func WithLogger(logger Logger) SchedulerOption {
+ return func(s *scheduler) error {
+ if logger == nil {
+ return ErrWithLoggerNil
+ }
+ s.logger = logger
+ s.exec.logger = logger
+ return nil
+ }
+}
+
+// WithStopTimeout sets the amount of time the Scheduler should
+// wait gracefully for jobs to complete before returning when
+// StopJobs() or Shutdown() are called.
+// Default: 10 * time.Second
+func WithStopTimeout(timeout time.Duration) SchedulerOption {
+ return func(s *scheduler) error {
+ if timeout <= 0 {
+ return ErrWithStopTimeoutZeroOrNegative
+ }
+ s.exec.stopTimeout = timeout
+ return nil
+ }
+}
+
+// WithMonitor sets the metrics provider to be used by the Scheduler.
+func WithMonitor(monitor Monitor) SchedulerOption {
+ return func(s *scheduler) error {
+ if monitor == nil {
+ return ErrWithMonitorNil
+ }
+ s.exec.monitor = monitor
+ return nil
+ }
+}
+
+// WithMonitorStatus sets the metrics provider to be used by the Scheduler.
+func WithMonitorStatus(monitor MonitorStatus) SchedulerOption {
+ return func(s *scheduler) error {
+ if monitor == nil {
+ return ErrWithMonitorNil
+ }
+ s.exec.monitorStatus = monitor
+ return nil
+ }
+}
diff --git a/vendor/github.com/go-co-op/gocron/v2/util.go b/vendor/github.com/go-co-op/gocron/v2/util.go
new file mode 100644
index 0000000..282463a
--- /dev/null
+++ b/vendor/github.com/go-co-op/gocron/v2/util.go
@@ -0,0 +1,113 @@
+package gocron
+
+import (
+ "context"
+ "reflect"
+ "slices"
+ "sync"
+ "time"
+
+ "github.com/google/uuid"
+)
+
+func callJobFuncWithParams(jobFunc any, params ...any) error {
+ if jobFunc == nil {
+ return nil
+ }
+ f := reflect.ValueOf(jobFunc)
+ if f.IsZero() {
+ return nil
+ }
+ if len(params) != f.Type().NumIn() {
+ return nil
+ }
+ in := make([]reflect.Value, len(params))
+ for k, param := range params {
+ in[k] = reflect.ValueOf(param)
+ }
+ returnValues := f.Call(in)
+ for _, val := range returnValues {
+ i := val.Interface()
+ if err, ok := i.(error); ok {
+ return err
+ }
+ }
+ return nil
+}
+
+func requestJob(id uuid.UUID, ch chan *jobOutRequest) *internalJob {
+ ctx, cancel := context.WithTimeout(context.Background(), time.Second)
+ defer cancel()
+ return requestJobCtx(ctx, id, ch)
+}
+
+func requestJobCtx(ctx context.Context, id uuid.UUID, ch chan *jobOutRequest) *internalJob {
+ resp := make(chan internalJob, 1)
+ select {
+ case ch <- &jobOutRequest{
+ id: id,
+ outChan: resp,
+ }:
+ case <-ctx.Done():
+ return nil
+ }
+ var j internalJob
+ select {
+ case <-ctx.Done():
+ return nil
+ case jobReceived := <-resp:
+ j = jobReceived
+ }
+ return &j
+}
+
+func removeSliceDuplicatesInt(in []int) []int {
+ slices.Sort(in)
+ return slices.Compact(in)
+}
+
+func convertAtTimesToDateTime(atTimes AtTimes, location *time.Location) ([]time.Time, error) {
+ if atTimes == nil {
+ return nil, errAtTimesNil
+ }
+ var atTimesDate []time.Time
+ for _, a := range atTimes() {
+ if a == nil {
+ return nil, errAtTimeNil
+ }
+ at := a()
+ if at.hours > 23 {
+ return nil, errAtTimeHours
+ } else if at.minutes > 59 || at.seconds > 59 {
+ return nil, errAtTimeMinSec
+ }
+ atTimesDate = append(atTimesDate, at.time(location))
+ }
+ slices.SortStableFunc(atTimesDate, ascendingTime)
+ return atTimesDate, nil
+}
+
+func ascendingTime(a, b time.Time) int {
+ return a.Compare(b)
+}
+
+type waitGroupWithMutex struct {
+ wg sync.WaitGroup
+ mu sync.Mutex
+}
+
+func (w *waitGroupWithMutex) Add(delta int) {
+ w.mu.Lock()
+ defer w.mu.Unlock()
+ w.wg.Add(delta)
+}
+
+func (w *waitGroupWithMutex) Done() {
+ w.wg.Done()
+}
+
+func (w *waitGroupWithMutex) Wait() {
+ w.mu.Lock()
+ defer w.mu.Unlock()
+ w.wg.Wait()
+}
diff --git a/vendor/github.com/gofiber/fiber/v2/.editorconfig b/vendor/github.com/gofiber/fiber/v2/.editorconfig
new file mode 100644
index 0000000..6a4ec76
--- /dev/null
+++ b/vendor/github.com/gofiber/fiber/v2/.editorconfig
@@ -0,0 +1,8 @@
+; This file is for unifying the coding style for different editors and IDEs.
+; More information at http://editorconfig.org
+; This style originates from https://github.com/fewagency/best-practices
+root = true
+
+[*]
+charset = utf-8
+end_of_line = lf
diff --git a/vendor/github.com/gofiber/fiber/v2/.gitattributes b/vendor/github.com/gofiber/fiber/v2/.gitattributes
new file mode 100644
index 0000000..963a68e
--- /dev/null
+++ b/vendor/github.com/gofiber/fiber/v2/.gitattributes
@@ -0,0 +1,12 @@
+# Handle line endings automatically for files detected as text
+# and leave all files detected as binary untouched.
+* text=auto eol=lf
+
+# Force batch scripts to always use CRLF line endings so that if a repo is accessed
+# in Windows via a file share from Linux, the scripts will work.
+*.{cmd,[cC][mM][dD]} text eol=crlf
+*.{bat,[bB][aA][tT]} text eol=crlf
+
+# Force bash scripts to always use LF line endings so that if a repo is accessed
+# in Unix via a file share from Windows, the scripts will work.
+*.sh text eol=lf
diff --git a/vendor/github.com/gofiber/fiber/v2/.gitignore b/vendor/github.com/gofiber/fiber/v2/.gitignore
new file mode 100644
index 0000000..119b111
--- /dev/null
+++ b/vendor/github.com/gofiber/fiber/v2/.gitignore
@@ -0,0 +1,30 @@
+# Binaries for programs and plugins
+*.exe
+*.exe~
+*.dll
+*.so
+*.dylib
+
+# Test binary, built with `go test -c`
+*.test
+*.tmp
+
+# Output of the go coverage tool, specifically when used with LiteIDE
+*.out
+
+# IDE files
+.vscode
+.DS_Store
+.idea
+
+# Misc
+*.fiber.gz
+*.fasthttp.gz
+*.pprof
+*.workspace
+
+# Dependencies
+/vendor/
+vendor/
+vendor
+/Godeps/
\ No newline at end of file
diff --git a/vendor/github.com/gofiber/fiber/v2/.golangci.yml b/vendor/github.com/gofiber/fiber/v2/.golangci.yml
new file mode 100644
index 0000000..88919e8
--- /dev/null
+++ b/vendor/github.com/gofiber/fiber/v2/.golangci.yml
@@ -0,0 +1,204 @@
+# Created based on v1.51.0
+# NOTE: Keep this in sync with the version in .github/workflows/linter.yml
+
+run:
+ modules-download-mode: readonly
+ skip-dirs-use-default: false
+ skip-dirs:
+ - internal
+
+output:
+ sort-results: true
+
+linters-settings:
+ errcheck:
+ check-type-assertions: true
+ check-blank: true
+ disable-default-exclusions: true
+ exclude-functions:
+ - '(*bytes.Buffer).Write' # always returns nil error
+ - '(*github.com/valyala/bytebufferpool.ByteBuffer).Write' # always returns nil error
+ - '(*github.com/valyala/bytebufferpool.ByteBuffer).WriteByte' # always returns nil error
+ - '(*github.com/valyala/bytebufferpool.ByteBuffer).WriteString' # always returns nil error
+
+ errchkjson:
+ report-no-exported: true
+
+ exhaustive:
+ default-signifies-exhaustive: true
+
+ forbidigo:
+ forbid:
+ - ^(fmt\.Print(|f|ln)|print|println)$
+ - 'http\.Default(Client|Transport)'
+ # TODO: Eventually enable these patterns
+ # - 'time\.Sleep'
+ # - 'panic'
+
+ gocritic:
+ disabled-checks:
+ - ifElseChain
+
+ gofumpt:
+ module-path: github.com/gofiber/fiber
+ extra-rules: true
+
+ gosec:
+ excludes:
+ - G104 # TODO: Enable this again. Mostly provided by errcheck
+ config:
+ global:
+ audit: true
+
+ govet:
+ check-shadowing: true
+ enable-all: true
+ disable:
+ - shadow
+ - fieldalignment
+ - loopclosure
+
+ grouper:
+ import-require-single-import: true
+ import-require-grouping: true
+
+ misspell:
+ locale: US
+
+ nolintlint:
+ require-explanation: true
+ require-specific: true
+
+ nonamedreturns:
+ report-error-in-defer: true
+
+ predeclared:
+ q: true
+
+ promlinter:
+ strict: true
+
+ revive:
+ enable-all-rules: true
+ rules:
+ # Provided by gomnd linter
+ - name: add-constant
+ disabled: true
+ - name: argument-limit
+ disabled: true
+ # Provided by bidichk
+ - name: banned-characters
+ disabled: true
+ - name: cognitive-complexity
+ disabled: true
+ - name: cyclomatic
+ disabled: true
+ - name: early-return
+ severity: warning
+ disabled: true
+ - name: exported
+ disabled: true
+ - name: file-header
+ disabled: true
+ - name: function-result-limit
+ disabled: true
+ - name: function-length
+ disabled: true
+ - name: line-length-limit
+ disabled: true
+ - name: max-public-structs
+ disabled: true
+ - name: modifies-parameter
+ disabled: true
+ - name: nested-structs
+ disabled: true
+ - name: package-comments
+ disabled: true
+
+ stylecheck:
+ checks:
+ - all
+ - -ST1000
+ - -ST1020
+ - -ST1021
+ - -ST1022
+
+ tagliatelle:
+ case:
+ rules:
+ json: snake
+
+ #tenv:
+ # all: true
+
+ #unparam:
+ # check-exported: true
+
+ wrapcheck:
+ ignorePackageGlobs:
+ - github.com/gofiber/fiber/*
+ - github.com/valyala/fasthttp
+
+issues:
+ exclude-use-default: false
+
+linters:
+ enable:
+ - asasalint
+ - asciicheck
+ - bidichk
+ - bodyclose
+ - containedctx
+ - contextcheck
+ - depguard
+ - dogsled
+ - durationcheck
+ - errcheck
+ - errchkjson
+ - errname
+ - errorlint
+ - execinquery
+ - exhaustive
+ - exportloopref
+ - forbidigo
+ - forcetypeassert
+ - goconst
+ - gocritic
+ - gofmt
+ - gofumpt
+ - goimports
+ - gomoddirectives
+ - goprintffuncname
+ - gosec
+ - gosimple
+ - govet
+ - grouper
+ - loggercheck
+ - misspell
+ - nakedret
+ - nilerr
+ - nilnil
+ - noctx
+ - nolintlint
+ - nonamedreturns
+ - nosprintfhostport
+ - predeclared
+ - promlinter
+ - reassign
+ - revive
+ - rowserrcheck
+ - sqlclosecheck
+ - staticcheck
+ - stylecheck
+ - tagliatelle
+ # - testpackage # TODO: Enable once https://github.com/gofiber/fiber/issues/2252 is implemented
+ - thelper
+ # - tparallel # TODO: Enable once https://github.com/gofiber/fiber/issues/2254 is implemented
+ - typecheck
+ - unconvert
+ - unparam
+ - unused
+ - usestdlibvars
+ - wastedassign
+ - whitespace
+ - wrapcheck
diff --git a/vendor/github.com/gofiber/fiber/v2/AGENTS.md b/vendor/github.com/gofiber/fiber/v2/AGENTS.md
new file mode 100644
index 0000000..4b23d8d
--- /dev/null
+++ b/vendor/github.com/gofiber/fiber/v2/AGENTS.md
@@ -0,0 +1,44 @@
+# AGENTS.md
+
+## Agent Instructions
+
+> **Note for the AI agent:** Before running the startup script, verify that all dependencies and CLI tools are already available. If a `vendor/` directory exists **or** `go list -m -mod=readonly all` succeeds (indicating modules are cached), you may skip the entire startup script—including all `go mod` commands and `go install` steps. Otherwise run the script as listed below.
+
+---
+
+## Startup script (reference only – do not run)
+
+- Fetch dependencies:
+
+ ```bash
+ go mod tidy && go mod download && go mod vendor
+ ```
+
+- Install CLI tools referenced in Makefile:
+
+ ```bash
+ go install gotest.tools/gotestsum@latest # test runner
+ go install golang.org/x/vuln/cmd/govulncheck@latest # vulnerability scanner
+ go install mvdan.cc/gofumpt@latest # code formatter
+ go install github.com/tinylib/msgp@latest # msgp codegen
+ go install github.com/vburenin/ifacemaker@975a95966976eeb2d4365a7fb236e274c54da64c # interface impls
+ go install github.com/dkorunic/betteralign/cmd/betteralign@latest # struct alignment
+ go mod tidy # clean up go.mod & go.sum
+ ```
+
+## Makefile commands
+
+Use `make help` to list all available commands. Common targets include:
+
+- **audit**: run `go mod verify`, `go vet`, and `govulncheck` for quality checks.
+- **benchmark**: run benchmarks with `go test`.
+- **coverage**: generate a coverage report.
+- **format**: apply formatting using `gofumpt`.
+- **lint**: execute `golangci-lint`.
+- **test**: run the test suite with `gotestsum`.
+- **longtest**: run the test suite 15 times with shuffling enabled.
+- **tidy**: clean and tidy dependencies.
+- **betteralign**: optimize struct field alignment.
+- **generate**: run `go generate` after installing msgp and ifacemaker.
+
+These targets can be invoked via `make " + b + "
") + case "json": + return c.JSON(body) + case "txt": + return c.SendString(b) + case "xml": + return c.XML(body) + } + return c.SendString(b) +} + +// FormFile returns the first file by key from a MultipartForm. +func (c *Ctx) FormFile(key string) (*multipart.FileHeader, error) { + return c.fasthttp.FormFile(key) +} + +// FormValue returns the first value by key from a MultipartForm. +// Search is performed in QueryArgs, PostArgs, MultipartForm and FormFile in this particular order. +// Defaults to the empty string "" if the form value doesn't exist. +// If a default value is given, it will return that value if the form value does not exist. +// Returned value is only valid within the handler. Do not store any references. +// Make copies or use the Immutable setting instead. +func (c *Ctx) FormValue(key string, defaultValue ...string) string { + return defaultString(c.app.getString(c.fasthttp.FormValue(key)), defaultValue) +} + +// Fresh returns true when the response is still “fresh” in the client's cache, +// otherwise false is returned to indicate that the client cache is now stale +// and the full response should be sent. +// When a client sends the Cache-Control: no-cache request header to indicate an end-to-end +// reload request, this module will return false to make handling these requests transparent. +// https://github.com/jshttp/fresh/blob/10e0471669dbbfbfd8de65bc6efac2ddd0bfa057/index.js#L33 +func (c *Ctx) Fresh() bool { + // fields + modifiedSince := c.Get(HeaderIfModifiedSince) + noneMatch := c.Get(HeaderIfNoneMatch) + + // unconditional request + if modifiedSince == "" && noneMatch == "" { + return false + } + + // Always return stale when Cache-Control: no-cache + // to support end-to-end reload requests + // https://tools.ietf.org/html/rfc2616#section-14.9.4 + cacheControl := c.Get(HeaderCacheControl) + if cacheControl != "" && isNoCache(cacheControl) { + return false + } + + // if-none-match + if noneMatch != "" && noneMatch != "*" { + etag := c.app.getString(c.fasthttp.Response.Header.Peek(HeaderETag)) + if etag == "" { + return false + } + if c.app.isEtagStale(etag, c.app.getBytes(noneMatch)) { + return false + } + + if modifiedSince != "" { + lastModified := c.app.getString(c.fasthttp.Response.Header.Peek(HeaderLastModified)) + if lastModified != "" { + lastModifiedTime, err := http.ParseTime(lastModified) + if err != nil { + return false + } + modifiedSinceTime, err := http.ParseTime(modifiedSince) + if err != nil { + return false + } + return lastModifiedTime.Before(modifiedSinceTime) + } + } + } + return true +} + +// Get returns the HTTP request header specified by field. +// Field names are case-insensitive +// Returned value is only valid within the handler. Do not store any references. +// Make copies or use the Immutable setting instead. +func (c *Ctx) Get(key string, defaultValue ...string) string { + return defaultString(c.app.getString(c.fasthttp.Request.Header.Peek(key)), defaultValue) +} + +// GetRespHeader returns the HTTP response header specified by field. +// Field names are case-insensitive +// Returned value is only valid within the handler. Do not store any references. +// Make copies or use the Immutable setting instead. +func (c *Ctx) GetRespHeader(key string, defaultValue ...string) string { + return defaultString(c.app.getString(c.fasthttp.Response.Header.Peek(key)), defaultValue) +} + +// GetReqHeaders returns the HTTP request headers. +// Returned value is only valid within the handler. Do not store any references. +// Make copies or use the Immutable setting instead. +func (c *Ctx) GetReqHeaders() map[string][]string { + headers := make(map[string][]string) + c.Request().Header.VisitAll(func(k, v []byte) { + key := c.app.getString(k) + headers[key] = append(headers[key], c.app.getString(v)) + }) + + return headers +} + +// GetRespHeaders returns the HTTP response headers. +// Returned value is only valid within the handler. Do not store any references. +// Make copies or use the Immutable setting instead. +func (c *Ctx) GetRespHeaders() map[string][]string { + headers := make(map[string][]string) + c.Response().Header.VisitAll(func(k, v []byte) { + key := c.app.getString(k) + headers[key] = append(headers[key], c.app.getString(v)) + }) + + return headers +} + +// Hostname contains the hostname derived from the X-Forwarded-Host or Host HTTP header. +// Returned value is only valid within the handler. Do not store any references. +// Make copies or use the Immutable setting instead. +// Please use Config.EnableTrustedProxyCheck to prevent header spoofing, in case when your app is behind the proxy. +func (c *Ctx) Hostname() string { + if c.IsProxyTrusted() { + if host := c.Get(HeaderXForwardedHost); len(host) > 0 { + commaPos := strings.Index(host, ",") + if commaPos != -1 { + return host[:commaPos] + } + return host + } + } + return c.app.getString(c.fasthttp.Request.URI().Host()) +} + +// Port returns the remote port of the request. +func (c *Ctx) Port() string { + tcpaddr, ok := c.fasthttp.RemoteAddr().(*net.TCPAddr) + if !ok { + panic(fmt.Errorf("failed to type-assert to *net.TCPAddr")) + } + return strconv.Itoa(tcpaddr.Port) +} + +// IP returns the remote IP address of the request. +// If ProxyHeader and IP Validation is configured, it will parse that header and return the first valid IP address. +// Please use Config.EnableTrustedProxyCheck to prevent header spoofing, in case when your app is behind the proxy. +func (c *Ctx) IP() string { + if c.IsProxyTrusted() && len(c.app.config.ProxyHeader) > 0 { + return c.extractIPFromHeader(c.app.config.ProxyHeader) + } + + return c.fasthttp.RemoteIP().String() +} + +// extractIPsFromHeader will return a slice of IPs it found given a header name in the order they appear. +// When IP validation is enabled, any invalid IPs will be omitted. +func (c *Ctx) extractIPsFromHeader(header string) []string { + // TODO: Reuse the c.extractIPFromHeader func somehow in here + + headerValue := c.Get(header) + + // We can't know how many IPs we will return, but we will try to guess with this constant division. + // Counting ',' makes function slower for about 50ns in general case. + const maxEstimatedCount = 8 + estimatedCount := len(headerValue) / maxEstimatedCount + if estimatedCount > maxEstimatedCount { + estimatedCount = maxEstimatedCount // Avoid big allocation on big header + } + + ipsFound := make([]string, 0, estimatedCount) + + i := 0 + j := -1 + +iploop: + for { + var v4, v6 bool + + // Manually splitting string without allocating slice, working with parts directly + i, j = j+1, j+2 + + if j > len(headerValue) { + break + } + + for j < len(headerValue) && headerValue[j] != ',' { + if headerValue[j] == ':' { + v6 = true + } else if headerValue[j] == '.' { + v4 = true + } + j++ + } + + for i < j && (headerValue[i] == ' ' || headerValue[i] == ',') { + i++ + } + + s := utils.TrimRight(headerValue[i:j], ' ') + + if c.app.config.EnableIPValidation { + // Skip validation if IP is clearly not IPv4/IPv6, otherwise validate without allocations + if (!v6 && !v4) || (v6 && !utils.IsIPv6(s)) || (v4 && !utils.IsIPv4(s)) { + continue iploop + } + } + + ipsFound = append(ipsFound, s) + } + + return ipsFound +} + +// extractIPFromHeader will attempt to pull the real client IP from the given header when IP validation is enabled. +// currently, it will return the first valid IP address in header. +// when IP validation is disabled, it will simply return the value of the header without any inspection. +// Implementation is almost the same as in extractIPsFromHeader, but without allocation of []string. +func (c *Ctx) extractIPFromHeader(header string) string { + if c.app.config.EnableIPValidation { + headerValue := c.Get(header) + + i := 0 + j := -1 + + iploop: + for { + var v4, v6 bool + + // Manually splitting string without allocating slice, working with parts directly + i, j = j+1, j+2 + + if j > len(headerValue) { + break + } + + for j < len(headerValue) && headerValue[j] != ',' { + if headerValue[j] == ':' { + v6 = true + } else if headerValue[j] == '.' { + v4 = true + } + j++ + } + + for i < j && headerValue[i] == ' ' { + i++ + } + + s := utils.TrimRight(headerValue[i:j], ' ') + + if c.app.config.EnableIPValidation { + if (!v6 && !v4) || (v6 && !utils.IsIPv6(s)) || (v4 && !utils.IsIPv4(s)) { + continue iploop + } + } + + return s + } + + return c.fasthttp.RemoteIP().String() + } + + // default behavior if IP validation is not enabled is just to return whatever value is + // in the proxy header. Even if it is empty or invalid + return c.Get(c.app.config.ProxyHeader) +} + +// IPs returns a string slice of IP addresses specified in the X-Forwarded-For request header. +// When IP validation is enabled, only valid IPs are returned. +func (c *Ctx) IPs() []string { + return c.extractIPsFromHeader(HeaderXForwardedFor) +} + +// Is returns the matching content type, +// if the incoming request's Content-Type HTTP header field matches the MIME type specified by the type parameter +func (c *Ctx) Is(extension string) bool { + extensionHeader := utils.GetMIME(extension) + if extensionHeader == "" { + return false + } + + ct := c.app.getString(c.fasthttp.Request.Header.ContentType()) + if i := strings.IndexByte(ct, ';'); i != -1 { + ct = ct[:i] + } + ct = utils.Trim(ct, ' ') + return utils.EqualFold(ct, extensionHeader) +} + +// JSON converts any interface or string to JSON. +// Array and slice values encode as JSON arrays, +// except that []byte encodes as a base64-encoded string, +// and a nil slice encodes as the null JSON value. +// If the ctype parameter is given, this method will set the +// Content-Type header equal to ctype. If ctype is not given, +// The Content-Type header will be set to application/json. +func (c *Ctx) JSON(data interface{}, ctype ...string) error { + raw, err := c.app.config.JSONEncoder(data) + if err != nil { + return err + } + c.fasthttp.Response.SetBodyRaw(raw) + if len(ctype) > 0 { + c.fasthttp.Response.Header.SetContentType(ctype[0]) + } else { + c.fasthttp.Response.Header.SetContentType(MIMEApplicationJSON) + } + return nil +} + +// JSONP sends a JSON response with JSONP support. +// This method is identical to JSON, except that it opts-in to JSONP callback support. +// By default, the callback name is simply callback. +func (c *Ctx) JSONP(data interface{}, callback ...string) error { + raw, err := c.app.config.JSONEncoder(data) + if err != nil { + return err + } + + var result, cb string + + if len(callback) > 0 { + cb = callback[0] + } else { + cb = "callback" + } + + result = cb + "(" + c.app.getString(raw) + ");" + + c.setCanonical(HeaderXContentTypeOptions, "nosniff") + c.fasthttp.Response.Header.SetContentType(MIMETextJavaScriptCharsetUTF8) + return c.SendString(result) +} + +// XML converts any interface or string to XML. +// This method also sets the content header to application/xml. +func (c *Ctx) XML(data interface{}) error { + raw, err := c.app.config.XMLEncoder(data) + if err != nil { + return err + } + c.fasthttp.Response.SetBodyRaw(raw) + c.fasthttp.Response.Header.SetContentType(MIMEApplicationXML) + return nil +} + +// Links joins the links followed by the property to populate the response's Link HTTP header field. +func (c *Ctx) Links(link ...string) { + if len(link) == 0 { + return + } + bb := bytebufferpool.Get() + for i := range link { + if i%2 == 0 { + _ = bb.WriteByte('<') + _, _ = bb.WriteString(link[i]) + _ = bb.WriteByte('>') + } else { + _, _ = bb.WriteString(`; rel="` + link[i] + `",`) + } + } + c.setCanonical(HeaderLink, utils.TrimRight(c.app.getString(bb.Bytes()), ',')) + bytebufferpool.Put(bb) +} + +// Locals makes it possible to pass interface{} values under keys scoped to the request +// and therefore available to all following routes that match the request. +// +// All the values are removed from ctx after returning from the top +// RequestHandler. Additionally, Close method is called on each value +// implementing io.Closer before removing the value from ctx. +func (c *Ctx) Locals(key interface{}, value ...interface{}) interface{} { + if len(value) == 0 { + return c.fasthttp.UserValue(key) + } + c.fasthttp.SetUserValue(key, value[0]) + return value[0] +} + +// Location sets the response Location HTTP header to the specified path parameter. +func (c *Ctx) Location(path string) { + c.setCanonical(HeaderLocation, path) +} + +// Method returns the HTTP request method for the context, optionally overridden by the provided argument. +// If no override is given or if the provided override is not a valid HTTP method, it returns the current method from the context. +// Otherwise, it updates the context's method and returns the overridden method as a string. +func (c *Ctx) Method(override ...string) string { + if len(override) == 0 { + // Nothing to override, just return current method from context + return c.method + } + + method := utils.ToUpper(override[0]) + mINT := c.app.methodInt(method) + if mINT == -1 { + // Provided override does not valid HTTP method, no override, return current method + return c.method + } + + c.method = method + c.methodINT = mINT + return c.method +} + +// MultipartForm parse form entries from binary. +// This returns a map[string][]string, so given a key the value will be a string slice. +func (c *Ctx) MultipartForm() (*multipart.Form, error) { + return c.fasthttp.MultipartForm() +} + +// ClientHelloInfo return CHI from context +func (c *Ctx) ClientHelloInfo() *tls.ClientHelloInfo { + if c.app.tlsHandler != nil { + return c.app.tlsHandler.clientHelloInfo + } + + return nil +} + +// Next executes the next method in the stack that matches the current route. +func (c *Ctx) Next() error { + // Increment handler index + c.indexHandler++ + var err error + // Did we execute all route handlers? + if c.indexHandler < len(c.route.Handlers) { + // Continue route stack + err = c.route.Handlers[c.indexHandler](c) + } else { + // Continue handler stack + _, err = c.app.next(c) + } + return err +} + +// RestartRouting instead of going to the next handler. This may be useful after +// changing the request path. Note that handlers might be executed again. +func (c *Ctx) RestartRouting() error { + c.indexRoute = -1 + _, err := c.app.next(c) + return err +} + +// OriginalURL contains the original request URL. +// Returned value is only valid within the handler. Do not store any references. +// Make copies or use the Immutable setting to use the value outside the Handler. +func (c *Ctx) OriginalURL() string { + return c.app.getString(c.fasthttp.Request.Header.RequestURI()) +} + +// Params is used to get the route parameters. +// Defaults to empty string "" if the param doesn't exist. +// If a default value is given, it will return that value if the param doesn't exist. +// Returned value is only valid within the handler. Do not store any references. +// Make copies or use the Immutable setting to use the value outside the Handler. +func (c *Ctx) Params(key string, defaultValue ...string) string { + if key == "*" || key == "+" { + key += "1" + } + for i := range c.route.Params { + if len(key) != len(c.route.Params[i]) { + continue + } + if c.route.Params[i] == key || (!c.app.config.CaseSensitive && utils.EqualFold(c.route.Params[i], key)) { + // in case values are not here + if len(c.values) <= i || len(c.values[i]) == 0 { + break + } + return c.values[i] + } + } + return defaultString("", defaultValue) +} + +// AllParams Params is used to get all route parameters. +// Using Params method to get params. +func (c *Ctx) AllParams() map[string]string { + params := make(map[string]string, len(c.route.Params)) + for _, param := range c.route.Params { + params[param] = c.Params(param) + } + + return params +} + +// ParamsParser binds the param string to a struct. +func (c *Ctx) ParamsParser(out interface{}) error { + params := make(map[string][]string, len(c.route.Params)) + for _, param := range c.route.Params { + params[param] = append(params[param], c.Params(param)) + } + return c.parseToStruct(paramsTag, out, params) +} + +// ParamsInt is used to get an integer from the route parameters +// it defaults to zero if the parameter is not found or if the +// parameter cannot be converted to an integer +// If a default value is given, it will return that value in case the param +// doesn't exist or cannot be converted to an integer +func (c *Ctx) ParamsInt(key string, defaultValue ...int) (int, error) { + // Use Atoi to convert the param to an int or return zero and an error + value, err := strconv.Atoi(c.Params(key)) + if err != nil { + if len(defaultValue) > 0 { + return defaultValue[0], nil + } + return 0, fmt.Errorf("failed to convert: %w", err) + } + + return value, nil +} + +// Path returns the path part of the request URL. +// Optionally, you could override the path. +func (c *Ctx) Path(override ...string) string { + if len(override) != 0 && c.path != override[0] { + // Set new path to context + c.pathOriginal = override[0] + + // Set new path to request context + c.fasthttp.Request.URI().SetPath(c.pathOriginal) + // Prettify path + c.configDependentPaths() + } + return c.path +} + +// Protocol contains the request protocol string: http or https for TLS requests. +// Please use Config.EnableTrustedProxyCheck to prevent header spoofing, in case when your app is behind the proxy. +func (c *Ctx) Protocol() string { + if c.fasthttp.IsTLS() { + return schemeHTTPS + } + if !c.IsProxyTrusted() { + return schemeHTTP + } + + scheme := schemeHTTP + const lenXHeaderName = 12 + c.fasthttp.Request.Header.VisitAll(func(key, val []byte) { + if len(key) < lenXHeaderName { + return // Neither "X-Forwarded-" nor "X-Url-Scheme" + } + switch { + case bytes.HasPrefix(key, []byte("X-Forwarded-")): + if bytes.Equal(key, []byte(HeaderXForwardedProto)) || + bytes.Equal(key, []byte(HeaderXForwardedProtocol)) { + v := c.app.getString(val) + commaPos := strings.Index(v, ",") + if commaPos != -1 { + scheme = v[:commaPos] + } else { + scheme = v + } + } else if bytes.Equal(key, []byte(HeaderXForwardedSsl)) && bytes.Equal(val, []byte("on")) { + scheme = schemeHTTPS + } + + case bytes.Equal(key, []byte(HeaderXUrlScheme)): + scheme = c.app.getString(val) + } + }) + return scheme +} + +// Query returns the query string parameter in the url. +// Defaults to empty string "" if the query doesn't exist. +// If a default value is given, it will return that value if the query doesn't exist. +// Returned value is only valid within the handler. Do not store any references. +// Make copies or use the Immutable setting to use the value outside the Handler. +func (c *Ctx) Query(key string, defaultValue ...string) string { + return defaultString(c.app.getString(c.fasthttp.QueryArgs().Peek(key)), defaultValue) +} + +// Queries returns a map of query parameters and their values. +// +// GET /?name=alex&wanna_cake=2&id= +// Queries()["name"] == "alex" +// Queries()["wanna_cake"] == "2" +// Queries()["id"] == "" +// +// GET /?field1=value1&field1=value2&field2=value3 +// Queries()["field1"] == "value2" +// Queries()["field2"] == "value3" +// +// GET /?list_a=1&list_a=2&list_a=3&list_b[]=1&list_b[]=2&list_b[]=3&list_c=1,2,3 +// Queries()["list_a"] == "3" +// Queries()["list_b[]"] == "3" +// Queries()["list_c"] == "1,2,3" +// +// GET /api/search?filters.author.name=John&filters.category.name=Technology&filters[customer][name]=Alice&filters[status]=pending +// Queries()["filters.author.name"] == "John" +// Queries()["filters.category.name"] == "Technology" +// Queries()["filters[customer][name]"] == "Alice" +// Queries()["filters[status]"] == "pending" +func (c *Ctx) Queries() map[string]string { + m := make(map[string]string, c.Context().QueryArgs().Len()) + c.Context().QueryArgs().VisitAll(func(key, value []byte) { + m[c.app.getString(key)] = c.app.getString(value) + }) + return m +} + +// QueryInt returns integer value of key string parameter in the url. +// Default to empty or invalid key is 0. +// +// GET /?name=alex&wanna_cake=2&id= +// QueryInt("wanna_cake", 1) == 2 +// QueryInt("name", 1) == 1 +// QueryInt("id", 1) == 1 +// QueryInt("id") == 0 +func (c *Ctx) QueryInt(key string, defaultValue ...int) int { + // Use Atoi to convert the param to an int or return zero and an error + value, err := strconv.Atoi(c.app.getString(c.fasthttp.QueryArgs().Peek(key))) + if err != nil { + if len(defaultValue) > 0 { + return defaultValue[0] + } + return 0 + } + + return value +} + +// QueryBool returns bool value of key string parameter in the url. +// Default to empty or invalid key is false. +// +// Get /?name=alex&want_pizza=false&id= +// QueryBool("want_pizza") == false +// QueryBool("want_pizza", true) == false +// QueryBool("name") == false +// QueryBool("name", true) == true +// QueryBool("id") == false +// QueryBool("id", true) == true +func (c *Ctx) QueryBool(key string, defaultValue ...bool) bool { + value, err := strconv.ParseBool(c.app.getString(c.fasthttp.QueryArgs().Peek(key))) + if err != nil { + if len(defaultValue) > 0 { + return defaultValue[0] + } + return false + } + return value +} + +// QueryFloat returns float64 value of key string parameter in the url. +// Default to empty or invalid key is 0. +// +// GET /?name=alex&amount=32.23&id= +// QueryFloat("amount") = 32.23 +// QueryFloat("amount", 3) = 32.23 +// QueryFloat("name", 1) = 1 +// QueryFloat("name") = 0 +// QueryFloat("id", 3) = 3 +func (c *Ctx) QueryFloat(key string, defaultValue ...float64) float64 { + // use strconv.ParseFloat to convert the param to a float or return zero and an error. + value, err := strconv.ParseFloat(c.app.getString(c.fasthttp.QueryArgs().Peek(key)), 64) + if err != nil { + if len(defaultValue) > 0 { + return defaultValue[0] + } + return 0 + } + return value +} + +// QueryParser binds the query string to a struct. +func (c *Ctx) QueryParser(out interface{}) error { + data := make(map[string][]string) + var err error + + c.fasthttp.QueryArgs().VisitAll(func(key, val []byte) { + if err != nil { + return + } + + k := c.app.getString(key) + v := c.app.getString(val) + + err = formatParserData(out, data, queryTag, k, v, c.app.config.EnableSplittingOnParsers, true) + }) + + if err != nil { + return err + } + + return c.parseToStruct(queryTag, out, data) +} + +// ReqHeaderParser binds the request header strings to a struct. +func (c *Ctx) ReqHeaderParser(out interface{}) error { + data := make(map[string][]string) + var err error + + c.fasthttp.Request.Header.VisitAll(func(key, val []byte) { + if err != nil { + return + } + + k := c.app.getString(key) + v := c.app.getString(val) + + err = formatParserData(out, data, reqHeaderTag, k, v, c.app.config.EnableSplittingOnParsers, false) + }) + + if err != nil { + return err + } + + return c.parseToStruct(reqHeaderTag, out, data) +} + +func (*Ctx) parseToStruct(aliasTag string, out interface{}, data map[string][]string) error { + // Get decoder from pool + schemaDecoder, ok := decoderPoolMap[aliasTag].Get().(*schema.Decoder) + if !ok { + panic(fmt.Errorf("failed to type-assert to *schema.Decoder")) + } + defer decoderPoolMap[aliasTag].Put(schemaDecoder) + + // Set alias tag + schemaDecoder.SetAliasTag(aliasTag) + + if err := schemaDecoder.Decode(out, data); err != nil { + return fmt.Errorf("failed to decode: %w", err) + } + + return nil +} + +func equalFieldType(out interface{}, kind reflect.Kind, key, tag string) bool { + outTyp := reflect.TypeOf(out).Elem() + if outTyp.Kind() != reflect.Struct { + return false + } + key = utils.ToLower(key) + return checkEqualFieldType(outTyp, kind, key, tag) +} + +func checkEqualFieldType(outTyp reflect.Type, kind reflect.Kind, key, tag string) bool { + for i := 0; i < outTyp.NumField(); i++ { + typeField := outTyp.Field(i) + + if typeField.Anonymous && typeField.Type.Kind() == reflect.Struct { + if checkEqualFieldType(typeField.Type, kind, key, tag) { + return true + } + } + + if typeField.PkgPath != "" { // unexported field + continue + } + + if typeField.Type.Kind() != kind { + continue + } + + inputFieldName := typeField.Tag.Get(tag) + if inputFieldName == "" { + inputFieldName = typeField.Name + } else if idx := strings.IndexByte(inputFieldName, ','); idx > -1 { + inputFieldName = inputFieldName[:idx] + } + + if utils.ToLower(inputFieldName) == key { + return true + } + } + + return false +} + +var ( + ErrRangeMalformed = errors.New("range: malformed range header string") + ErrRangeUnsatisfiable = errors.New("range: unsatisfiable range") +) + +// Range returns a struct containing the type and a slice of ranges. +func (c *Ctx) Range(size int) (Range, error) { + var ( + rangeData Range + ranges string + ) + rangeStr := c.Get(HeaderRange) + + i := strings.IndexByte(rangeStr, '=') + if i == -1 || strings.Contains(rangeStr[i+1:], "=") { + return rangeData, ErrRangeMalformed + } + rangeData.Type = rangeStr[:i] + ranges = rangeStr[i+1:] + + var ( + singleRange string + moreRanges = ranges + ) + for moreRanges != "" { + singleRange = moreRanges + if i := strings.IndexByte(moreRanges, ','); i >= 0 { + singleRange = moreRanges[:i] + moreRanges = moreRanges[i+1:] + } else { + moreRanges = "" + } + + var ( + startStr, endStr string + i int + ) + if i = strings.IndexByte(singleRange, '-'); i == -1 { + return rangeData, ErrRangeMalformed + } + startStr = singleRange[:i] + endStr = singleRange[i+1:] + + start, startErr := fasthttp.ParseUint(utils.UnsafeBytes(startStr)) + end, endErr := fasthttp.ParseUint(utils.UnsafeBytes(endStr)) + if startErr != nil { // -nnn + start = size - end + end = size - 1 + } else if endErr != nil { // nnn- + end = size - 1 + } + if end > size-1 { // limit last-byte-pos to current length + end = size - 1 + } + if start > end || start < 0 { + continue + } + rangeData.Ranges = append(rangeData.Ranges, struct { + Start int + End int + }{ + start, + end, + }) + } + if len(rangeData.Ranges) < 1 { + return rangeData, ErrRangeUnsatisfiable + } + + return rangeData, nil +} + +// Redirect to the URL derived from the specified path, with specified status. +// If status is not specified, status defaults to 302 Found. +func (c *Ctx) Redirect(location string, status ...int) error { + c.setCanonical(HeaderLocation, location) + if len(status) > 0 { + c.Status(status[0]) + } else { + c.Status(StatusFound) + } + return nil +} + +// Bind Add vars to default view var map binding to template engine. +// Variables are read by the Render method and may be overwritten. +func (c *Ctx) Bind(vars Map) error { + // init viewBindMap - lazy map + for k, v := range vars { + c.viewBindMap.Store(k, v) + } + return nil +} + +// getLocationFromRoute get URL location from route using parameters +func (c *Ctx) getLocationFromRoute(route Route, params Map) (string, error) { + buf := bytebufferpool.Get() + for _, segment := range route.routeParser.segs { + if !segment.IsParam { + _, err := buf.WriteString(segment.Const) + if err != nil { + return "", fmt.Errorf("failed to write string: %w", err) + } + continue + } + + for key, val := range params { + isSame := key == segment.ParamName || (!c.app.config.CaseSensitive && utils.EqualFold(key, segment.ParamName)) + isGreedy := segment.IsGreedy && len(key) == 1 && isInCharset(key[0], greedyParameters) + if isSame || isGreedy { + _, err := buf.WriteString(utils.ToString(val)) + if err != nil { + return "", fmt.Errorf("failed to write string: %w", err) + } + } + } + } + location := buf.String() + // release buffer + bytebufferpool.Put(buf) + return location, nil +} + +// GetRouteURL generates URLs to named routes, with parameters. URLs are relative, for example: "/user/1831" +func (c *Ctx) GetRouteURL(routeName string, params Map) (string, error) { + return c.getLocationFromRoute(c.App().GetRoute(routeName), params) +} + +// RedirectToRoute to the Route registered in the app with appropriate parameters +// If status is not specified, status defaults to 302 Found. +// If you want to send queries to route, you must add "queries" key typed as map[string]string to params. +func (c *Ctx) RedirectToRoute(routeName string, params Map, status ...int) error { + location, err := c.getLocationFromRoute(c.App().GetRoute(routeName), params) + if err != nil { + return err + } + + // Check queries + if queries, ok := params["queries"].(map[string]string); ok { + queryText := bytebufferpool.Get() + defer bytebufferpool.Put(queryText) + + i := 1 + for k, v := range queries { + _, _ = queryText.WriteString(k + "=" + v) + + if i != len(queries) { + _, _ = queryText.WriteString("&") + } + i++ + } + + return c.Redirect(location+"?"+queryText.String(), status...) + } + return c.Redirect(location, status...) +} + +// RedirectBack to the URL to referer +// If status is not specified, status defaults to 302 Found. +func (c *Ctx) RedirectBack(fallback string, status ...int) error { + location := c.Get(HeaderReferer) + if location == "" { + location = fallback + } + return c.Redirect(location, status...) +} + +// Render a template with data and sends a text/html response. +// We support the following engines: html, amber, handlebars, mustache, pug +func (c *Ctx) Render(name string, bind interface{}, layouts ...string) error { + // Get new buffer from pool + buf := bytebufferpool.Get() + defer bytebufferpool.Put(buf) + + // Initialize empty bind map if bind is nil + if bind == nil { + bind = make(Map) + } + + // Pass-locals-to-views, bind, appListKeys + c.renderExtensions(bind) + + var rendered bool + for i := len(c.app.mountFields.appListKeys) - 1; i >= 0; i-- { + prefix := c.app.mountFields.appListKeys[i] + app := c.app.mountFields.appList[prefix] + if prefix == "" || strings.Contains(c.OriginalURL(), prefix) { + if len(layouts) == 0 && app.config.ViewsLayout != "" { + layouts = []string{ + app.config.ViewsLayout, + } + } + + // Render template from Views + if app.config.Views != nil { + if err := app.config.Views.Render(buf, name, bind, layouts...); err != nil { + return fmt.Errorf("failed to render: %w", err) + } + + rendered = true + break + } + } + } + + if !rendered { + // Render raw template using 'name' as filepath if no engine is set + var tmpl *template.Template + if _, err := readContent(buf, name); err != nil { + return err + } + // Parse template + tmpl, err := template.New("").Parse(c.app.getString(buf.Bytes())) + if err != nil { + return fmt.Errorf("failed to parse: %w", err) + } + buf.Reset() + // Render template + if err := tmpl.Execute(buf, bind); err != nil { + return fmt.Errorf("failed to execute: %w", err) + } + } + + // Set Content-Type to text/html + c.fasthttp.Response.Header.SetContentType(MIMETextHTMLCharsetUTF8) + // Set rendered template to body + c.fasthttp.Response.SetBody(buf.Bytes()) + + return nil +} + +func (c *Ctx) renderExtensions(bind interface{}) { + if bindMap, ok := bind.(Map); ok { + // Bind view map + c.viewBindMap.Range(func(key, value interface{}) bool { + keyValue, ok := key.(string) + if !ok { + return true + } + if _, ok := bindMap[keyValue]; !ok { + bindMap[keyValue] = value + } + return true + }) + + // Check if the PassLocalsToViews option is enabled (by default it is disabled) + if c.app.config.PassLocalsToViews { + // Loop through each local and set it in the map + c.fasthttp.VisitUserValues(func(key []byte, val interface{}) { + // check if bindMap doesn't contain the key + if _, ok := bindMap[c.app.getString(key)]; !ok { + // Set the key and value in the bindMap + bindMap[c.app.getString(key)] = val + } + }) + } + } + + if len(c.app.mountFields.appListKeys) == 0 { + c.app.generateAppListKeys() + } +} + +// Route returns the matched Route struct. +func (c *Ctx) Route() *Route { + if c.route == nil { + // Fallback for fasthttp error handler + return &Route{ + path: c.pathOriginal, + Path: c.pathOriginal, + Method: c.method, + Handlers: make([]Handler, 0), + Params: make([]string, 0), + } + } + return c.route +} + +// SaveFile saves any multipart file to disk. +func (*Ctx) SaveFile(fileheader *multipart.FileHeader, path string) error { + return fasthttp.SaveMultipartFile(fileheader, path) +} + +// SaveFileToStorage saves any multipart file to an external storage system. +func (*Ctx) SaveFileToStorage(fileheader *multipart.FileHeader, path string, storage Storage) error { + file, err := fileheader.Open() + if err != nil { + return fmt.Errorf("failed to open: %w", err) + } + + content, err := io.ReadAll(file) + if err != nil { + return fmt.Errorf("failed to read: %w", err) + } + + if err := storage.Set(path, content, 0); err != nil { + return fmt.Errorf("failed to store: %w", err) + } + + return nil +} + +// Secure returns whether a secure connection was established. +func (c *Ctx) Secure() bool { + return c.Protocol() == schemeHTTPS +} + +// Send sets the HTTP response body without copying it. +// From this point onward the body argument must not be changed. +func (c *Ctx) Send(body []byte) error { + // Write response body + c.fasthttp.Response.SetBodyRaw(body) + return nil +} + +var ( + sendFileOnce sync.Once + sendFileFS *fasthttp.FS + sendFileHandler fasthttp.RequestHandler +) + +// SendFile transfers the file from the given path. +// The file is not compressed by default, enable this by passing a 'true' argument +// Sets the Content-Type response HTTP header field based on the filenames extension. +func (c *Ctx) SendFile(file string, compress ...bool) error { + // Save the filename, we will need it in the error message if the file isn't found + filename := file + + // https://github.com/valyala/fasthttp/blob/c7576cc10cabfc9c993317a2d3f8355497bea156/fs.go#L129-L134 + sendFileOnce.Do(func() { + const cacheDuration = 10 * time.Second + sendFileFS = &fasthttp.FS{ + Root: "", + AllowEmptyRoot: true, + GenerateIndexPages: false, + AcceptByteRange: true, + Compress: true, + CompressedFileSuffix: c.app.config.CompressedFileSuffix, + CacheDuration: cacheDuration, + IndexNames: []string{"index.html"}, + PathNotFound: func(ctx *fasthttp.RequestCtx) { + ctx.Response.SetStatusCode(StatusNotFound) + }, + } + sendFileHandler = sendFileFS.NewRequestHandler() + }) + + // Keep original path for mutable params + c.pathOriginal = utils.CopyString(c.pathOriginal) + // Disable compression + if len(compress) == 0 || !compress[0] { + // https://github.com/valyala/fasthttp/blob/7cc6f4c513f9e0d3686142e0a1a5aa2f76b3194a/fs.go#L55 + c.fasthttp.Request.Header.Del(HeaderAcceptEncoding) + } + // copy of https://github.com/valyala/fasthttp/blob/7cc6f4c513f9e0d3686142e0a1a5aa2f76b3194a/fs.go#L103-L121 with small adjustments + if len(file) == 0 || !filepath.IsAbs(file) { + // extend relative path to absolute path + hasTrailingSlash := len(file) > 0 && (file[len(file)-1] == '/' || file[len(file)-1] == '\\') + + var err error + file = filepath.FromSlash(file) + if file, err = filepath.Abs(file); err != nil { + return fmt.Errorf("failed to determine abs file path: %w", err) + } + if hasTrailingSlash { + file += "/" + } + } + // convert the path to forward slashes regardless the OS in order to set the URI properly + // the handler will convert back to OS path separator before opening the file + file = filepath.ToSlash(file) + + // Restore the original requested URL + originalURL := utils.CopyString(c.OriginalURL()) + defer c.fasthttp.Request.SetRequestURI(originalURL) + // Set new URI for fileHandler + c.fasthttp.Request.SetRequestURI(file) + // Save status code + status := c.fasthttp.Response.StatusCode() + // Serve file + sendFileHandler(c.fasthttp) + // Get the status code which is set by fasthttp + fsStatus := c.fasthttp.Response.StatusCode() + // Set the status code set by the user if it is different from the fasthttp status code and 200 + if status != fsStatus && status != StatusOK { + c.Status(status) + } + // Check for error + if status != StatusNotFound && fsStatus == StatusNotFound { + return NewError(StatusNotFound, fmt.Sprintf("sendfile: file %s not found", filename)) + } + return nil +} + +// SendStatus sets the HTTP status code and if the response body is empty, +// it sets the correct status message in the body. +func (c *Ctx) SendStatus(status int) error { + c.Status(status) + + // Only set status body when there is no response body + if len(c.fasthttp.Response.Body()) == 0 { + return c.SendString(utils.StatusMessage(status)) + } + + return nil +} + +// SendString sets the HTTP response body for string types. +// This means no type assertion, recommended for faster performance +func (c *Ctx) SendString(body string) error { + c.fasthttp.Response.SetBodyString(body) + + return nil +} + +// SendStream sets response body stream and optional body size. +func (c *Ctx) SendStream(stream io.Reader, size ...int) error { + if len(size) > 0 && size[0] >= 0 { + c.fasthttp.Response.SetBodyStream(stream, size[0]) + } else { + c.fasthttp.Response.SetBodyStream(stream, -1) + } + + return nil +} + +// Set sets the response's HTTP header field to the specified key, value. +func (c *Ctx) Set(key, val string) { + c.fasthttp.Response.Header.Set(key, val) +} + +func (c *Ctx) setCanonical(key, val string) { + c.fasthttp.Response.Header.SetCanonical(c.app.getBytes(key), c.app.getBytes(val)) +} + +// Subdomains returns a string slice of subdomains in the domain name of the request. +// The subdomain offset, which defaults to 2, is used for determining the beginning of the subdomain segments. +func (c *Ctx) Subdomains(offset ...int) []string { + o := 2 + if len(offset) > 0 { + o = offset[0] + } + subdomains := strings.Split(c.Hostname(), ".") + l := len(subdomains) - o + // Check index to avoid slice bounds out of range panic + if l < 0 { + l = len(subdomains) + } + subdomains = subdomains[:l] + return subdomains +} + +// Stale is not implemented yet, pull requests are welcome! +func (c *Ctx) Stale() bool { + return !c.Fresh() +} + +// Status sets the HTTP status for the response. +// This method is chainable. +func (c *Ctx) Status(status int) *Ctx { + c.fasthttp.Response.SetStatusCode(status) + return c +} + +// String returns unique string representation of the ctx. +// +// The returned value may be useful for logging. +func (c *Ctx) String() string { + // Get buffer from pool + buf := bytebufferpool.Get() + + // Start with the ID, converting it to a hex string without fmt.Sprintf + buf.WriteByte('#') + + // Convert ID to hexadecimal + id := strconv.FormatUint(c.fasthttp.ID(), 16) + // Pad with leading zeros to ensure 16 characters + for i := 0; i < (16 - len(id)); i++ { + buf.WriteByte('0') + } + buf.WriteString(id) + buf.WriteString(" - ") + + // Add local and remote addresses directly + buf.WriteString(c.fasthttp.LocalAddr().String()) + buf.WriteString(" <-> ") + buf.WriteString(c.fasthttp.RemoteAddr().String()) + buf.WriteString(" - ") + + // Add method and URI + buf.Write(c.fasthttp.Request.Header.Method()) + buf.WriteByte(' ') + buf.Write(c.fasthttp.URI().FullURI()) + + // Allocate string + str := buf.String() + + // Reset buffer + buf.Reset() + bytebufferpool.Put(buf) + + return str +} + +// Type sets the Content-Type HTTP header to the MIME type specified by the file extension. +func (c *Ctx) Type(extension string, charset ...string) *Ctx { + if len(charset) > 0 { + c.fasthttp.Response.Header.SetContentType(utils.GetMIME(extension) + "; charset=" + charset[0]) + } else { + c.fasthttp.Response.Header.SetContentType(utils.GetMIME(extension)) + } + return c +} + +// Vary adds the given header field to the Vary response header. +// This will append the header, if not already listed, otherwise leaves it listed in the current location. +func (c *Ctx) Vary(fields ...string) { + c.Append(HeaderVary, fields...) +} + +// Write appends p into response body. +func (c *Ctx) Write(p []byte) (int, error) { + c.fasthttp.Response.AppendBody(p) + return len(p), nil +} + +// Writef appends f & a into response body writer. +func (c *Ctx) Writef(f string, a ...interface{}) (int, error) { + //nolint:wrapcheck // This must not be wrapped + return fmt.Fprintf(c.fasthttp.Response.BodyWriter(), f, a...) +} + +// WriteString appends s to response body. +func (c *Ctx) WriteString(s string) (int, error) { + c.fasthttp.Response.AppendBodyString(s) + return len(s), nil +} + +// XHR returns a Boolean property, that is true, if the request's X-Requested-With header field is XMLHttpRequest, +// indicating that the request was issued by a client library (such as jQuery). +func (c *Ctx) XHR() bool { + return utils.EqualFoldBytes(c.app.getBytes(c.Get(HeaderXRequestedWith)), []byte("xmlhttprequest")) +} + +// configDependentPaths set paths for route recognition and prepared paths for the user, +// here the features for caseSensitive, decoded paths, strict paths are evaluated +func (c *Ctx) configDependentPaths() { + c.pathBuffer = append(c.pathBuffer[0:0], c.pathOriginal...) + // If UnescapePath enabled, we decode the path and save it for the framework user + if c.app.config.UnescapePath { + c.pathBuffer = fasthttp.AppendUnquotedArg(c.pathBuffer[:0], c.pathBuffer) + } + c.path = c.app.getString(c.pathBuffer) + + // another path is specified which is for routing recognition only + // use the path that was changed by the previous configuration flags + c.detectionPathBuffer = append(c.detectionPathBuffer[0:0], c.pathBuffer...) + // If CaseSensitive is disabled, we lowercase the original path + if !c.app.config.CaseSensitive { + c.detectionPathBuffer = utils.ToLowerBytes(c.detectionPathBuffer) + } + // If StrictRouting is disabled, we strip all trailing slashes + if !c.app.config.StrictRouting && len(c.detectionPathBuffer) > 1 && c.detectionPathBuffer[len(c.detectionPathBuffer)-1] == '/' { + c.detectionPathBuffer = utils.TrimRightBytes(c.detectionPathBuffer, '/') + } + c.detectionPath = c.app.getString(c.detectionPathBuffer) + + // Define the path for dividing routes into areas for fast tree detection, so that fewer routes need to be traversed, + // since the first three characters area select a list of routes + c.treePath = c.treePath[0:0] + const maxDetectionPaths = 3 + if len(c.detectionPath) >= maxDetectionPaths { + c.treePath = c.detectionPath[:maxDetectionPaths] + } +} + +func (c *Ctx) IsProxyTrusted() bool { + if !c.app.config.EnableTrustedProxyCheck { + return true + } + + ip := c.fasthttp.RemoteIP() + + if _, trusted := c.app.config.trustedProxiesMap[ip.String()]; trusted { + return true + } + + for _, ipNet := range c.app.config.trustedProxyRanges { + if ipNet.Contains(ip) { + return true + } + } + + return false +} + +var localHosts = [...]string{"127.0.0.1", "::1"} + +// IsLocalHost will return true if address is a localhost address. +func (*Ctx) isLocalHost(address string) bool { + for _, h := range localHosts { + if address == h { + return true + } + } + return false +} + +// IsFromLocal will return true if request came from local. +func (c *Ctx) IsFromLocal() bool { + return c.isLocalHost(c.fasthttp.RemoteIP().String()) +} + +func (c *Ctx) getBody() []byte { + if c.app.config.Immutable { + return utils.CopyBytes(c.fasthttp.Request.Body()) + } + + return c.fasthttp.Request.Body() +} diff --git a/vendor/github.com/gofiber/fiber/v2/error.go b/vendor/github.com/gofiber/fiber/v2/error.go new file mode 100644 index 0000000..e520420 --- /dev/null +++ b/vendor/github.com/gofiber/fiber/v2/error.go @@ -0,0 +1,40 @@ +package fiber + +import ( + errors "encoding/json" + + "github.com/gofiber/fiber/v2/internal/schema" +) + +type ( + // ConversionError Conversion error exposes the internal schema.ConversionError for public use. + ConversionError = schema.ConversionError + // UnknownKeyError error exposes the internal schema.UnknownKeyError for public use. + UnknownKeyError = schema.UnknownKeyError + // EmptyFieldError error exposes the internal schema.EmptyFieldError for public use. + EmptyFieldError = schema.EmptyFieldError + // MultiError error exposes the internal schema.MultiError for public use. + MultiError = schema.MultiError +) + +type ( + // An InvalidUnmarshalError describes an invalid argument passed to Unmarshal. + // (The argument to Unmarshal must be a non-nil pointer.) + InvalidUnmarshalError = errors.InvalidUnmarshalError + + // A MarshalerError represents an error from calling a MarshalJSON or MarshalText method. + MarshalerError = errors.MarshalerError + + // A SyntaxError is a description of a JSON syntax error. + SyntaxError = errors.SyntaxError + + // An UnmarshalTypeError describes a JSON value that was + // not appropriate for a value of a specific Go type. + UnmarshalTypeError = errors.UnmarshalTypeError + + // An UnsupportedTypeError is returned by Marshal when attempting + // to encode an unsupported value type. + UnsupportedTypeError = errors.UnsupportedTypeError + + UnsupportedValueError = errors.UnsupportedValueError +) diff --git a/vendor/github.com/gofiber/fiber/v2/group.go b/vendor/github.com/gofiber/fiber/v2/group.go new file mode 100644 index 0000000..0e546a3 --- /dev/null +++ b/vendor/github.com/gofiber/fiber/v2/group.go @@ -0,0 +1,209 @@ +// ⚡️ Fiber is an Express inspired web framework written in Go with ☕️ +// 🤖 Github Repository: https://github.com/gofiber/fiber +// 📌 API Documentation: https://docs.gofiber.io + +package fiber + +import ( + "fmt" + "reflect" +) + +// Group struct +type Group struct { + app *App + parentGroup *Group + name string + anyRouteDefined bool + + Prefix string +} + +// Name Assign name to specific route or group itself. +// +// If this method is used before any route added to group, it'll set group name and OnGroupNameHook will be used. +// Otherwise, it'll set route name and OnName hook will be used. +func (grp *Group) Name(name string) Router { + if grp.anyRouteDefined { + grp.app.Name(name) + + return grp + } + + grp.app.mutex.Lock() + if grp.parentGroup != nil { + grp.name = grp.parentGroup.name + name + } else { + grp.name = name + } + + if err := grp.app.hooks.executeOnGroupNameHooks(*grp); err != nil { + panic(err) + } + grp.app.mutex.Unlock() + + return grp +} + +// Use registers a middleware route that will match requests +// with the provided prefix (which is optional and defaults to "/"). +// +// app.Use(func(c *fiber.Ctx) error { +// return c.Next() +// }) +// app.Use("/api", func(c *fiber.Ctx) error { +// return c.Next() +// }) +// app.Use("/api", handler, func(c *fiber.Ctx) error { +// return c.Next() +// }) +// +// This method will match all HTTP verbs: GET, POST, PUT, HEAD etc... +func (grp *Group) Use(args ...interface{}) Router { + var prefix string + var prefixes []string + var handlers []Handler + + for i := 0; i < len(args); i++ { + switch arg := args[i].(type) { + case string: + prefix = arg + case []string: + prefixes = arg + case Handler: + handlers = append(handlers, arg) + default: + panic(fmt.Sprintf("use: invalid handler %v\n", reflect.TypeOf(arg))) + } + } + + if len(prefixes) == 0 { + prefixes = append(prefixes, prefix) + } + + for _, prefix := range prefixes { + grp.app.register(methodUse, getGroupPath(grp.Prefix, prefix), grp, handlers...) + } + + if !grp.anyRouteDefined { + grp.anyRouteDefined = true + } + + return grp +} + +// Get registers a route for GET methods that requests a representation +// of the specified resource. Requests using GET should only retrieve data. +func (grp *Group) Get(path string, handlers ...Handler) Router { + grp.Add(MethodHead, path, handlers...) + return grp.Add(MethodGet, path, handlers...) +} + +// Head registers a route for HEAD methods that asks for a response identical +// to that of a GET request, but without the response body. +func (grp *Group) Head(path string, handlers ...Handler) Router { + return grp.Add(MethodHead, path, handlers...) +} + +// Post registers a route for POST methods that is used to submit an entity to the +// specified resource, often causing a change in state or side effects on the server. +func (grp *Group) Post(path string, handlers ...Handler) Router { + return grp.Add(MethodPost, path, handlers...) +} + +// Put registers a route for PUT methods that replaces all current representations +// of the target resource with the request payload. +func (grp *Group) Put(path string, handlers ...Handler) Router { + return grp.Add(MethodPut, path, handlers...) +} + +// Delete registers a route for DELETE methods that deletes the specified resource. +func (grp *Group) Delete(path string, handlers ...Handler) Router { + return grp.Add(MethodDelete, path, handlers...) +} + +// Connect registers a route for CONNECT methods that establishes a tunnel to the +// server identified by the target resource. +func (grp *Group) Connect(path string, handlers ...Handler) Router { + return grp.Add(MethodConnect, path, handlers...) +} + +// Options registers a route for OPTIONS methods that is used to describe the +// communication options for the target resource. +func (grp *Group) Options(path string, handlers ...Handler) Router { + return grp.Add(MethodOptions, path, handlers...) +} + +// Trace registers a route for TRACE methods that performs a message loop-back +// test along the path to the target resource. +func (grp *Group) Trace(path string, handlers ...Handler) Router { + return grp.Add(MethodTrace, path, handlers...) +} + +// Patch registers a route for PATCH methods that is used to apply partial +// modifications to a resource. +func (grp *Group) Patch(path string, handlers ...Handler) Router { + return grp.Add(MethodPatch, path, handlers...) +} + +// Add allows you to specify a HTTP method to register a route +func (grp *Group) Add(method, path string, handlers ...Handler) Router { + grp.app.register(method, getGroupPath(grp.Prefix, path), grp, handlers...) + if !grp.anyRouteDefined { + grp.anyRouteDefined = true + } + + return grp +} + +// Static will create a file server serving static files +func (grp *Group) Static(prefix, root string, config ...Static) Router { + grp.app.registerStatic(getGroupPath(grp.Prefix, prefix), root, config...) + if !grp.anyRouteDefined { + grp.anyRouteDefined = true + } + + return grp +} + +// All will register the handler on all HTTP methods +func (grp *Group) All(path string, handlers ...Handler) Router { + for _, method := range grp.app.config.RequestMethods { + _ = grp.Add(method, path, handlers...) + } + return grp +} + +// Group is used for Routes with common prefix to define a new sub-router with optional middleware. +// +// api := app.Group("/api") +// api.Get("/users", handler) +func (grp *Group) Group(prefix string, handlers ...Handler) Router { + prefix = getGroupPath(grp.Prefix, prefix) + if len(handlers) > 0 { + grp.app.register(methodUse, prefix, grp, handlers...) + } + + // Create new group + newGrp := &Group{Prefix: prefix, app: grp.app, parentGroup: grp} + if err := grp.app.hooks.executeOnGroupHooks(*newGrp); err != nil { + panic(err) + } + + return newGrp +} + +// Route is used to define routes with a common prefix inside the common function. +// Uses Group method to define new sub-router. +func (grp *Group) Route(prefix string, fn func(router Router), name ...string) Router { + // Create new group + group := grp.Group(prefix) + if len(name) > 0 { + group.Name(name[0]) + } + + // Define routes + fn(group) + + return group +} diff --git a/vendor/github.com/gofiber/fiber/v2/helpers.go b/vendor/github.com/gofiber/fiber/v2/helpers.go new file mode 100644 index 0000000..2896c2a --- /dev/null +++ b/vendor/github.com/gofiber/fiber/v2/helpers.go @@ -0,0 +1,1226 @@ +// ⚡️ Fiber is an Express inspired web framework written in Go with ☕️ +// 🤖 Github Repository: https://github.com/gofiber/fiber +// 📌 API Documentation: https://docs.gofiber.io + +package fiber + +import ( + "bytes" + "crypto/tls" + "errors" + "fmt" + "hash/crc32" + "io" + "net" + "os" + "path/filepath" + "reflect" + "strings" + "time" + "unsafe" + + "github.com/gofiber/fiber/v2/log" + "github.com/gofiber/fiber/v2/utils" + + "github.com/valyala/bytebufferpool" + "github.com/valyala/fasthttp" +) + +// acceptType is a struct that holds the parsed value of an Accept header +// along with quality, specificity, parameters, and order. +// Used for sorting accept headers. +type acceptedType struct { + spec string + quality float64 + specificity int + order int + params string +} + +// getTLSConfig returns a net listener's tls config +func getTLSConfig(ln net.Listener) *tls.Config { + // Get listener type + pointer := reflect.ValueOf(ln) + + // Is it a tls.listener? + if pointer.String() == "<*tls.listener Value>" { + // Copy value from pointer + if val := reflect.Indirect(pointer); val.Type() != nil { + // Get private field from value + if field := val.FieldByName("config"); field.Type() != nil { + // Copy value from pointer field (unsafe) + newval := reflect.NewAt(field.Type(), unsafe.Pointer(field.UnsafeAddr())) //nolint:gosec // Probably the only way to extract the *tls.Config from a net.Listener. TODO: Verify there really is no easier way without using unsafe. + if newval.Type() != nil { + // Get element from pointer + if elem := newval.Elem(); elem.Type() != nil { + // Cast value to *tls.Config + c, ok := elem.Interface().(*tls.Config) + if !ok { + panic(fmt.Errorf("failed to type-assert to *tls.Config")) + } + return c + } + } + } + } + } + + return nil +} + +// readContent opens a named file and read content from it +func readContent(rf io.ReaderFrom, name string) (int64, error) { + // Read file + f, err := os.Open(filepath.Clean(name)) + if err != nil { + return 0, fmt.Errorf("failed to open: %w", err) + } + defer func() { + if err = f.Close(); err != nil { + log.Errorf("Error closing file: %s", err) + } + }() + if n, err := rf.ReadFrom(f); err != nil { + return n, fmt.Errorf("failed to read: %w", err) + } + return 0, nil +} + +// quoteString escape special characters in a given string +func (app *App) quoteString(raw string) string { + bb := bytebufferpool.Get() + // quoted := string(fasthttp.AppendQuotedArg(bb.B, getBytes(raw))) + quoted := app.getString(fasthttp.AppendQuotedArg(bb.B, app.getBytes(raw))) + bytebufferpool.Put(bb) + return quoted +} + +// Scan stack if other methods match the request +func (app *App) methodExist(ctx *Ctx) bool { + var exists bool + methods := app.config.RequestMethods + for i := 0; i < len(methods); i++ { + // Skip original method + if ctx.methodINT == i { + continue + } + // Reset stack index + indexRoute := -1 + tree, ok := ctx.app.treeStack[i][ctx.treePath] + if !ok { + tree = ctx.app.treeStack[i][""] + } + // Get stack length + lenr := len(tree) - 1 + // Loop over the route stack starting from previous index + for indexRoute < lenr { + // Increment route index + indexRoute++ + // Get *Route + route := tree[indexRoute] + // Skip use routes + if route.use { + continue + } + // Check if it matches the request path + match := route.match(ctx.detectionPath, ctx.path, &ctx.values) + // No match, next route + if match { + // We matched + exists = true + // Add method to Allow header + ctx.Append(HeaderAllow, methods[i]) + // Break stack loop + break + } + } + } + return exists +} + +// uniqueRouteStack drop all not unique routes from the slice +func uniqueRouteStack(stack []*Route) []*Route { + var unique []*Route + m := make(map[*Route]int) + for _, v := range stack { + if _, ok := m[v]; !ok { + // Unique key found. Record position and collect + // in result. + m[v] = len(unique) + unique = append(unique, v) + } + } + + return unique +} + +// defaultString returns the value or a default value if it is set +func defaultString(value string, defaultValue []string) string { + if len(value) == 0 && len(defaultValue) > 0 { + return defaultValue[0] + } + return value +} + +const normalizedHeaderETag = "Etag" + +// Generate and set ETag header to response +func setETag(c *Ctx, weak bool) { //nolint: revive // Accepting a bool param is fine here + // Don't generate ETags for invalid responses + if c.fasthttp.Response.StatusCode() != StatusOK { + return + } + body := c.fasthttp.Response.Body() + // Skips ETag if no response body is present + if len(body) == 0 { + return + } + // Get ETag header from request + clientEtag := c.Get(HeaderIfNoneMatch) + + // Generate ETag for response + const pol = 0xD5828281 + crc32q := crc32.MakeTable(pol) + etag := fmt.Sprintf("\"%d-%v\"", len(body), crc32.Checksum(body, crc32q)) + + // Enable weak tag + if weak { + etag = "W/" + etag + } + + // Check if client's ETag is weak + if strings.HasPrefix(clientEtag, "W/") { + // Check if server's ETag is weak + if clientEtag[2:] == etag || clientEtag[2:] == etag[2:] { + // W/1 == 1 || W/1 == W/1 + if err := c.SendStatus(StatusNotModified); err != nil { + log.Errorf("setETag: failed to SendStatus: %v", err) + } + c.fasthttp.ResetBody() + return + } + // W/1 != W/2 || W/1 != 2 + c.setCanonical(normalizedHeaderETag, etag) + return + } + if strings.Contains(clientEtag, etag) { + // 1 == 1 + if err := c.SendStatus(StatusNotModified); err != nil { + log.Errorf("setETag: failed to SendStatus: %v", err) + } + c.fasthttp.ResetBody() + return + } + // 1 != 2 + c.setCanonical(normalizedHeaderETag, etag) +} + +func getGroupPath(prefix, path string) string { + if len(path) == 0 { + return prefix + } + + if path[0] != '/' { + path = "/" + path + } + + return utils.TrimRight(prefix, '/') + path +} + +// acceptsOffer This function determines if an offer matches a given specification. +// It checks if the specification ends with a '*' or if the offer has the prefix of the specification. +// Returns true if the offer matches the specification, false otherwise. +func acceptsOffer(spec, offer, _ string) bool { + if len(spec) >= 1 && spec[len(spec)-1] == '*' { + return true + } else if strings.HasPrefix(spec, offer) { + return true + } + return false +} + +// acceptsOfferType This function determines if an offer type matches a given specification. +// It checks if the specification is equal to */* (i.e., all types are accepted). +// It gets the MIME type of the offer (either from the offer itself or by its file extension). +// It checks if the offer MIME type matches the specification MIME type or if the specification is of the form
+
+
+
+
+
+Cobra is a library for creating powerful modern CLI applications.
+
+Visit Cobra.dev for extensive documentation
+
+
+Cobra is used in many Go projects such as [Kubernetes](https://kubernetes.io/),
+[Hugo](https://gohugo.io), and [GitHub CLI](https://github.com/cli/cli) to
+name a few. [This list](site/content/projects_using_cobra.md) contains a more extensive list of projects using Cobra.
+
+[](https://github.com/spf13/cobra/actions?query=workflow%3ATest)
+[](https://pkg.go.dev/github.com/spf13/cobra)
+[](https://goreportcard.com/report/github.com/spf13/cobra)
+[](https://gophers.slack.com/archives/CD3LP1199)
++
+ Supported by:
+
+
+ +
+
+
+### [Warp, the AI terminal for devs](https://www.warp.dev/cobra)
+[Try Cobra in Warp today](https://www.warp.dev/cobra)
+ +
++
+ +
+ +
+ +# Overview + +Cobra is a library providing a simple interface to create powerful modern CLI +interfaces similar to git & go tools. + +Cobra provides: +* Easy subcommand-based CLIs: `app server`, `app fetch`, etc. +* Fully POSIX-compliant flags (including short & long versions) +* Nested subcommands +* Global, local and cascading flags +* Intelligent suggestions (`app srver`... did you mean `app server`?) +* Automatic help generation for commands and flags +* Grouping help for subcommands +* Automatic help flag recognition of `-h`, `--help`, etc. +* Automatically generated shell autocomplete for your application (bash, zsh, fish, powershell) +* Automatically generated man pages for your application +* Command aliases so you can change things without breaking them +* The flexibility to define your own help, usage, etc. +* Optional seamless integration with [viper](https://github.com/spf13/viper) for 12-factor apps + +# Concepts + +Cobra is built on a structure of commands, arguments & flags. + +**Commands** represent actions, **Args** are things and **Flags** are modifiers for those actions. + +The best applications read like sentences when used, and as a result, users +intuitively know how to interact with them. + +The pattern to follow is +`APPNAME VERB NOUN --ADJECTIVE` + or +`APPNAME COMMAND ARG --FLAG`. + +A few good real world examples may better illustrate this point. + +In the following example, 'server' is a command, and 'port' is a flag: + + hugo server --port=1313 + +In this command we are telling Git to clone the url bare. + + git clone URL --bare + +## Commands + +Command is the central point of the application. Each interaction that +the application supports will be contained in a Command. A command can +have children commands and optionally run an action. + +In the example above, 'server' is the command. + +[More about cobra.Command](https://pkg.go.dev/github.com/spf13/cobra#Command) + +## Flags + +A flag is a way to modify the behavior of a command. Cobra supports +fully POSIX-compliant flags as well as the Go [flag package](https://golang.org/pkg/flag/). +A Cobra command can define flags that persist through to children commands +and flags that are only available to that command. + +In the example above, 'port' is the flag. + +Flag functionality is provided by the [pflag +library](https://github.com/spf13/pflag), a fork of the flag standard library +which maintains the same interface while adding POSIX compliance. + +# Installing +Using Cobra is easy. First, use `go get` to install the latest version +of the library. + +``` +go get -u github.com/spf13/cobra@latest +``` + +Next, include Cobra in your application: + +```go +import "github.com/spf13/cobra" +``` + +# Usage +`cobra-cli` is a command line program to generate cobra applications and command files. +It will bootstrap your application scaffolding to rapidly +develop a Cobra-based application. It is the easiest way to incorporate Cobra into your application. + +It can be installed by running: + +``` +go install github.com/spf13/cobra-cli@latest +``` + +For complete details on using the Cobra-CLI generator, please read [The Cobra Generator README](https://github.com/spf13/cobra-cli/blob/main/README.md) + +For complete details on using the Cobra library, please read [The Cobra User Guide](site/content/user_guide.md). + +# License + +Cobra is released under the Apache 2.0 license. See [LICENSE.txt](LICENSE.txt) diff --git a/vendor/github.com/spf13/cobra/SECURITY.md b/vendor/github.com/spf13/cobra/SECURITY.md new file mode 100644 index 0000000..54e60c2 --- /dev/null +++ b/vendor/github.com/spf13/cobra/SECURITY.md @@ -0,0 +1,105 @@ +# Security Policy + +## Reporting a Vulnerability + +The `cobra` maintainers take security issues seriously and +we appreciate your efforts to _**responsibly**_ disclose your findings. +We will make every effort to swiftly respond and address concerns. + +To report a security vulnerability: + +1. **DO NOT** create a public GitHub issue for the vulnerability! +2. **DO NOT** create a public GitHub Pull Request with a fix for the vulnerability! +3. Send an email to `cobra-security@googlegroups.com`. +4. Include the following details in your report: + - Description of the vulnerability + - Steps to reproduce + - Potential impact of the vulnerability (to your downstream project, to the Go ecosystem, etc.) + - Any potential mitigations you've already identified +5. Allow up to 7 days for an initial response. + You should receive an acknowledgment of your report and an estimated timeline for a fix. +6. (Optional) If you have a fix and would like to contribute your patch, please work + directly with the maintainers via `cobra-security@googlegroups.com` to + coordinate pushing the patch to GitHub, cutting a new release, and disclosing the change. + +## Response Process + +When a security vulnerability report is received, the `cobra` maintainers will: + +1. Confirm receipt of the vulnerability report within 7 days. +2. Assess the report to determine if it constitutes a security vulnerability. +3. If confirmed, assign the vulnerability a severity level and create a timeline for addressing it. +4. Develop and test a fix. +5. Patch the vulnerability and make a new GitHub release: the maintainers will coordinate disclosure with the reporter. +6. Create a new GitHub Security Advisory to inform the broader Go ecosystem + +## Disclosure Policy + +The `cobra` maintainers follow a coordinated disclosure process: + +1. Security vulnerabilities will be addressed as quickly as possible. +2. A CVE (Common Vulnerabilities and Exposures) identifier will be requested for significant vulnerabilities + that are within `cobra` itself. +3. Once a fix is ready, the maintainers will: + - Release a new version containing the fix. + - Update the security advisory with details about the vulnerability. + - Credit the reporter (unless they wish to remain anonymous). + - Credit the fixer (unless they wish to remain anonymous, this may be the same as the reporter). + - Announce the vulnerability through appropriate channels + (GitHub Security Advisory, mailing lists, GitHub Releases, etc.) + +## Supported Versions + +Security fixes will typically only be released for the most recent major release. + +## Upstream Security Issues + +`cobra` generally will not accept vulnerability reports that originate in upstream +dependencies. I.e., if there is a problem in Go code that `cobra` depends on, +it is best to engage that project's maintainers and owners. + +This security policy primarily pertains only to `cobra` itself but if you believe you've +identified a problem that originates in an upstream dependency and is being widely +distributed by `cobra`, please follow the disclosure procedure above: the `cobra` +maintainers will work with you to determine the severity and ecosystem impact. + +## Security Updates and CVEs + +Information about known security vulnerabilities and CVEs affecting `cobra` will +be published as GitHub Security Advisories at +https://github.com/spf13/cobra/security/advisories. + +All users are encouraged to watch the repository and upgrade promptly when +security releases are published. + +## `cobra` Security Best Practices for Users + +When using `cobra` in your CLIs, the `cobra` maintainers recommend the following: + +1. Always use the latest version of `cobra`. +2. [Use Go modules](https://go.dev/blog/using-go-modules) for dependency management. +3. Always use the latest possible version of Go. + +## Security Best Practices for Contributors + +When contributing to `cobra`: + +1. Be mindful of security implications when adding new features or modifying existing ones. +2. Be aware of `cobra`'s extremely large reach: it is used in nearly every Go CLI + (like Kubernetes, Docker, Prometheus, etc. etc.) +3. Write tests that explicitly cover edge cases and potential issues. +4. If you discover a security issue while working on `cobra`, please report it + following the process above rather than opening a public pull request or issue that + addresses the vulnerability. +5. Take personal sec-ops seriously and secure your GitHub account: use [two-factor authentication](https://docs.github.com/en/authentication/securing-your-account-with-two-factor-authentication-2fa), + [sign your commits with a GPG or SSH key](https://docs.github.com/en/authentication/managing-commit-signature-verification/about-commit-signature-verification), + etc. + +## Acknowledgments + +The `cobra` maintainers would like to thank all security researchers and +community members who help keep cobra, its users, and the entire Go ecosystem secure through responsible disclosures!! + +--- + +*This security policy is inspired by the [Open Web Application Security Project (OWASP)](https://owasp.org/) guidelines and security best practices.* diff --git a/vendor/github.com/spf13/cobra/active_help.go b/vendor/github.com/spf13/cobra/active_help.go new file mode 100644 index 0000000..b3e2dad --- /dev/null +++ b/vendor/github.com/spf13/cobra/active_help.go @@ -0,0 +1,60 @@ +// Copyright 2013-2023 The Cobra Authors +// +// Licensed under the Apache License, Version 2.0 (the "License"); +// you may not use this file except in compliance with the License. +// You may obtain a copy of the License at +// +// http://www.apache.org/licenses/LICENSE-2.0 +// +// Unless required by applicable law or agreed to in writing, software +// distributed under the License is distributed on an "AS IS" BASIS, +// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. +// See the License for the specific language governing permissions and +// limitations under the License. + +package cobra + +import ( + "fmt" + "os" +) + +const ( + activeHelpMarker = "_activeHelp_ " + // The below values should not be changed: programs will be using them explicitly + // in their user documentation, and users will be using them explicitly. + activeHelpEnvVarSuffix = "ACTIVE_HELP" + activeHelpGlobalEnvVar = configEnvVarGlobalPrefix + "_" + activeHelpEnvVarSuffix + activeHelpGlobalDisable = "0" +) + +// AppendActiveHelp adds the specified string to the specified array to be used as ActiveHelp. +// Such strings will be processed by the completion script and will be shown as ActiveHelp +// to the user. +// The array parameter should be the array that will contain the completions. +// This function can be called multiple times before and/or after completions are added to +// the array. Each time this function is called with the same array, the new +// ActiveHelp line will be shown below the previous ones when completion is triggered. +func AppendActiveHelp(compArray []Completion, activeHelpStr string) []Completion { + return append(compArray, fmt.Sprintf("%s%s", activeHelpMarker, activeHelpStr)) +} + +// GetActiveHelpConfig returns the value of the ActiveHelp environment variable +//
%s
", basePathEscaped) + _, _ = fmt.Fprintf(w, "- ")
+
+ if len(basePathEscaped) > 1 {
+ var parentURI URI
+ base.CopyTo(&parentURI)
+ parentURI.Update(string(base.Path()) + "/..")
+ parentPathEscaped := html.EscapeString(string(parentURI.Path()))
+ _, _ = fmt.Fprintf(w, `
- .. `, parentPathEscaped) + } + + dirEntries, err := fs.ReadDir(h.filesystem, dirPath) + if err != nil { + return nil, err + } + + fm := make(map[string]fs.FileInfo, len(dirEntries)) + filenames := make([]string, 0, len(dirEntries)) +nestedContinue: + for _, de := range dirEntries { + name := de.Name() + for _, cfs := range h.compressedFileSuffixes { + if strings.HasSuffix(name, cfs) { + // Do not show compressed files on index page. + continue nestedContinue + } + } + fi, err := de.Info() + if err != nil { + ctx.Logger().Printf("cannot fetch information from dir entry %q: %v, skip", name, err) + + continue nestedContinue + } + + fm[name] = fi + filenames = append(filenames, name) + } + + var u URI + base.CopyTo(&u) + u.Update(string(u.Path()) + "/") + + sort.Strings(filenames) + for _, name := range filenames { + u.Update(name) + pathEscaped := html.EscapeString(string(u.Path())) + fi := fm[name] + auxStr := "dir" + className := "dir" + if !fi.IsDir() { + auxStr = fmt.Sprintf("file, %d bytes", fi.Size()) + className = "file" + } + _, _ = fmt.Fprintf(w, `
- %s, %s, last modified %s `, + pathEscaped, className, html.EscapeString(name), auxStr, fsModTime(fi.ModTime())) + } + + _, _ = fmt.Fprintf(w, "