chore: tweak stat card

chore: bump version
chore: update navigator
2025-06-02 10:20:11 +08:00 · 2025-06-02 09:39:57 +08:00 · 2025-06-02 09:39:50 +08:00 · 2025-06-02 01:01:29 +08:00 · 2025-06-02 00:34:45 +08:00 · 2025-06-02 00:32:53 +08:00
815 changed files with 105704 additions and 29117 deletions
@@ -1,11 +1,11 @@
 name: Bug Report
-description: Create a report to help us improve
+description: If something isn't working as expected
 labels: [bug]
 body:
  - type: markdown
    attributes:
      value: |
-        If you are reporting a new issue, make sure that we do not have any duplicates already open. You can ensure this by searching the issue list for this repository. If there is a duplicate, please close your issue and add a comment to the existing issue instead.
+        Before submitting a bug report, please check if the issue is already present in the issues. If it is, please add a reaction to the issue. If it isn't, please fill out the form below.
  - type: textarea
    attributes:
      label: Describe the bug
@@ -24,8 +24,16 @@ body:
        3. See error
    validations:
      required: true
+  - type: input
+    attributes:
+      label: |
+        The version of Memos you're using
+      description: |
+        Provide the version of Memos you're using. Please use the following format: `v0.22.0` instead of `stable` or `latest`.
+    validations:
+      required: true
  - type: textarea
    attributes:
      label: Screenshots or additional context
      description: |
-        Add screenshots or any other context about the problem.
+        If applicable, add screenshots to help explain your problem. And add any other context about the problem here. Such as the device you're using, etc.
@@ -0,0 +1 @@
+blank_issues_enabled: false
@@ -1,28 +1,36 @@
 name: Feature Request
-description: Suggest an idea for this project
+description: If you have a suggestion for a new feature
 labels: [enhancement]
 body:
  - type: markdown
    attributes:
      value: |
-        Thanks for taking the time to suggest an idea for Memos!
-  - type: textarea
-    attributes:
-      label: Is your feature request related to a problem?
-      description: |
-        A clear and concise description of what the problem is.
-      placeholder: |
-        I'm always frustrated when [...]
-    validations:
-      required: true
+        Before submitting a feature request, please check if the issue is already present in the issues. If it is, please add a reaction to the issue. If it isn't, please fill out the form below.
  - type: textarea
    attributes:
      label: Describe the solution you'd like
      description: |
        A clear and concise description of what you want to happen.
+      placeholder: |
+        It would be great if [...]
+    validations:
+      required: true
+  - type: dropdown
+    attributes:
+      label: Type of feature
+      description: What type of feature is this?
+      options:
+        - User Interface (UI)
+        - User Experience (UX)
+        - API
+        - Documentation
+        - Integrations
+        - Other
+      default: 0
    validations:
      required: true
  - type: textarea
    attributes:
      label: Additional context
-      description: Add any other context or screenshots about the feature request.
+      description: |
+        What are you trying to do? Why is this important to you?
@@ -0,0 +1,20 @@
+version: 2
+updates:
+  - package-ecosystem: "github-actions"
+    commit-message:
+      prefix: "chore"
+    directory: "/"
+    schedule:
+      interval: "monthly"
+  - package-ecosystem: npm
+    commit-message:
+      prefix: "chore"
+    directory: "/web"
+    schedule:
+      interval: "monthly"
+  - package-ecosystem: "gomod"
+    commit-message:
+      prefix: "chore"
+    directory: "/"
+    schedule:
+      interval: "monthly"
@@ -1,38 +1,44 @@
 name: Backend Test

 on:
+  push:
+    branches: [main]
  pull_request:
    branches:
      - main
-      - "release/*.*.*"
+    paths:
+      - "go.mod"
+      - "go.sum"
+      - "**.go"

 jobs:
  go-static-checks:
    runs-on: ubuntu-latest
    steps:
-      - uses: actions/checkout@v3
-      - uses: actions/setup-go@v3
+      - uses: actions/checkout@v4
+      - uses: actions/setup-go@v5
        with:
-          go-version: 1.19
+          go-version: 1.24
          check-latest: true
          cache: true
      - name: Verify go.mod is tidy
        run: |
-          go mod tidy -go=1.19
+          go mod tidy -go=1.24
          git diff --exit-code
      - name: golangci-lint
-        uses: golangci/golangci-lint-action@v3
+        uses: golangci/golangci-lint-action@v8
        with:
-          args: -v
+          version: v2.1.6
+          args: --verbose --timeout=3m
          skip-cache: true

  go-tests:
    runs-on: ubuntu-latest
    steps:
-      - uses: actions/checkout@v3
-      - uses: actions/setup-go@v3
+      - uses: actions/checkout@v4
+      - uses: actions/setup-go@v5
        with:
-          go-version: 1.19
+          go-version: 1.24
          check-latest: true
          cache: true
      - name: Run all tests
@@ -0,0 +1,91 @@
+name: Build and Push Canary Image
+
+on:
+  push:
+    branches: [main]
+
+env:
+  DOCKER_PLATFORMS: |
+    linux/amd64
+    linux/arm64
+
+concurrency:
+  group: ${{ github.workflow }}-${{ github.repository }}
+  cancel-in-progress: true
+
+jobs:
+  build-and-push-canary-image:
+    runs-on: ubuntu-latest
+    permissions:
+      contents: read
+      packages: write
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Set up QEMU
+        uses: docker/setup-qemu-action@v3
+        with:
+          platforms: ${{ env.DOCKER_PLATFORMS }}
+
+      - name: Set up Docker Buildx
+        id: buildx
+        uses: docker/setup-buildx-action@v3
+        with:
+          version: latest
+          install: true
+          platforms: ${{ env.DOCKER_PLATFORMS }}
+
+      - name: Docker meta
+        id: meta
+        uses: docker/metadata-action@v5
+        with:
+          images: |
+            neosmemo/memos
+            ghcr.io/usememos/memos
+          flavor: |
+            latest=false
+          tags: |
+            type=raw,value=canary
+
+      - name: Login to Docker Hub
+        uses: docker/login-action@v3
+        with:
+          username: ${{ secrets.DOCKER_HUB_USERNAME }}
+          password: ${{ secrets.DOCKER_HUB_TOKEN }}
+
+      - name: Login to GitHub Container Registry
+        uses: docker/login-action@v3
+        with:
+          registry: ghcr.io
+          username: ${{ github.actor }}
+          password: ${{ github.token }}
+
+      # Frontend build.
+      - uses: pnpm/action-setup@v4.1.0
+        with:
+          version: 10
+      - uses: actions/setup-node@v4
+        with:
+          node-version: "22"
+          cache: pnpm
+          cache-dependency-path: "web/pnpm-lock.yaml"
+      - run: pnpm install
+        working-directory: web
+      - name: Run frontend build
+        run: pnpm release
+        working-directory: web
+
+      - name: Build and Push
+        id: docker_build
+        uses: docker/build-push-action@v6
+        with:
+          context: .
+          file: ./scripts/Dockerfile
+          platforms: ${{ env.DOCKER_PLATFORMS }}
+          push: true
+          tags: ${{ steps.meta.outputs.tags }}
+          labels: ${{ steps.meta.outputs.labels }}
+          cache-from: type=gha
+          cache-to: type=gha,mode=max
+          build-args: |
+            BUILDKIT_INLINE_CACHE=1
@@ -1,45 +0,0 @@
-name: build-and-push-release-image
-
-on:
-  push:
-    branches:
-      # Run on pushing branches like `release/1.0.0`
-      - "release/*.*.*"
-
-jobs:
-  build-and-push-release-image:
-    runs-on: ubuntu-latest
-    steps:
-      - uses: actions/checkout@v3
-
-      - name: Set up QEMU
-        uses: docker/setup-qemu-action@v2
-
-      - name: Extract build args
-        # Extract version from branch name
-        # Example: branch name `release/1.0.0` sets up env.VERSION=1.0.0
-        run: |
-          echo "VERSION=${GITHUB_REF_NAME#release/}" >> $GITHUB_ENV
-
-      - name: Login to Docker Hub
-        uses: docker/login-action@v2
-        with:
-          username: neosmemo
-          password: ${{ secrets.DOCKER_NEOSMEMO_TOKEN }}
-
-      - name: Set up Docker Buildx
-        id: buildx
-        uses: docker/setup-buildx-action@v2
-        with:
-          install: true
-          version: v0.9.1
-
-      - name: Build and Push
-        id: docker_build
-        uses: docker/build-push-action@v3
-        with:
-          context: ./
-          file: ./Dockerfile
-          platforms: linux/amd64,linux/arm64
-          push: true
-          tags: neosmemo/memos:latest, neosmemo/memos:${{ env.VERSION }}
@@ -0,0 +1,103 @@
+name: Build and Push Stable Docker Image
+
+on:
+  push:
+    branches:
+      - "release/**"
+    tags:
+      - "v*.*.*"
+
+env:
+  DOCKER_PLATFORMS: |
+    linux/amd64
+    linux/arm/v7
+    linux/arm64
+
+jobs:
+  build-and-push-image:
+    runs-on: ubuntu-latest
+    permissions:
+      contents: read
+      packages: write
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Set up QEMU
+        uses: docker/setup-qemu-action@v3
+        with:
+          platforms: ${{ env.DOCKER_PLATFORMS }}
+
+      - name: Set up Docker Buildx
+        id: buildx
+        uses: docker/setup-buildx-action@v3
+        with:
+          version: latest
+          install: true
+          platforms: ${{ env.DOCKER_PLATFORMS }}
+
+      - name: Extract version
+        run: |
+          if [[ "$GITHUB_REF_TYPE" == "tag" ]]; then
+            echo "VERSION=${GITHUB_REF_NAME#v}" >> $GITHUB_ENV
+          else
+            echo "VERSION=${GITHUB_REF_NAME#release/}" >> $GITHUB_ENV
+          fi
+
+      - name: Login to Docker Hub
+        uses: docker/login-action@v3
+        with:
+          username: ${{ secrets.DOCKER_HUB_USERNAME }}
+          password: ${{ secrets.DOCKER_HUB_TOKEN }}
+
+      - name: Login to GitHub Container Registry
+        uses: docker/login-action@v3
+        with:
+          registry: ghcr.io
+          username: ${{ github.actor }}
+          password: ${{ github.token }}
+
+      - name: Docker meta
+        id: meta
+        uses: docker/metadata-action@v5
+        with:
+          images: |
+            neosmemo/memos
+            ghcr.io/usememos/memos
+          tags: |
+            type=semver,pattern={{version}},value=${{ env.VERSION }}
+            type=semver,pattern={{major}}.{{minor}},value=${{ env.VERSION }}
+            type=raw,value=stable
+          flavor: |
+            latest=false
+          labels: |
+            org.opencontainers.image.version=${{ env.VERSION }}
+
+      # Frontend build.
+      - uses: pnpm/action-setup@v4.1.0
+        with:
+          version: 10
+      - uses: actions/setup-node@v4
+        with:
+          node-version: "22"
+          cache: pnpm
+          cache-dependency-path: "web/pnpm-lock.yaml"
+      - run: pnpm install
+        working-directory: web
+      - name: Run frontend build
+        run: pnpm release
+        working-directory: web
+
+      - name: Build and Push
+        id: docker_build
+        uses: docker/build-push-action@v6
+        with:
+          context: .
+          file: ./scripts/Dockerfile
+          platforms: ${{ env.DOCKER_PLATFORMS }}
+          push: true
+          tags: ${{ steps.meta.outputs.tags }}
+          labels: ${{ steps.meta.outputs.labels }}
+          cache-from: type=gha
+          cache-to: type=gha,mode=max
+          build-args: |
+            BUILDKIT_INLINE_CACHE=1
@@ -1,37 +0,0 @@
-name: build-and-push-test-image
-
-on:
-  push:
-    branches: [main]
-
-jobs:
-  build-and-push-test-image:
-    runs-on: ubuntu-latest
-    steps:
-      - uses: actions/checkout@v3
-
-      - name: Set up QEMU
-        uses: docker/setup-qemu-action@v2
-
-      - name: Login to Docker Hub
-        uses: docker/login-action@v2
-        with:
-          username: neosmemo
-          password: ${{ secrets.DOCKER_NEOSMEMO_TOKEN }}
-
-      - name: Set up Docker Buildx
-        id: buildx
-        uses: docker/setup-buildx-action@v2
-        with:
-          install: true
-          version: v0.9.1
-
-      - name: Build and Push
-        id: docker_build
-        uses: docker/build-push-action@v3
-        with:
-          context: ./
-          file: ./Dockerfile
-          platforms: linux/amd64
-          push: true
-          tags: neosmemo/memos:test
@@ -0,0 +1,45 @@
+name: Build Artifacts
+
+on:
+  push:
+    tags:
+      - "*"
+
+permissions:
+  contents: write
+
+jobs:
+  goreleaser:
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+        with:
+          fetch-depth: 0
+      - uses: actions/setup-go@v5
+        with:
+          go-version: 1.24
+          check-latest: true
+          cache: true
+      - uses: pnpm/action-setup@v4.1.0
+        with:
+          version: 9
+      - uses: actions/setup-node@v4
+        with:
+          node-version: "20"
+          cache: pnpm
+          cache-dependency-path: "web/pnpm-lock.yaml"
+      - run: pnpm install
+        working-directory: web
+      - run: pnpm release
+        working-directory: web
+      - name: Run GoReleaser
+        uses: goreleaser/goreleaser-action@v6
+        with:
+          # either 'goreleaser' (default) or 'goreleaser-pro'
+          distribution: goreleaser
+          # 'latest', 'nightly', or a semver
+          version: latest
+          args: release --clean --skip=validate
+        env:
+          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
@@ -1,68 +0,0 @@
-# For most projects, this workflow file will not need changing; you simply need
-# to commit it to your repository.
-#
-# You may wish to alter this file to override the set of languages analyzed,
-# or to provide custom queries or build logic.
-#
-# ******** NOTE ********
-# We have attempted to detect the languages in your repository. Please check
-# the `language` matrix defined below to confirm you have the correct set of
-# supported CodeQL languages.
-#
-name: "CodeQL"
-
-on:
-  push:
-    branches: [main]
-  pull_request:
-    # The branches below must be a subset of the branches above
-    branches: [main]
-
-jobs:
-  analyze:
-    name: Analyze
-    runs-on: ubuntu-latest
-    permissions:
-      actions: read
-      contents: read
-      security-events: write
-
-    strategy:
-      fail-fast: false
-      matrix:
-        language: ["go", "javascript"]
-        # CodeQL supports [ 'cpp', 'csharp', 'go', 'java', 'javascript', 'python', 'ruby' ]
-        # Learn more about CodeQL language support at https://git.io/codeql-language-support
-
-    steps:
-      - name: Checkout repository
-        uses: actions/checkout@v2
-
-      # Initializes the CodeQL tools for scanning.
-      - name: Initialize CodeQL
-        uses: github/codeql-action/init@v1
-        with:
-          languages: ${{ matrix.language }}
-          # If you wish to specify custom queries, you can do so here or in a config file.
-          # By default, queries listed here will override any specified in a config file.
-          # Prefix the list here with "+" to use these queries and those in the config file.
-          # queries: ./path/to/local/query, your-org/your-repo/queries@main
-
-      # Autobuild attempts to build any compiled languages  (C/C++, C#, or Java).
-      # If this step fails, then you should remove it and run the build manually (see below)
-      - name: Autobuild
-        uses: github/codeql-action/autobuild@v1
-
-      # ℹ️ Command-line programs to run using the OS shell.
-      # 📚 https://git.io/JvXDl
-
-      # ✏️ If the Autobuild fails above, remove it and uncomment the following three lines
-      #    and modify them (or add more) to build your code if your project
-      #    uses a compiled language
-
-      #- run: |
-      #   make bootstrap
-      #   make release
-
-      - name: Perform CodeQL Analysis
-        uses: github/codeql-action/analyze@v1
@@ -0,0 +1,17 @@
+name: Deploy Demo to Render
+
+on:
+  workflow_dispatch:
+
+jobs:
+  deploy-demo:
+    runs-on: ubuntu-latest
+    steps:
+      - name: Trigger Render Deploy
+        run: |
+          curl -X POST "${{ secrets.RENDER_DEPLOY_HOOK }}" \
+            -H "Content-Type: application/json" \
+            -d '{"trigger": "github_action"}'
+
+      - name: Deployment Status
+        run: echo "Demo deployment triggered successfully on Render"
@@ -1,38 +1,47 @@
 name: Frontend Test

 on:
+  push:
+    branches: [main]
  pull_request:
    branches:
      - main
-      - "release/*.*.*"
+    paths:
+      - "web/**"

 jobs:
-  eslint-checks:
+  static-checks:
    runs-on: ubuntu-latest
    steps:
-      - uses: actions/checkout@v3
-      - uses: actions/setup-node@v3
+      - uses: actions/checkout@v4
+      - uses: pnpm/action-setup@v4.1.0
        with:
-          node-version: "18"
-          cache: yarn
-          cache-dependency-path: "web/yarn.lock"
-      - run: yarn
+          version: 9
+      - uses: actions/setup-node@v4
+        with:
+          node-version: "20"
+          cache: pnpm
+          cache-dependency-path: "web/pnpm-lock.yaml"
+      - run: pnpm install
        working-directory: web
-      - name: Run eslint check
-        run: yarn lint
+      - name: Run check
+        run: pnpm lint
        working-directory: web

  frontend-build:
    runs-on: ubuntu-latest
    steps:
-      - uses: actions/checkout@v3
-      - uses: actions/setup-node@v3
+      - uses: actions/checkout@v4
+      - uses: pnpm/action-setup@v4.1.0
        with:
-          node-version: "18"
-          cache: yarn
-          cache-dependency-path: "web/yarn.lock"
-      - run: yarn
+          version: 9
+      - uses: actions/setup-node@v4
+        with:
+          node-version: "20"
+          cache: pnpm
+          cache-dependency-path: "web/pnpm-lock.yaml"
+      - run: pnpm install
        working-directory: web
      - name: Run frontend build
-        run: yarn build
+        run: pnpm build
        working-directory: web
@@ -1,18 +0,0 @@
-name: 'issue-translator'
-on: 
-  issue_comment: 
-    types: [created]
-  issues: 
-    types: [opened]
-
-jobs:
-  build:
-    runs-on: ubuntu-latest
-    steps:
-      - uses: usthe/issues-translate-action@v2.7
-        with:
-          IS_MODIFY_TITLE: false
-          # not require, default false, . Decide whether to modify the issue title
-          # if true, the robot account @Issues-translate-bot must have modification permissions, invite @Issues-translate-bot to your project or use your custom bot.
-          CUSTOM_BOT_NOTE: Issue is not in English. It has been translated automatically.
-          # not require. Customize the translation robot prefix message.
@@ -0,0 +1,33 @@
+name: Protobuf Linter
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+    branches:
+      - main
+    paths:
+      - "proto/**"
+
+jobs:
+  lint-protos:
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+        with:
+          fetch-depth: 0
+      - name: Setup buf
+        uses: bufbuild/buf-setup-action@v1
+        with:
+          github_token: ${{ github.token }}
+      - name: buf lint
+        uses: bufbuild/buf-lint-action@v1
+        with:
+          input: "proto"
+      - name: buf format
+        run: |
+          if [[ $(buf format -d) ]]; then
+            echo "Run 'buf format -d'"
+            exit 1
+          fi
@@ -0,0 +1,17 @@
+name: Close Stale Issues
+
+on:
+  schedule:
+    - cron: "0 */8 * * *"
+
+jobs:
+  stale:
+    runs-on: ubuntu-latest
+    permissions:
+      issues: write
+
+    steps:
+      - uses: actions/stale@v9.1.0
+        with:
+          days-before-issue-stale: 14
+          days-before-issue-close: 7
@@ -1,97 +0,0 @@
-name: Build PR Image
-on:
-  pull_request:
-    types: [opened, synchronize, reopened, closed]
-
-jobs:
-  build-memos:
-    name: Build and push `Memos`
-    runs-on: ubuntu-latest
-    outputs:
-      tags: ${{ steps.meta.outputs.tags }}
-    if: ${{ github.event.action != 'closed' }}
-    steps:
-      - name: Checkout git repo
-        uses: actions/checkout@v3
-
-      - name: Set up Docker Buildx
-        uses: docker/setup-buildx-action@v2
-
-      - name: Generate UUID image name
-        id: uuid
-        run: echo "UUID_WORKER=$(uuidgen)" >> $GITHUB_ENV
-
-      - name: Docker metadata
-        id: meta
-        uses: docker/metadata-action@v4
-        with:
-          images: registry.uffizzi.com/${{ env.UUID_WORKER }}
-          tags: |
-            type=raw,value=60d
-
-      - name: Build and Push Image to registry.uffizzi.com - Uffizzi's ephemeral Registry
-        uses: docker/build-push-action@v3
-        with:
-          context: ./
-          file: Dockerfile
-          tags: ${{ steps.meta.outputs.tags }}
-          labels: ${{ steps.meta.outputs.labels }}
-          push: true
-          cache-from: type=gha
-          cache-to: type=gha, mode=max
-
-  render-compose-file:
-    name: Render Docker Compose File
-    # Pass output of this workflow to another triggered by `workflow_run` event.
-    runs-on: ubuntu-latest
-    needs:
-      - build-memos
-    outputs:
-      compose-file-cache-key: ${{ steps.hash.outputs.hash }}
-    steps:
-      - name: Checkout git repo
-        uses: actions/checkout@v3
-      - name: Render Compose File
-        run: |
-          MEMOS_IMAGE=${{ needs.build-memos.outputs.tags }}
-          export MEMOS_IMAGE
-          # Render simple template from environment variables.
-          envsubst < docker-compose.uffizzi.yml > docker-compose.rendered.yml
-          cat docker-compose.rendered.yml
-      - name: Upload Rendered Compose File as Artifact
-        uses: actions/upload-artifact@v3
-        with:
-          name: preview-spec
-          path: docker-compose.rendered.yml
-          retention-days: 2
-      - name: Serialize PR Event to File
-        run: |
-          cat << EOF > event.json
-          ${{ toJSON(github.event) }}
-
-          EOF
-      - name: Upload PR Event as Artifact
-        uses: actions/upload-artifact@v3
-        with:
-          name: preview-spec
-          path: event.json
-          retention-days: 2
-
-  delete-preview:
-    name: Call for Preview Deletion
-    runs-on: ubuntu-latest
-    if: ${{ github.event.action == 'closed' }}
-    steps:
-      # If this PR is closing, we will not render a compose file nor pass it to the next workflow.
-      - name: Serialize PR Event to File
-        run: |
-          cat << EOF > event.json
-          ${{ toJSON(github.event) }}
-
-          EOF
-      - name: Upload PR Event as Artifact
-        uses: actions/upload-artifact@v3
-        with:
-          name: preview-spec
-          path: event.json
-          retention-days: 2
@@ -1,88 +0,0 @@
-name: Deploy Uffizzi Preview
-
-on:
-  workflow_run:
-    workflows:
-      - "Build PR Image"
-    types:
-      - completed
-
-
-jobs:
-  cache-compose-file:
-    name: Cache Compose File
-    if: ${{ github.event.workflow_run.conclusion == 'success' }}
-    runs-on: ubuntu-latest
-    outputs:
-      compose-file-cache-key: ${{ env.HASH }}
-      pr-number: ${{ env.PR_NUMBER }}
-    steps:
-      - name: 'Download artifacts'
-        # Fetch output (zip archive) from the workflow run that triggered this workflow.
-        uses: actions/github-script@v6
-        with:
-          script: |
-            let allArtifacts = await github.rest.actions.listWorkflowRunArtifacts({
-               owner: context.repo.owner,
-               repo: context.repo.repo,
-               run_id: context.payload.workflow_run.id,
-            });
-            let matchArtifact = allArtifacts.data.artifacts.filter((artifact) => {
-              return artifact.name == "preview-spec"
-            })[0];
-            let download = await github.rest.actions.downloadArtifact({
-               owner: context.repo.owner,
-               repo: context.repo.repo,
-               artifact_id: matchArtifact.id,
-               archive_format: 'zip',
-            });
-            let fs = require('fs');
-            fs.writeFileSync(`${process.env.GITHUB_WORKSPACE}/preview-spec.zip`, Buffer.from(download.data));
-
-      - name: 'Unzip artifact'
-        run: unzip preview-spec.zip
-      - name: Read Event into ENV
-        run: |
-          echo 'EVENT_JSON<<EOF' >> $GITHUB_ENV
-          cat event.json >> $GITHUB_ENV
-          echo 'EOF' >> $GITHUB_ENV
-
-      - name: Hash Rendered Compose File
-        id: hash
-        # If the previous workflow was triggered by a PR close event, we will not have a compose file artifact.
-        if: ${{ fromJSON(env.EVENT_JSON).action != 'closed' }}
-        run: echo "HASH=$(md5sum docker-compose.rendered.yml | awk '{ print $1 }')" >> $GITHUB_ENV
-      - name: Cache Rendered Compose File
-        if: ${{ fromJSON(env.EVENT_JSON).action != 'closed' }}
-        uses: actions/cache@v3
-        with:
-          path: docker-compose.rendered.yml
-          key: ${{ env.HASH }}
-
-      - name: Read PR Number From Event Object
-        id: pr
-        run: echo "PR_NUMBER=${{ fromJSON(env.EVENT_JSON).number }}" >> $GITHUB_ENV
-      - name: DEBUG - Print Job Outputs
-        if: ${{ runner.debug }}
-        run: |
-          echo "PR number: ${{ env.PR_NUMBER }}"
-          echo "Compose file hash: ${{ env.HASH }}"
-          cat event.json
-
-  deploy-uffizzi-preview:
-    name: Use Remote Workflow to Preview on Uffizzi
-    if: ${{ github.event.workflow_run.conclusion == 'success' }}
-    needs:
-      - cache-compose-file
-    uses: UffizziCloud/preview-action/.github/workflows/reusable.yaml@v2
-    with:
-      # If this workflow was triggered by a PR close event, cache-key will be an empty string
-      # and this reusable workflow will delete the preview deployment.
-      compose-file-cache-key: ${{ needs.cache-compose-file.outputs.compose-file-cache-key }}
-      compose-file-cache-path: docker-compose.rendered.yml
-      server: https://app.uffizzi.com
-      pr-number: ${{ needs.cache-compose-file.outputs.pr-number }}
-    permissions:
-      contents: read
-      pull-requests: write
-      id-token: write
@@ -1,6 +1,3 @@
-# Air (hot reload) generated
-.air
-
 # temp folder
 tmp

@@ -15,4 +12,10 @@ build
 # Jetbrains
 .idea

-bin/air
+# Docker Compose Environment File
+.env
+
+dist
+
+# VSCode settings
+.vscode
@@ -1,6 +1,7 @@
+version: "2"
+
 linters:
  enable:
-    - goimports
    - revive
    - govet
    - staticcheck
@@ -10,55 +11,91 @@ linters:
    - rowserrcheck
    - nilerr
    - godot
+    - forbidigo
+    - mirror
+    - bodyclose
+  disable:
+    - errcheck
+  settings:
+    exhaustive:
+      explicit-exhaustive-switch: false
+    staticcheck:
+      checks:
+        - all
+        - -ST1000
+        - -ST1003
+        - -ST1021
+        - -QF1003
+    revive:
+      # Default to run all linters so that new rules in the future could automatically be added to the static check.
+      enable-all-rules: true
+      rules:
+        # The following rules are too strict and make coding harder. We do not enable them for now.
+        - name: file-header
+          disabled: true
+        - name: line-length-limit
+          disabled: true
+        - name: function-length
+          disabled: true
+        - name: max-public-structs
+          disabled: true
+        - name: function-result-limit
+          disabled: true
+        - name: banned-characters
+          disabled: true
+        - name: argument-limit
+          disabled: true
+        - name: cognitive-complexity
+          disabled: true
+        - name: cyclomatic
+          disabled: true
+        - name: confusing-results
+          disabled: true
+        - name: add-constant
+          disabled: true
+        - name: flag-parameter
+          disabled: true
+        - name: nested-structs
+          disabled: true
+        - name: import-shadowing
+          disabled: true
+        - name: early-return
+          disabled: true
+        - name: use-any
+          disabled: true
+        - name: exported
+          disabled: true
+        - name: unhandled-error
+          disabled: true
+        - name: if-return
+          disabled: true
+        - name: max-control-nesting
+          disabled: true
+        - name: redefines-builtin-id
+          disabled: true
+        - name: package-comments
+          disabled: true
+    gocritic:
+      disabled-checks:
+        - ifElseChain
+    govet:
+      settings:
+        printf: # The name of the analyzer, run `go tool vet help` to see the list of all analyzers
+          funcs: # Run `go tool vet help printf` to see the full configuration of `printf`.
+            - common.Errorf
+      enable-all: true
+      disable:
+        - fieldalignment
+        - shadow
+    forbidigo:
+      forbid:
+        - pattern: 'fmt\.Errorf(# Please use errors\.Wrap\|Wrapf\|Errorf instead)?'
+        - pattern: 'ioutil\.ReadDir(# Please use os\.ReadDir)?'

-issues:
-  exclude:
-    - Rollback
-    - fmt.Printf
-    - fmt.Print
-
-linters-settings:
-  revive:
-    enable-all-rules: true
-    rules:
-      - name: file-header
-        disabled: true
-      - name: line-length-limit
-        disabled: true
-      - name: function-length
-        disabled: true
-      - name: max-public-structs
-        disabled: true
-      - name: function-result-limit
-        disabled: true
-      - name: banned-characters
-        disabled: true
-      - name: argument-limit
-        disabled: true
-      - name: cognitive-complexity
-        disabled: true
-      - name: cyclomatic
-        disabled: true
-      - name: confusing-results
-        disabled: true
-      - name: add-constant
-        disabled: true
-      - name: flag-parameter
-        disabled: true
-      - name: nested-structs
-        disabled: true
-      - name: import-shadowing
-        disabled: true
-      - name: early-return
-        disabled: true
-  gocritic:
-    disabled-checks:
-      - ifElseChain
-  govet:
-    settings:
-      printf:
-        funcs:
-          - common.Errorf
-  forbidigo:
-    forbid:
-      - 'fmt\.Errorf(# Please use errors\.Wrap\|Wrapf\|Errorf instead)?'
+formatters:
+  enable:
+    - goimports
+  settings:
+    goimports:
+      local-prefixes:
+        - github.com/usememos/memos
@@ -0,0 +1,36 @@
+version: 1
+
+before:
+  hooks:
+    # You may remove this if you don't use go modules.
+    - go mod tidy
+
+builds:
+  - main: ./bin/memos
+    binary: memos
+    goos:
+      - linux
+      - darwin
+
+archives:
+  - format: tar.gz
+    # this name template makes the OS and Arch compatible with the results of `uname`.
+    name_template: >-
+      {{ .ProjectName }}_{{ .Tag }}_{{ .Os }}_{{ .Arch }}
+
+changelog:
+  sort: asc
+  filters:
+    exclude:
+      - "^docs:"
+      - "^test:"
+
+checksum:
+  disable: true
+
+release:
+  draft: true
+  replace_existing_draft: true
+  make_latest: true
+  mode: replace
+  skip_upload: false
@@ -1,3 +0,0 @@
-{
-  "recommendations": ["golang.go"]
-}
@@ -1,12 +0,0 @@
-{
-  "folders": [
-    {
-      "name": "server",
-      "path": "../"
-    },
-    {
-      "name": "web",
-      "path": "../web"
-    }
-  ]
-}
@@ -1,5 +0,0 @@
-{
-  "go.lintOnSave": "workspace",
-  "go.lintTool": "golangci-lint",
-  "go.inferGopath": false
-}
@@ -1,31 +0,0 @@
-# Build frontend dist.
-FROM node:18.12.1-alpine3.16 AS frontend
-WORKDIR /frontend-build
-
-COPY ./web/ .
-
-RUN yarn && yarn build
-
-# Build backend exec file.
-FROM golang:1.19.3-alpine3.16 AS backend
-WORKDIR /backend-build
-
-RUN apk update && apk add --no-cache gcc musl-dev
-
-COPY . .
-COPY --from=frontend /frontend-build/dist ./server/dist
-
-RUN go build -o memos ./main.go
-
-# Make workspace with above generated files.
-FROM alpine:3.16 AS monolithic
-WORKDIR /usr/local/memos
-
-COPY --from=backend /backend-build/memos /usr/local/memos/
-
-EXPOSE 5230
-
-# Directory to store the data, which can be referenced as the mounting point.
-RUN mkdir -p /var/opt/memos
-
-ENTRYPOINT ["./memos", "--mode", "prod", "--port", "5230"]
@@ -1,6 +1,6 @@
 MIT License

-Copyright (c) 2022 Memos
+Copyright (c) 2025 Memos

 Permission is hereby granted, free of charge, to any person obtaining a copy
 of this software and associated documentation files (the "Software"), to deal
@@ -1,62 +1,59 @@
-<p align="center"><a href="https://usememos.com"><img height="64px" src="https://raw.githubusercontent.com/usememos/memos/main/resources/logo-full.webp" alt="✍️ memos" /></a></p>
+# Memos - Open Source, Self-hosted, Your Notes, Your Way

-<p align="center">
-  <a href="https://github.com/usememos/memos/stargazers"><img alt="GitHub stars" src="https://img.shields.io/github/stars/usememos/memos" /></a>
-  <a href="https://hub.docker.com/r/neosmemo/memos"><img alt="Docker pull" src="https://img.shields.io/docker/pulls/neosmemo/memos.svg" /></a>
-  <a href="https://hosted.weblate.org/engage/memos/"><img src="https://hosted.weblate.org/widgets/memos/-/svg-badge.svg" alt="Translation status" /></a>
+<img align="right" height="96px" src="https://www.usememos.com/logo-rounded.png" alt="Memos" />
+
+An open-source, self-hosted note-taking solution designed for seamless deployment and multi-platform access. Experience effortless plain text writing with pain-free, complemented by robust Markdown syntax support for enhanced formatting.
+
+<a href="https://www.usememos.com">Home Page</a> •
+<a href="https://www.usememos.com/blog">Blogs</a> •
+<a href="https://www.usememos.com/docs">Docs</a> •
+<a href="https://demo.usememos.com/">Live Demo</a>
+
+<p>
+  <a href="https://deepwiki.com/usememos/memos"><img src="https://devin.ai/assets/deepwiki-badge.png" alt="Ask DeepWiki" height="20"/></a>
+  <a href="https://hub.docker.com/r/neosmemo/memos"><img alt="Docker pull" src="https://img.shields.io/docker/pulls/neosmemo/memos.svg"/></a>
+  <a href="https://hub.docker.com/r/neosmemo/memos"><img alt="Docker image size" src="https://img.shields.io/docker/image-size/neosmemo/memos?sort=semver"/></a>
  <a href="https://discord.gg/tfPJa4UmAv"><img alt="Discord" src="https://img.shields.io/badge/discord-chat-5865f2?logo=discord&logoColor=f5f5f5" /></a>
 </p>

-<p align="center">
-  <a href="https://demo.usememos.com/">Live Demo</a> •
-  Discuss in <a href="https://t.me/+-_tNF1k70UU4ZTc9">Telegram</a> / <a href="https://discord.gg/tfPJa4UmAv">Discord</a>
-</p>
+![demo](https://www.usememos.com/demo.png)

-![demo](https://usememos.com/demo.webp)
+## Features

-## Key points
-
- Open source and free forever
- Self-hosting with Docker in seconds
- Markdown support
- Customizable and sharable
- RESTful API for self-service
+- **Privacy First** 🏡: Your data, your control. All runtime data is securely stored in your local database.
+- **Create at Speed** ✍️: Write and save content as plain text for quick access, with Markdown support for fast formatting and easy sharing.
+- **Lightweight but Powerful** ⚡: Built with Go and React.js, our app combines a compact architecture with powerful performance.
+- **Customizable** 🧩: Personalize your experience by customizing the server name, icon, description, theme, and execution scripts.
+- **Open Source** 🦦: Fully open source, with all code available on GitHub for transparency and collaboration.
+- **Free to Use** 💸: Enjoy all features at no cost, no hidden fees, no subscriptions.

 ## Deploy with Docker in seconds

 ```bash
-docker run -d --name memos -p 5230:5230 -v ~/.memos/:/var/opt/memos neosmemo/memos:latest
+docker run -d --name memos -p 5230:5230 -v ~/.memos/:/var/opt/memos neosmemo/memos:stable
 ```

+> [!NOTE]
+> This command is only applicable for Unix/Linux systems. For Windows, please refer to the detailed [documentation](https://www.usememos.com/docs/install/container-install#docker-on-windows).
+>
 > The `~/.memos/` directory will be used as the data directory on your local machine, while `/var/opt/memos` is the directory of the volume in Docker and should not be modified.

-Learn more about [other installation methods](https://usememos.com/docs/install).
+Learn more about [other installation methods](https://www.usememos.com/docs/install).
+
+> [!WARNING]
+> Memos is still under active development, so you may encounter bugs or breaking changes as we improve.

 ## Contribution

 Contributions are what make the open-source community such an amazing place to learn, inspire, and create. We greatly appreciate any contributions you make. Thank you for being a part of our community! 🥰

-<a href="https://github.com/usememos/memos/graphs/contributors">
-  <img src="https://contrib.rocks/image?repo=usememos/memos" />
-</a>
-
-Here are some products made by our community:
-
- [Moe Memos](https://memos.moe/) - Third party client for iOS and Android
- [lmm214/memos-bber](https://github.com/lmm214/memos-bber) - Chrome extension
- [Rabithua/memos_wmp](https://github.com/Rabithua/memos_wmp) - WeChat MiniProgram
- [qazxcdswe123/telegramMemoBot](https://github.com/qazxcdswe123/telegramMemoBot) - Telegram bot
- [eallion/memos.top](https://github.com/eallion/memos.top) - Static page rendered with the Memos API
- [eindex/logseq-memos-sync](https://github.com/EINDEX/logseq-memos-sync) - Logseq plugin
- [JakeLaoyu/memos-import-from-flomo](https://github.com/JakeLaoyu/memos-import-from-flomo) - Import data. Support from flomo, wechat reading
- [Send to memos](https://sharecuts.cn/shortcut/12640) - A shortcut for iOS
- [Memos Raycast Extension](https://www.raycast.com/JakeYu/memos) - Raycast extension
- [Memos Desktop](https://github.com/xudaolong/memos-desktop) - Third party client for MacOS and Windows
-
-## Acknowledgements
-
- Thanks [Uffizzi](https://www.uffizzi.com/) for sponsoring preview environments for PRs.
+Guide to [contribution](https://www.usememos.com/docs/contribution/development).

 ## Star history

 [![Star History Chart](https://api.star-history.com/svg?repos=usememos/memos&type=Date)](https://star-history.com/#usememos/memos&Date)
+
+## Other Projects
+
+- [**Slash**](https://github.com/yourselfhosted/slash): An open source, self-hosted bookmarks and link sharing platform. Save and share your links very easily.
+- [**Gomark**](https://github.com/usememos/gomark): A markdown parser written in Go for Memos. And its [WebAssembly version](https://github.com/usememos/gomark-wasm) is also available.
@@ -4,4 +4,4 @@

 Report security bugs via GitHub [issues](https://github.com/usememos/memos/issues).

-For more information, please contact [stevenlgtm@gmail.com](stevenlgtm@gmail.com).
+For more information, please contact [usememos@gmail.com](usememos@gmail.com).
@@ -1,137 +0,0 @@
-package api
-
-import "github.com/usememos/memos/server/profile"
-
-// ActivityType is the type for an activity.
-type ActivityType string
-
-const (
-	// User related.
-
-	// ActivityUserCreate is the type for creating users.
-	ActivityUserCreate ActivityType = "user.create"
-	// ActivityUserUpdate is the type for updating users.
-	ActivityUserUpdate ActivityType = "user.update"
-	// ActivityUserDelete is the type for deleting users.
-	ActivityUserDelete ActivityType = "user.delete"
-	// ActivityUserAuthSignIn is the type for user signin.
-	ActivityUserAuthSignIn ActivityType = "user.auth.signin"
-	// ActivityUserAuthSignUp is the type for user signup.
-	ActivityUserAuthSignUp ActivityType = "user.auth.signup"
-	// ActivityUserSettingUpdate is the type for updating user settings.
-	ActivityUserSettingUpdate ActivityType = "user.setting.update"
-
-	// Memo related.
-
-	// ActivityMemoCreate is the type for creating memos.
-	ActivityMemoCreate ActivityType = "memo.create"
-	// ActivityMemoUpdate is the type for updating memos.
-	ActivityMemoUpdate ActivityType = "memo.update"
-	// ActivityMemoDelete is the type for deleting memos.
-	ActivityMemoDelete ActivityType = "memo.delete"
-
-	// Shortcut related.
-
-	// ActivityShortcutCreate is the type for creating shortcuts.
-	ActivityShortcutCreate ActivityType = "shortcut.create"
-	// ActivityShortcutUpdate is the type for updating shortcuts.
-	ActivityShortcutUpdate ActivityType = "shortcut.update"
-	// ActivityShortcutDelete is the type for deleting shortcuts.
-	ActivityShortcutDelete ActivityType = "shortcut.delete"
-
-	// Resource related.
-
-	// ActivityResourceCreate is the type for creating resources.
-	ActivityResourceCreate ActivityType = "resource.create"
-	// ActivityResourceDelete is the type for deleting resources.
-	ActivityResourceDelete ActivityType = "resource.delete"
-
-	// Tag related.
-
-	// ActivityTagCreate is the type for creating tags.
-	ActivityTagCreate ActivityType = "tag.create"
-	// ActivityTagDelete is the type for deleting tags.
-	ActivityTagDelete ActivityType = "tag.delete"
-
-	// Server related.
-
-	// ActivityServerStart is the type for starting server.
-	ActivityServerStart ActivityType = "server.start"
-)
-
-// ActivityLevel is the level of activities.
-type ActivityLevel string
-
-const (
-	// ActivityInfo is the INFO level of activities.
-	ActivityInfo ActivityLevel = "INFO"
-	// ActivityWarn is the WARN level of activities.
-	ActivityWarn ActivityLevel = "WARN"
-	// ActivityError is the ERROR level of activities.
-	ActivityError ActivityLevel = "ERROR"
-)
-
-type ActivityUserCreatePayload struct {
-	UserID   int    `json:"userId"`
-	Username string `json:"username"`
-	Role     Role   `json:"role"`
-}
-
-type ActivityUserAuthSignInPayload struct {
-	UserID int    `json:"userId"`
-	IP     string `json:"ip"`
-}
-
-type ActivityUserAuthSignUpPayload struct {
-	Username string `json:"username"`
-	IP       string `json:"ip"`
-}
-
-type ActivityMemoCreatePayload struct {
-	Content    string `json:"content"`
-	Visibility string `json:"visibility"`
-}
-
-type ActivityShortcutCreatePayload struct {
-	Title   string `json:"title"`
-	Payload string `json:"payload"`
-}
-
-type ActivityResourceCreatePayload struct {
-	Filename string `json:"filename"`
-	Type     string `json:"type"`
-	Size     int64  `json:"size"`
-}
-
-type ActivityTagCreatePayload struct {
-	TagName string `json:"tagName"`
-}
-
-type ActivityServerStartPayload struct {
-	ServerID string           `json:"serverId"`
-	Profile  *profile.Profile `json:"profile"`
-}
-
-type Activity struct {
-	ID int `json:"id"`
-
-	// Standard fields
-	CreatorID int   `json:"creatorId"`
-	CreatedTs int64 `json:"createdTs"`
-
-	// Domain specific fields
-	Type    ActivityType  `json:"type"`
-	Level   ActivityLevel `json:"level"`
-	Payload string        `json:"payload"`
-}
-
-// ActivityCreate is the API message for creating an activity.
-type ActivityCreate struct {
-	// Standard fields
-	CreatorID int
-
-	// Domain specific fields
-	Type    ActivityType `json:"type"`
-	Level   ActivityLevel
-	Payload string `json:"payload"`
-}
@@ -1,17 +0,0 @@
-package api
-
-type SignIn struct {
-	Username string `json:"username"`
-	Password string `json:"password"`
-}
-
-type SSOSignIn struct {
-	IdentityProviderID int    `json:"identityProviderId"`
-	Code               string `json:"code"`
-	RedirectURI        string `json:"redirectUri"`
-}
-
-type SignUp struct {
-	Username string `json:"username"`
-	Password string `json:"password"`
-}
@@ -1,24 +0,0 @@
-package api
-
-// UnknownID is the ID for unknowns.
-const UnknownID = -1
-
-// RowStatus is the status for a row.
-type RowStatus string
-
-const (
-	// Normal is the status for a normal row.
-	Normal RowStatus = "NORMAL"
-	// Archived is the status for an archived row.
-	Archived RowStatus = "ARCHIVED"
-)
-
-func (e RowStatus) String() string {
-	switch e {
-	case Normal:
-		return "NORMAL"
-	case Archived:
-		return "ARCHIVED"
-	}
-	return ""
-}
@@ -1,58 +0,0 @@
-package api
-
-type IdentityProviderType string
-
-const (
-	IdentityProviderOAuth2 IdentityProviderType = "OAUTH2"
-)
-
-type IdentityProviderConfig struct {
-	OAuth2Config *IdentityProviderOAuth2Config `json:"oauth2Config"`
-}
-
-type IdentityProviderOAuth2Config struct {
-	ClientID     string        `json:"clientId"`
-	ClientSecret string        `json:"clientSecret"`
-	AuthURL      string        `json:"authUrl"`
-	TokenURL     string        `json:"tokenUrl"`
-	UserInfoURL  string        `json:"userInfoUrl"`
-	Scopes       []string      `json:"scopes"`
-	FieldMapping *FieldMapping `json:"fieldMapping"`
-}
-
-type FieldMapping struct {
-	Identifier  string `json:"identifier"`
-	DisplayName string `json:"displayName"`
-	Email       string `json:"email"`
-}
-
-type IdentityProvider struct {
-	ID               int                     `json:"id"`
-	Name             string                  `json:"name"`
-	Type             IdentityProviderType    `json:"type"`
-	IdentifierFilter string                  `json:"identifierFilter"`
-	Config           *IdentityProviderConfig `json:"config"`
-}
-
-type IdentityProviderCreate struct {
-	Name             string                  `json:"name"`
-	Type             IdentityProviderType    `json:"type"`
-	IdentifierFilter string                  `json:"identifierFilter"`
-	Config           *IdentityProviderConfig `json:"config"`
-}
-
-type IdentityProviderFind struct {
-	ID *int
-}
-
-type IdentityProviderPatch struct {
-	ID               int
-	Type             IdentityProviderType    `json:"type"`
-	Name             *string                 `json:"name"`
-	IdentifierFilter *string                 `json:"identifierFilter"`
-	Config           *IdentityProviderConfig `json:"config"`
-}
-
-type IdentityProviderDelete struct {
-	ID int
-}
@@ -1,97 +0,0 @@
-package api
-
-// MaxContentLength means the max memo content bytes is 1MB.
-const MaxContentLength = 1 << 30
-
-// Visibility is the type of a visibility.
-type Visibility string
-
-const (
-	// Public is the PUBLIC visibility.
-	Public Visibility = "PUBLIC"
-	// Protected is the PROTECTED visibility.
-	Protected Visibility = "PROTECTED"
-	// Private is the PRIVATE visibility.
-	Private Visibility = "PRIVATE"
-)
-
-func (e Visibility) String() string {
-	switch e {
-	case Public:
-		return "PUBLIC"
-	case Protected:
-		return "PROTECTED"
-	case Private:
-		return "PRIVATE"
-	}
-	return "PRIVATE"
-}
-
-type Memo struct {
-	ID int `json:"id"`
-
-	// Standard fields
-	RowStatus RowStatus `json:"rowStatus"`
-	CreatorID int       `json:"creatorId"`
-	CreatedTs int64     `json:"createdTs"`
-	UpdatedTs int64     `json:"updatedTs"`
-
-	// Domain specific fields
-	Content    string     `json:"content"`
-	Visibility Visibility `json:"visibility"`
-	Pinned     bool       `json:"pinned"`
-
-	// Related fields
-	CreatorName  string      `json:"creatorName"`
-	ResourceList []*Resource `json:"resourceList"`
-}
-
-type MemoCreate struct {
-	// Standard fields
-	CreatorID int    `json:"-"`
-	CreatedTs *int64 `json:"createdTs"`
-
-	// Domain specific fields
-	Visibility Visibility `json:"visibility"`
-	Content    string     `json:"content"`
-
-	// Related fields
-	ResourceIDList []int `json:"resourceIdList"`
-}
-
-type MemoPatch struct {
-	ID int `json:"-"`
-
-	// Standard fields
-	CreatedTs *int64 `json:"createdTs"`
-	UpdatedTs *int64
-	RowStatus *RowStatus `json:"rowStatus"`
-
-	// Domain specific fields
-	Content    *string     `json:"content"`
-	Visibility *Visibility `json:"visibility"`
-
-	// Related fields
-	ResourceIDList []int `json:"resourceIdList"`
-}
-
-type MemoFind struct {
-	ID *int
-
-	// Standard fields
-	RowStatus *RowStatus
-	CreatorID *int
-
-	// Domain specific fields
-	Pinned         *bool
-	ContentSearch  *string
-	VisibilityList []Visibility
-
-	// Pagination
-	Limit  *int
-	Offset *int
-}
-
-type MemoDelete struct {
-	ID int
-}
@@ -1,26 +0,0 @@
-package api
-
-type MemoOrganizer struct {
-	ID int
-
-	// Domain specific fields
-	MemoID int
-	UserID int
-	Pinned bool
-}
-
-type MemoOrganizerUpsert struct {
-	MemoID int  `json:"-"`
-	UserID int  `json:"-"`
-	Pinned bool `json:"pinned"`
-}
-
-type MemoOrganizerFind struct {
-	MemoID int
-	UserID int
-}
-
-type MemoOrganizerDelete struct {
-	MemoID *int
-	UserID *int
-}
@@ -1,24 +0,0 @@
-package api
-
-type MemoResource struct {
-	MemoID     int
-	ResourceID int
-	CreatedTs  int64
-	UpdatedTs  int64
-}
-
-type MemoResourceUpsert struct {
-	MemoID     int `json:"-"`
-	ResourceID int
-	UpdatedTs  *int64
-}
-
-type MemoResourceFind struct {
-	MemoID     *int
-	ResourceID *int
-}
-
-type MemoResourceDelete struct {
-	MemoID     *int
-	ResourceID *int
-}
@@ -1,5 +0,0 @@
-package api
-
-type OpenAICompletionRequest struct {
-	Prompt string `json:"prompt"`
-}
@@ -1,61 +0,0 @@
-package api
-
-type Resource struct {
-	ID int `json:"id"`
-
-	// Standard fields
-	CreatorID int   `json:"creatorId"`
-	CreatedTs int64 `json:"createdTs"`
-	UpdatedTs int64 `json:"updatedTs"`
-
-	// Domain specific fields
-	Filename     string     `json:"filename"`
-	Blob         []byte     `json:"-"`
-	ExternalLink string     `json:"externalLink"`
-	Type         string     `json:"type"`
-	Size         int64      `json:"size"`
-	Visibility   Visibility `json:"visibility"`
-
-	// Related fields
-	LinkedMemoAmount int `json:"linkedMemoAmount"`
-}
-
-type ResourceCreate struct {
-	// Standard fields
-	CreatorID int `json:"-"`
-
-	// Domain specific fields
-	Filename     string     `json:"filename"`
-	Blob         []byte     `json:"-"`
-	ExternalLink string     `json:"externalLink"`
-	Type         string     `json:"type"`
-	Size         int64      `json:"-"`
-	Visibility   Visibility `json:"visibility"`
-}
-
-type ResourceFind struct {
-	ID *int `json:"id"`
-
-	// Standard fields
-	CreatorID *int `json:"creatorId"`
-
-	// Domain specific fields
-	Filename *string `json:"filename"`
-	MemoID   *int
-	GetBlob  bool
-}
-
-type ResourcePatch struct {
-	ID int `json:"-"`
-
-	// Standard fields
-	UpdatedTs *int64
-
-	// Domain specific fields
-	Filename   *string     `json:"filename"`
-	Visibility *Visibility `json:"visibility"`
-}
-
-type ResourceDelete struct {
-	ID int
-}
@@ -1,53 +0,0 @@
-package api
-
-type Shortcut struct {
-	ID int `json:"id"`
-
-	// Standard fields
-	RowStatus RowStatus `json:"rowStatus"`
-	CreatorID int       `json:"creatorId"`
-	CreatedTs int64     `json:"createdTs"`
-	UpdatedTs int64     `json:"updatedTs"`
-
-	// Domain specific fields
-	Title   string `json:"title"`
-	Payload string `json:"payload"`
-}
-
-type ShortcutCreate struct {
-	// Standard fields
-	CreatorID int `json:"-"`
-
-	// Domain specific fields
-	Title   string `json:"title"`
-	Payload string `json:"payload"`
-}
-
-type ShortcutPatch struct {
-	ID int `json:"-"`
-
-	// Standard fields
-	UpdatedTs *int64
-	RowStatus *RowStatus `json:"rowStatus"`
-
-	// Domain specific fields
-	Title   *string `json:"title"`
-	Payload *string `json:"payload"`
-}
-
-type ShortcutFind struct {
-	ID *int
-
-	// Standard fields
-	CreatorID *int
-
-	// Domain specific fields
-	Title *string `json:"title"`
-}
-
-type ShortcutDelete struct {
-	ID *int
-
-	// Standard fields
-	CreatorID *int
-}
@@ -1,49 +0,0 @@
-package api
-
-type StorageType string
-
-const (
-	StorageS3 StorageType = "S3"
-)
-
-type StorageConfig struct {
-	S3Config *StorageS3Config `json:"s3Config"`
-}
-
-type StorageS3Config struct {
-	EndPoint  string `json:"endPoint"`
-	Path      string `json:"path"`
-	Region    string `json:"region"`
-	AccessKey string `json:"accessKey"`
-	SecretKey string `json:"secretKey"`
-	Bucket    string `json:"bucket"`
-	URLPrefix string `json:"urlPrefix"`
-}
-
-type Storage struct {
-	ID     int            `json:"id"`
-	Name   string         `json:"name"`
-	Type   StorageType    `json:"type"`
-	Config *StorageConfig `json:"config"`
-}
-
-type StorageCreate struct {
-	Name   string         `json:"name"`
-	Type   StorageType    `json:"type"`
-	Config *StorageConfig `json:"config"`
-}
-
-type StoragePatch struct {
-	ID     int            `json:"id"`
-	Type   StorageType    `json:"type"`
-	Name   *string        `json:"name"`
-	Config *StorageConfig `json:"config"`
-}
-
-type StorageFind struct {
-	ID *int `json:"id"`
-}
-
-type StorageDelete struct {
-	ID int `json:"id"`
-}
@@ -1,22 +0,0 @@
-package api
-
-import "github.com/usememos/memos/server/profile"
-
-type SystemStatus struct {
-	Host    *User           `json:"host"`
-	Profile profile.Profile `json:"profile"`
-	DBSize  int64           `json:"dbSize"`
-
-	// System settings
-	// Allow sign up.
-	AllowSignUp bool `json:"allowSignUp"`
-	// Disable public memos.
-	DisablePublicMemos bool `json:"disablePublicMemos"`
-	// Additional style.
-	AdditionalStyle string `json:"additionalStyle"`
-	// Additional script.
-	AdditionalScript string `json:"additionalScript"`
-	// Customized server profile, including server name and external url.
-	CustomizedProfile CustomizedProfile `json:"customizedProfile"`
-	StorageServiceID  int               `json:"storageServiceId"`
-}
@@ -1,160 +0,0 @@
-package api
-
-import (
-	"encoding/json"
-	"errors"
-	"fmt"
-
-	"golang.org/x/exp/slices"
-)
-
-type SystemSettingName string
-
-const (
-	// SystemSettingServerID is the key type of server id.
-	SystemSettingServerID SystemSettingName = "serverId"
-	// SystemSettingSecretSessionName is the key type of secret session name.
-	SystemSettingSecretSessionName SystemSettingName = "secretSessionName"
-	// SystemSettingAllowSignUpName is the key type of allow signup setting.
-	SystemSettingAllowSignUpName SystemSettingName = "allowSignUp"
-	// SystemSettingDisablePublicMemosName is the key type of disable public memos setting.
-	SystemSettingDisablePublicMemosName SystemSettingName = "disablePublicMemos"
-	// SystemSettingAdditionalStyleName is the key type of additional style.
-	SystemSettingAdditionalStyleName SystemSettingName = "additionalStyle"
-	// SystemSettingAdditionalScriptName is the key type of additional script.
-	SystemSettingAdditionalScriptName SystemSettingName = "additionalScript"
-	// SystemSettingCustomizedProfileName is the key type of customized server profile.
-	SystemSettingCustomizedProfileName SystemSettingName = "customizedProfile"
-	// SystemSettingStorageServiceIDName is the key type of storage service ID.
-	SystemSettingStorageServiceIDName SystemSettingName = "storageServiceId"
-	// SystemSettingOpenAIConfigName is the key type of OpenAI config.
-	SystemSettingOpenAIConfigName SystemSettingName = "openAIConfig"
-)
-
-// CustomizedProfile is the struct definition for SystemSettingCustomizedProfileName system setting item.
-type CustomizedProfile struct {
-	// Name is the server name, default is `memos`
-	Name string `json:"name"`
-	// LogoURL is the url of logo image.
-	LogoURL string `json:"logoUrl"`
-	// Description is the server description.
-	Description string `json:"description"`
-	// Locale is the server default locale.
-	Locale string `json:"locale"`
-	// Appearance is the server default appearance.
-	Appearance string `json:"appearance"`
-	// ExternalURL is the external url of server. e.g. https://usermemos.com
-	ExternalURL string `json:"externalUrl"`
-}
-
-type OpenAIConfig struct {
-	Key  string `json:"key"`
-	Host string `json:"host"`
-}
-
-func (key SystemSettingName) String() string {
-	switch key {
-	case SystemSettingServerID:
-		return "serverId"
-	case SystemSettingSecretSessionName:
-		return "secretSessionName"
-	case SystemSettingAllowSignUpName:
-		return "allowSignUp"
-	case SystemSettingDisablePublicMemosName:
-		return "disablePublicMemos"
-	case SystemSettingAdditionalStyleName:
-		return "additionalStyle"
-	case SystemSettingAdditionalScriptName:
-		return "additionalScript"
-	case SystemSettingCustomizedProfileName:
-		return "customizedProfile"
-	case SystemSettingStorageServiceIDName:
-		return "storageServiceId"
-	case SystemSettingOpenAIConfigName:
-		return "openAIConfig"
-	}
-	return ""
-}
-
-type SystemSetting struct {
-	Name SystemSettingName `json:"name"`
-	// Value is a JSON string with basic value.
-	Value       string `json:"value"`
-	Description string `json:"description"`
-}
-
-type SystemSettingUpsert struct {
-	Name        SystemSettingName `json:"name"`
-	Value       string            `json:"value"`
-	Description string            `json:"description"`
-}
-
-func (upsert SystemSettingUpsert) Validate() error {
-	if upsert.Name == SystemSettingServerID {
-		return errors.New("update server id is not allowed")
-	} else if upsert.Name == SystemSettingAllowSignUpName {
-		value := false
-		err := json.Unmarshal([]byte(upsert.Value), &value)
-		if err != nil {
-			return fmt.Errorf("failed to unmarshal system setting allow signup value")
-		}
-	} else if upsert.Name == SystemSettingDisablePublicMemosName {
-		value := false
-		err := json.Unmarshal([]byte(upsert.Value), &value)
-		if err != nil {
-			return fmt.Errorf("failed to unmarshal system setting disable public memos value")
-		}
-	} else if upsert.Name == SystemSettingAdditionalStyleName {
-		value := ""
-		err := json.Unmarshal([]byte(upsert.Value), &value)
-		if err != nil {
-			return fmt.Errorf("failed to unmarshal system setting additional style value")
-		}
-	} else if upsert.Name == SystemSettingAdditionalScriptName {
-		value := ""
-		err := json.Unmarshal([]byte(upsert.Value), &value)
-		if err != nil {
-			return fmt.Errorf("failed to unmarshal system setting additional script value")
-		}
-	} else if upsert.Name == SystemSettingCustomizedProfileName {
-		customizedProfile := CustomizedProfile{
-			Name:        "memos",
-			LogoURL:     "",
-			Description: "",
-			Locale:      "en",
-			Appearance:  "system",
-			ExternalURL: "",
-		}
-		err := json.Unmarshal([]byte(upsert.Value), &customizedProfile)
-		if err != nil {
-			return fmt.Errorf("failed to unmarshal system setting customized profile value")
-		}
-		if !slices.Contains(UserSettingLocaleValue, customizedProfile.Locale) {
-			return fmt.Errorf("invalid locale value")
-		}
-		if !slices.Contains(UserSettingAppearanceValue, customizedProfile.Appearance) {
-			return fmt.Errorf("invalid appearance value")
-		}
-	} else if upsert.Name == SystemSettingStorageServiceIDName {
-		value := 0
-		err := json.Unmarshal([]byte(upsert.Value), &value)
-		if err != nil {
-			return fmt.Errorf("failed to unmarshal system setting storage service id value")
-		}
-		return nil
-	} else if upsert.Name == SystemSettingOpenAIConfigName {
-		value := OpenAIConfig{}
-		err := json.Unmarshal([]byte(upsert.Value), &value)
-		if err != nil {
-			return fmt.Errorf("failed to unmarshal system setting openai api config value")
-		}
-	} else {
-		return fmt.Errorf("invalid system setting name")
-	}
-
-	return nil
-}
-
-type SystemSettingFind struct {
-	Name SystemSettingName `json:"name"`
-}
@@ -1,20 +0,0 @@
-package api
-
-type Tag struct {
-	Name      string
-	CreatorID int
-}
-
-type TagUpsert struct {
-	Name      string
-	CreatorID int `json:"-"`
-}
-
-type TagFind struct {
-	CreatorID int
-}
-
-type TagDelete struct {
-	Name      string `json:"name"`
-	CreatorID int
-}
@@ -1,158 +0,0 @@
-package api
-
-import (
-	"fmt"
-
-	"github.com/usememos/memos/common"
-)
-
-// Role is the type of a role.
-type Role string
-
-const (
-	// Host is the HOST role.
-	Host Role = "HOST"
-	// Admin is the ADMIN role.
-	Admin Role = "ADMIN"
-	// NormalUser is the USER role.
-	NormalUser Role = "USER"
-)
-
-func (e Role) String() string {
-	switch e {
-	case Host:
-		return "HOST"
-	case Admin:
-		return "ADMIN"
-	case NormalUser:
-		return "USER"
-	}
-	return "USER"
-}
-
-type User struct {
-	ID int `json:"id"`
-
-	// Standard fields
-	RowStatus RowStatus `json:"rowStatus"`
-	CreatedTs int64     `json:"createdTs"`
-	UpdatedTs int64     `json:"updatedTs"`
-
-	// Domain specific fields
-	Username        string         `json:"username"`
-	Role            Role           `json:"role"`
-	Email           string         `json:"email"`
-	Nickname        string         `json:"nickname"`
-	PasswordHash    string         `json:"-"`
-	OpenID          string         `json:"openId"`
-	AvatarURL       string         `json:"avatarUrl"`
-	UserSettingList []*UserSetting `json:"userSettingList"`
-}
-
-type UserCreate struct {
-	// Domain specific fields
-	Username     string `json:"username"`
-	Role         Role   `json:"role"`
-	Email        string `json:"email"`
-	Nickname     string `json:"nickname"`
-	Password     string `json:"password"`
-	PasswordHash string
-	OpenID       string
-}
-
-func (create UserCreate) Validate() error {
-	if len(create.Username) < 3 {
-		return fmt.Errorf("username is too short, minimum length is 3")
-	}
-	if len(create.Username) > 32 {
-		return fmt.Errorf("username is too long, maximum length is 32")
-	}
-	if len(create.Password) < 3 {
-		return fmt.Errorf("password is too short, minimum length is 6")
-	}
-	if len(create.Password) > 512 {
-		return fmt.Errorf("password is too long, maximum length is 512")
-	}
-	if len(create.Nickname) > 64 {
-		return fmt.Errorf("nickname is too long, maximum length is 64")
-	}
-	if create.Email != "" {
-		if len(create.Email) > 256 {
-			return fmt.Errorf("email is too long, maximum length is 256")
-		}
-		if !common.ValidateEmail(create.Email) {
-			return fmt.Errorf("invalid email format")
-		}
-	}
-
-	return nil
-}
-
-type UserPatch struct {
-	ID int `json:"-"`
-
-	// Standard fields
-	UpdatedTs *int64
-	RowStatus *RowStatus `json:"rowStatus"`
-
-	// Domain specific fields
-	Username     *string `json:"username"`
-	Email        *string `json:"email"`
-	Nickname     *string `json:"nickname"`
-	Password     *string `json:"password"`
-	ResetOpenID  *bool   `json:"resetOpenId"`
-	AvatarURL    *string `json:"avatarUrl"`
-	PasswordHash *string
-	OpenID       *string
-}
-
-func (patch UserPatch) Validate() error {
-	if patch.Username != nil && len(*patch.Username) < 3 {
-		return fmt.Errorf("username is too short, minimum length is 3")
-	}
-	if patch.Username != nil && len(*patch.Username) > 32 {
-		return fmt.Errorf("username is too long, maximum length is 32")
-	}
-	if patch.Password != nil && len(*patch.Password) < 3 {
-		return fmt.Errorf("password is too short, minimum length is 6")
-	}
-	if patch.Password != nil && len(*patch.Password) > 512 {
-		return fmt.Errorf("password is too long, maximum length is 512")
-	}
-	if patch.Nickname != nil && len(*patch.Nickname) > 64 {
-		return fmt.Errorf("nickname is too long, maximum length is 64")
-	}
-	if patch.AvatarURL != nil {
-		if len(*patch.AvatarURL) > 2<<20 {
-			return fmt.Errorf("avatar is too large, maximum is 2MB")
-		}
-	}
-	if patch.Email != nil && *patch.Email != "" {
-		if len(*patch.Email) > 256 {
-			return fmt.Errorf("email is too long, maximum length is 256")
-		}
-		if !common.ValidateEmail(*patch.Email) {
-			return fmt.Errorf("invalid email format")
-		}
-	}
-
-	return nil
-}
-
-type UserFind struct {
-	ID *int `json:"id"`
-
-	// Standard fields
-	RowStatus *RowStatus `json:"rowStatus"`
-
-	// Domain specific fields
-	Username *string `json:"username"`
-	Role     *Role
-	Email    *string `json:"email"`
-	Nickname *string `json:"nickname"`
-	OpenID   *string
-}
-
-type UserDelete struct {
-	ID int
-}
@@ -1,110 +0,0 @@
-package api
-
-import (
-	"encoding/json"
-	"fmt"
-
-	"golang.org/x/exp/slices"
-)
-
-type UserSettingKey string
-
-const (
-	// UserSettingLocaleKey is the key type for user locale.
-	UserSettingLocaleKey UserSettingKey = "locale"
-	// UserSettingAppearanceKey is the key type for user appearance.
-	UserSettingAppearanceKey UserSettingKey = "appearance"
-	// UserSettingMemoVisibilityKey is the key type for user preference memo default visibility.
-	UserSettingMemoVisibilityKey UserSettingKey = "memoVisibility"
-	// UserSettingResourceVisibilityKey is the key type for user preference resource default visibility.
-	UserSettingResourceVisibilityKey UserSettingKey = "resourceVisibility"
-)
-
-// String returns the string format of UserSettingKey type.
-func (key UserSettingKey) String() string {
-	switch key {
-	case UserSettingLocaleKey:
-		return "locale"
-	case UserSettingAppearanceKey:
-		return "appearance"
-	case UserSettingMemoVisibilityKey:
-		return "memoVisibility"
-	case UserSettingResourceVisibilityKey:
-		return "resourceVisibility"
-	}
-	return ""
-}
-
-var (
-	UserSettingLocaleValue             = []string{"en", "zh", "vi", "fr", "nl", "sv", "de", "es", "uk", "ru", "it", "hant", "tr", "ko"}
-	UserSettingAppearanceValue         = []string{"system", "light", "dark"}
-	UserSettingMemoVisibilityValue     = []Visibility{Private, Protected, Public}
-	UserSettingResourceVisibilityValue = []Visibility{Private, Protected, Public}
-)
-
-type UserSetting struct {
-	UserID int
-	Key    UserSettingKey `json:"key"`
-	// Value is a JSON string with basic value
-	Value string `json:"value"`
-}
-
-type UserSettingUpsert struct {
-	UserID int            `json:"-"`
-	Key    UserSettingKey `json:"key"`
-	Value  string         `json:"value"`
-}
-
-func (upsert UserSettingUpsert) Validate() error {
-	if upsert.Key == UserSettingLocaleKey {
-		localeValue := "en"
-		err := json.Unmarshal([]byte(upsert.Value), &localeValue)
-		if err != nil {
-			return fmt.Errorf("failed to unmarshal user setting locale value")
-		}
-		if !slices.Contains(UserSettingLocaleValue, localeValue) {
-			return fmt.Errorf("invalid user setting locale value")
-		}
-	} else if upsert.Key == UserSettingAppearanceKey {
-		appearanceValue := "system"
-		err := json.Unmarshal([]byte(upsert.Value), &appearanceValue)
-		if err != nil {
-			return fmt.Errorf("failed to unmarshal user setting appearance value")
-		}
-		if !slices.Contains(UserSettingAppearanceValue, appearanceValue) {
-			return fmt.Errorf("invalid user setting appearance value")
-		}
-	} else if upsert.Key == UserSettingMemoVisibilityKey {
-		memoVisibilityValue := Private
-		err := json.Unmarshal([]byte(upsert.Value), &memoVisibilityValue)
-		if err != nil {
-			return fmt.Errorf("failed to unmarshal user setting memo visibility value")
-		}
-		if !slices.Contains(UserSettingMemoVisibilityValue, memoVisibilityValue) {
-			return fmt.Errorf("invalid user setting memo visibility value")
-		}
-	} else if upsert.Key == UserSettingResourceVisibilityKey {
-		resourceVisibilityValue := Private
-		err := json.Unmarshal([]byte(upsert.Value), &resourceVisibilityValue)
-		if err != nil {
-			return fmt.Errorf("failed to unmarshal user setting resource visibility value")
-		}
-		if !slices.Contains(UserSettingResourceVisibilityValue, resourceVisibilityValue) {
-			return fmt.Errorf("invalid user setting resource visibility value")
-		}
-	} else {
-		return fmt.Errorf("invalid user setting key")
-	}
-
-	return nil
-}
-
-type UserSettingFind struct {
-	UserID int
-
-	Key UserSettingKey `json:"key"`
-}
-
-type UserSettingDelete struct {
-	UserID int
-}
@@ -0,0 +1,187 @@
+package main
+
+import (
+	"context"
+	"fmt"
+	"log/slog"
+	"net/http"
+	"os"
+	"os/signal"
+	"syscall"
+
+	"github.com/spf13/cobra"
+	"github.com/spf13/viper"
+
+	"github.com/usememos/memos/internal/profile"
+	"github.com/usememos/memos/internal/version"
+	"github.com/usememos/memos/server"
+	"github.com/usememos/memos/store"
+	"github.com/usememos/memos/store/db"
+)
+
+const (
+	greetingBanner = `
+███╗   ███╗███████╗███╗   ███╗ ██████╗ ███████╗
+████╗ ████║██╔════╝████╗ ████║██╔═══██╗██╔════╝
+██╔████╔██║█████╗  ██╔████╔██║██║   ██║███████╗
+██║╚██╔╝██║██╔══╝  ██║╚██╔╝██║██║   ██║╚════██║
+██║ ╚═╝ ██║███████╗██║ ╚═╝ ██║╚██████╔╝███████║
+╚═╝     ╚═╝╚══════╝╚═╝     ╚═╝ ╚═════╝ ╚══════╝
+`
+)
+
+var (
+	rootCmd = &cobra.Command{
+		Use:   "memos",
+		Short: `An open source, lightweight note-taking service. Easily capture and share your great thoughts.`,
+		Run: func(_ *cobra.Command, _ []string) {
+			instanceProfile := &profile.Profile{
+				Mode:        viper.GetString("mode"),
+				Addr:        viper.GetString("addr"),
+				Port:        viper.GetInt("port"),
+				UNIXSock:    viper.GetString("unix-sock"),
+				Data:        viper.GetString("data"),
+				Driver:      viper.GetString("driver"),
+				DSN:         viper.GetString("dsn"),
+				InstanceURL: viper.GetString("instance-url"),
+				Version:     version.GetCurrentVersion(viper.GetString("mode")),
+			}
+			if err := instanceProfile.Validate(); err != nil {
+				panic(err)
+			}
+
+			ctx, cancel := context.WithCancel(context.Background())
+			dbDriver, err := db.NewDBDriver(instanceProfile)
+			if err != nil {
+				cancel()
+				slog.Error("failed to create db driver", "error", err)
+				return
+			}
+
+			storeInstance := store.New(dbDriver, instanceProfile)
+			if err := storeInstance.Migrate(ctx); err != nil {
+				cancel()
+				slog.Error("failed to migrate", "error", err)
+				return
+			}
+
+			s, err := server.NewServer(ctx, instanceProfile, storeInstance)
+			if err != nil {
+				cancel()
+				slog.Error("failed to create server", "error", err)
+				return
+			}
+
+			c := make(chan os.Signal, 1)
+			// Trigger graceful shutdown on SIGINT or SIGTERM.
+			// The default signal sent by the `kill` command is SIGTERM,
+			// which is taken as the graceful shutdown signal for many systems, eg., Kubernetes, Gunicorn.
+			signal.Notify(c, os.Interrupt, syscall.SIGTERM)
+
+			if err := s.Start(ctx); err != nil {
+				if err != http.ErrServerClosed {
+					slog.Error("failed to start server", "error", err)
+					cancel()
+				}
+			}
+
+			printGreetings(instanceProfile)
+
+			go func() {
+				<-c
+				s.Shutdown(ctx)
+				cancel()
+			}()
+
+			// Wait for CTRL-C.
+			<-ctx.Done()
+		},
+	}
+)
+
+func init() {
+	viper.SetDefault("mode", "dev")
+	viper.SetDefault("driver", "sqlite")
+	viper.SetDefault("port", 8081)
+
+	rootCmd.PersistentFlags().String("mode", "dev", `mode of server, can be "prod" or "dev" or "demo"`)
+	rootCmd.PersistentFlags().String("addr", "", "address of server")
+	rootCmd.PersistentFlags().Int("port", 8081, "port of server")
+	rootCmd.PersistentFlags().String("unix-sock", "", "path to the unix socket, overrides --addr and --port")
+	rootCmd.PersistentFlags().String("data", "", "data directory")
+	rootCmd.PersistentFlags().String("driver", "sqlite", "database driver")
+	rootCmd.PersistentFlags().String("dsn", "", "database source name(aka. DSN)")
+	rootCmd.PersistentFlags().String("instance-url", "", "the url of your memos instance")
+
+	if err := viper.BindPFlag("mode", rootCmd.PersistentFlags().Lookup("mode")); err != nil {
+		panic(err)
+	}
+	if err := viper.BindPFlag("addr", rootCmd.PersistentFlags().Lookup("addr")); err != nil {
+		panic(err)
+	}
+	if err := viper.BindPFlag("port", rootCmd.PersistentFlags().Lookup("port")); err != nil {
+		panic(err)
+	}
+	if err := viper.BindPFlag("unix-sock", rootCmd.PersistentFlags().Lookup("unix-sock")); err != nil {
+		panic(err)
+	}
+	if err := viper.BindPFlag("data", rootCmd.PersistentFlags().Lookup("data")); err != nil {
+		panic(err)
+	}
+	if err := viper.BindPFlag("driver", rootCmd.PersistentFlags().Lookup("driver")); err != nil {
+		panic(err)
+	}
+	if err := viper.BindPFlag("dsn", rootCmd.PersistentFlags().Lookup("dsn")); err != nil {
+		panic(err)
+	}
+	if err := viper.BindPFlag("instance-url", rootCmd.PersistentFlags().Lookup("instance-url")); err != nil {
+		panic(err)
+	}
+
+	viper.SetEnvPrefix("memos")
+	viper.AutomaticEnv()
+	if err := viper.BindEnv("instance-url", "MEMOS_INSTANCE_URL"); err != nil {
+		panic(err)
+	}
+}
+
+func printGreetings(profile *profile.Profile) {
+	if profile.IsDev() {
+		println("Development mode is enabled")
+		println("DSN: ", profile.DSN)
+	}
+	fmt.Printf(`---
+Server profile
+version: %s
+data: %s
+addr: %s
+port: %d
+unix-sock: %s
+mode: %s
+driver: %s
+---
+`, profile.Version, profile.Data, profile.Addr, profile.Port, profile.UNIXSock, profile.Mode, profile.Driver)
+
+	print(greetingBanner)
+	if len(profile.UNIXSock) == 0 {
+		if len(profile.Addr) == 0 {
+			fmt.Printf("Version %s has been started on port %d\n", profile.Version, profile.Port)
+		} else {
+			fmt.Printf("Version %s has been started on address '%s' and port %d\n", profile.Version, profile.Addr, profile.Port)
+		}
+	} else {
+		fmt.Printf("Version %s has been started on unix socket %s\n", profile.Version, profile.UNIXSock)
+	}
+	fmt.Printf(`---
+See more in:
+👉Website: %s
+👉GitHub: %s
+---
+`, "https://usememos.com", "https://github.com/usememos/memos")
+}
+
+func main() {
+	if err := rootCmd.Execute(); err != nil {
+		panic(err)
+	}
+}
@@ -1,119 +0,0 @@
-package cmd
-
-import (
-	"context"
-	"fmt"
-	"net/http"
-	"os"
-	"os/signal"
-	"syscall"
-
-	"github.com/spf13/cobra"
-	"github.com/spf13/viper"
-
-	"github.com/usememos/memos/server"
-	_profile "github.com/usememos/memos/server/profile"
-)
-
-const (
-	greetingBanner = `
-███╗   ███╗███████╗███╗   ███╗ ██████╗ ███████╗
-████╗ ████║██╔════╝████╗ ████║██╔═══██╗██╔════╝
-██╔████╔██║█████╗  ██╔████╔██║██║   ██║███████╗
-██║╚██╔╝██║██╔══╝  ██║╚██╔╝██║██║   ██║╚════██║
-██║ ╚═╝ ██║███████╗██║ ╚═╝ ██║╚██████╔╝███████║
-╚═╝     ╚═╝╚══════╝╚═╝     ╚═╝ ╚═════╝ ╚══════╝
-`
-)
-
-var (
-	profile *_profile.Profile
-	mode    string
-	port    int
-	data    string
-
-	rootCmd = &cobra.Command{
-		Use:   "memos",
-		Short: `An open-source, self-hosted memo hub with knowledge management and social networking.`,
-		Run: func(_cmd *cobra.Command, _args []string) {
-			ctx, cancel := context.WithCancel(context.Background())
-			s, err := server.NewServer(ctx, profile)
-			if err != nil {
-				cancel()
-				fmt.Printf("failed to create server, error: %+v\n", err)
-				return
-			}
-
-			c := make(chan os.Signal, 1)
-			// Trigger graceful shutdown on SIGINT or SIGTERM.
-			// The default signal sent by the `kill` command is SIGTERM,
-			// which is taken as the graceful shutdown signal for many systems, eg., Kubernetes, Gunicorn.
-			signal.Notify(c, os.Interrupt, syscall.SIGTERM)
-			go func() {
-				sig := <-c
-				fmt.Printf("%s received.\n", sig.String())
-				s.Shutdown(ctx)
-				cancel()
-			}()
-
-			println(greetingBanner)
-			fmt.Printf("Version %s has started at :%d\n", profile.Version, profile.Port)
-			if err := s.Start(ctx); err != nil {
-				if err != http.ErrServerClosed {
-					fmt.Printf("failed to start server, error: %+v\n", err)
-					cancel()
-				}
-			}
-
-			// Wait for CTRL-C.
-			<-ctx.Done()
-		},
-	}
-)
-
-func Execute() error {
-	return rootCmd.Execute()
-}
-
-func init() {
-	cobra.OnInitialize(initConfig)
-
-	rootCmd.PersistentFlags().StringVarP(&mode, "mode", "m", "demo", `mode of server, can be "prod" or "dev" or "demo"`)
-	rootCmd.PersistentFlags().IntVarP(&port, "port", "p", 8081, "port of server")
-	rootCmd.PersistentFlags().StringVarP(&data, "data", "d", "", "data directory")
-
-	err := viper.BindPFlag("mode", rootCmd.PersistentFlags().Lookup("mode"))
-	if err != nil {
-		panic(err)
-	}
-	err = viper.BindPFlag("port", rootCmd.PersistentFlags().Lookup("port"))
-	if err != nil {
-		panic(err)
-	}
-	err = viper.BindPFlag("data", rootCmd.PersistentFlags().Lookup("data"))
-	if err != nil {
-		panic(err)
-	}
-
-	viper.SetDefault("mode", "demo")
-	viper.SetDefault("port", 8081)
-	viper.SetEnvPrefix("memos")
-}
-
-func initConfig() {
-	viper.AutomaticEnv()
-	var err error
-	profile, err = _profile.GetProfile()
-	if err != nil {
-		fmt.Printf("failed to get profile, error: %+v\n", err)
-		return
-	}
-
-	println("---")
-	println("Server profile")
-	println("dsn:", profile.DSN)
-	println("port:", profile.Port)
-	println("mode:", profile.Mode)
-	println("version:", profile.Version)
-	println("---")
-}
@@ -1,72 +0,0 @@
-package common
-
-import (
-	"errors"
-)
-
-// Code is the error code.
-type Code int
-
-// Application error codes.
-const (
-	// 0 ~ 99 general error.
-	Ok             Code = 0
-	Internal       Code = 1
-	NotAuthorized  Code = 2
-	Invalid        Code = 3
-	NotFound       Code = 4
-	Conflict       Code = 5
-	NotImplemented Code = 6
-)
-
-// Error represents an application-specific error. Application errors can be
-// unwrapped by the caller to extract out the code & message.
-//
-// Any non-application error (such as a disk error) should be reported as an
-// Internal error and the human user should only see "Internal error" as the
-// message. These low-level internal error details should only be logged and
-// reported to the operator of the application (not the end user).
-type Error struct {
-	// Machine-readable error code.
-	Code Code
-
-	// Embedded error.
-	Err error
-}
-
-// Error implements the error interface. Not used by the application otherwise.
-func (e *Error) Error() string {
-	return e.Err.Error()
-}
-
-// ErrorCode unwraps an application error and returns its code.
-// Non-application errors always return EINTERNAL.
-func ErrorCode(err error) Code {
-	var e *Error
-	if err == nil {
-		return Ok
-	} else if errors.As(err, &e) {
-		return e.Code
-	}
-	return Internal
-}
-
-// ErrorMessage unwraps an application error and returns its message.
-// Non-application errors always return "Internal error".
-func ErrorMessage(err error) string {
-	var e *Error
-	if err == nil {
-		return ""
-	} else if errors.As(err, &e) {
-		return e.Err.Error()
-	}
-	return "Internal error."
-}
-
-// Errorf is a helper function to return an Error with a given code and error.
-func Errorf(code Code, err error) *Error {
-	return &Error{
-		Code: code,
-		Err:  err,
-	}
-}
@@ -1,67 +0,0 @@
-// Package log implements a simple logging package.
-package log
-
-import (
-	"go.uber.org/zap"
-	"go.uber.org/zap/zapcore"
-)
-
-var (
-	// `gl` is the global logger.
-	// Other packages should use public methods such as Info/Error to do the logging.
-	// For other types of logging, e.g. logging to a separate file, they should use their own loggers.
-	gl     *zap.Logger
-	gLevel zap.AtomicLevel
-)
-
-// Initializes the global console logger.
-func init() {
-	gLevel = zap.NewAtomicLevelAt(zap.InfoLevel)
-	gl, _ = zap.Config{
-		Level:       gLevel,
-		Development: true,
-		// Use "console" to print readable stacktrace.
-		Encoding:         "console",
-		EncoderConfig:    zap.NewDevelopmentEncoderConfig(),
-		OutputPaths:      []string{"stderr"},
-		ErrorOutputPaths: []string{"stderr"},
-	}.Build(
-		// Skip one caller stack to locate the correct caller.
-		zap.AddCallerSkip(1),
-	)
-}
-
-// SetLevel wraps the zap Level's SetLevel method.
-func SetLevel(level zapcore.Level) {
-	gLevel.SetLevel(level)
-}
-
-// EnabledLevel wraps the zap Level's Enabled method.
-func EnabledLevel(level zapcore.Level) bool {
-	return gLevel.Enabled(level)
-}
-
-// Debug wraps the zap Logger's Debug method.
-func Debug(msg string, fields ...zap.Field) {
-	gl.Debug(msg, fields...)
-}
-
-// Info wraps the zap Logger's Info method.
-func Info(msg string, fields ...zap.Field) {
-	gl.Info(msg, fields...)
-}
-
-// Warn wraps the zap Logger's Warn method.
-func Warn(msg string, fields ...zap.Field) {
-	gl.Warn(msg, fields...)
-}
-
-// Error wraps the zap Logger's Error method.
-func Error(msg string, fields ...zap.Field) {
-	gl.Error(msg, fields...)
-}
-
-// Sync wraps the zap Logger's Sync method.
-func Sync() {
-	_ = gl.Sync()
-}
@@ -1,14 +0,0 @@
-# Adding A Custom Theme
-
-1. Open the Settings Dialog
-2. Navigate to the System Tab
-3. In the "Additional Styles" box add these lines of code:
-
-```css
-.memo-list-container {background-color: #INSERT COLOR HERE;}
-.page-container {background-color: #INSERT COLOR HERE;}
-```
-
-  It is recommended that you choose the same color for both options
-
-4. Refresh the page and the background color of your memos app will successfully update to reflect your changes
@@ -1,17 +0,0 @@
-version: "3.0"
-
-# uffizzi integration
-x-uffizzi:
-  ingress:
-    service: memos
-    port: 5230
-
-services:
-  memos:
-    image: "${MEMOS_IMAGE}"
-    volumes:
-      - memos_volume:/var/opt/memos
-    command: ["--mode", "demo"]
-
-volumes:
-  memos_volume:
@@ -1,133 +0,0 @@
-# A Beginner's Guide to Deploying Memos on Render.com
-
-written by [AJ](https://memos.ajstephens.website/) (also a noob)
-
-<img height="64px" src="https://raw.githubusercontent.com/usememos/memos/main/resources/logo-full.webp" alt="✍️ memos" />
-
-[Live Demo](https://demo.usememos.com) • [Official Website](https://usememos.com) • [Source Code](https://github.com/usememos/memos)
-
-## Who is this guide for?
-
-Someone who...
-
- doesn't have much experience with self hosting
- has a minimal understanding of docker
-
-Someone who wants...
-
- to use memos
- to support the memos project
- a cost effective and simple way to host it on the cloud with reliablity and persistance
- to share memos with friends
-
-## Requirements
-
- Can follow instructions
- Have 7ish USD a month on a debit/credit card
-
-## Guide
-
-Create an account at [Render](https://dashboard.render.com/register)
-![ss1](https://i.imgur.com/l3K7aqC.png)
-
-1. Go to your dashboard
-
-[https://dashboard.render.com/](https://dashboard.render.com/)
-
-2. Select New Web Service
-
-   ![ss2](https://i.imgur.com/IIDdK2y.png)
-
-3. Scroll down to "Public Git repository"
-
-4. Paste in the link for the public git repository for memos (https://github.com/usememos/memos) and press continue
-
-   ![ss3](https://i.imgur.com/OXoCWoJ.png)
-
-5. Render will pre-fill most of the fields but you will need to create a unique name for your web service
-
-6. Adjust region if you want to
-
-7. Don't touch the "branch", "root directory", and "environment" fields
-
-   ![ss4](https://i.imgur.com/v7Sw3fp.png)
-
-8. Click "enter your payment information" and do so
-
-   ![ss5](https://i.imgur.com/paKcQFl.png)
-
-   ![ss6](https://i.imgur.com/JdcO1HC.png)
-
-9. Select the starter plan ($7 a month - a requirement for persistant data - render's free instances spin down when inactive and lose all data)
-
-10. Click "Create Web Service"
-
-![ss7](https://i.imgur.com/MHe45J4.png)
-
-11. Wait patiently while the _magic_ happens 🤷‍♂️
-
-![ss8](https://i.imgur.com/h1PXHHJ.png)
-
-12. After some time (~ 6 min for me) the build will finish and you will see the web service is live
-
-![ss9](https://i.imgur.com/msapkRw.png)
-
-13. Now it's time to add the disk so your data won't dissappear when the webservice redeploys (redeploys happen automatically when the public repo is updated)
-
-14. Select the "Disks" tab on the left menu and then click "Add Disk"
-
-![ss10](https://i.imgur.com/rGeI0bv.png)
-
-15. Name your disk (can be whatever)
-
-16. Set the "Mount Path" to `/var/opt/memos`
-
-17. Set the disk size (default is 10GB but 1GB is plenty and can be increased at any time)
-
-18. Click "Save"
-
-    ![ss11](https://i.imgur.com/Jbg7O6q.png)
-
-19. Wait...again...while the webservice redeploys with the persistant disk
-
-    ![ss12](https://i.imgur.com/pTzpE34.png)
-
-20. aaaand....we're back online!
-
-    ![ss13](https://i.imgur.com/qdsFfSa.png)
-
-21. Time to test! We're going to make sure everything is working correctly.
-
-22. Click the link in the top left, it should look like `https://the-name-you-chose.onrender.com` - this is your self hosted memos link!
-
-    ![ss14](https://i.imgur.com/cgzFSIn.png)
-
-23. Create a Username and Password (remember these) then click "Sign up as Host"
-
-    ![ss15](https://i.imgur.com/kuRStAj.png)
-
-24. Create a test memo then click save
-
-    ![ss16](https://i.imgur.com/Eh2AB44.png)
-
-25. Sign out of your self-hosted memos
-
-    ![ss17](https://i.imgur.com/0mMb88G.png)
-
-26. Return to your Render dashboard, click the "Manual Deploy" dropdown button and click "Deploy latest commit" and wait until the webservice is live again (This is to test that your data is persistant)
-
-    ![ss18](https://i.imgur.com/w1N7VTb.png)
-
-27. Once the webservice is live go back to your self-hosted memos page and sign in! (If your memos screen looks different then something went wrong)
-
-28. Once you're logged in, verify your test memo is still there after the redeploy
-
-    ![ss19](https://i.imgur.com/dTcEQZS.png)
-
-    ![ss20](https://i.imgur.com/VE2lu8H.png)
-
-## 🎉Celebrate!🎉
-
-You did it! Enjoy using memos!
-
-Want to learn more or need more guidance? Join the community on [telegram](https://t.me/+-_tNF1k70UU4ZTc9) and [discord](https://discord.gg/tfPJa4UmAv).
@@ -1,40 +0,0 @@
-# Development
-
-Memos is built with a curated tech stack. It is optimized for developer experience and is very easy to start working on the code:
-
-1. It has no external dependency.
-2. It requires zero config.
-3. 1 command to start backend and 1 command to start frontend, both with live reload support.
-
-## Tech Stack
-
-![tech-stack](https://raw.githubusercontent.com/usememos/memos/main/resources/tech-stack.png)
-
-## Prerequisites
-
- [Go](https://golang.org/doc/install)
- [Air](https://github.com/cosmtrek/air#installation) for backend live reload
- [Node.js](https://nodejs.org/)
- [yarn](https://yarnpkg.com/getting-started/install)
-
-## Steps
-
-1. pull source code
-
-   ```bash
-   git clone https://github.com/usememos/memos
-   ```
-
-2. start backend using air(with live reload)
-
-   ```bash
-   air -c scripts/.air.toml
-   ```
-
-3. start frontend dev server
-
-   ```bash
-   cd web && yarn && yarn dev
-   ```
-
-Memos should now be running at [http://localhost:3001](http://localhost:3001) and change either frontend or backend code would trigger live reload.
@@ -1,78 +1,98 @@
 module github.com/usememos/memos

-go 1.19
+go 1.24

 require (
-	github.com/aws/aws-sdk-go-v2 v1.17.4
-	github.com/aws/aws-sdk-go-v2/config v1.18.12
-	github.com/aws/aws-sdk-go-v2/credentials v1.13.12
-	github.com/aws/aws-sdk-go-v2/feature/s3/manager v1.11.51
-	github.com/aws/aws-sdk-go-v2/service/s3 v1.30.3
-	github.com/google/uuid v1.3.0
-	github.com/gorilla/feeds v1.1.1
-	github.com/gorilla/sessions v1.2.1
-	github.com/labstack/echo-contrib v0.13.0
-	github.com/labstack/echo/v4 v4.9.0
-	github.com/mattn/go-sqlite3 v1.14.9
+	github.com/aws/aws-sdk-go-v2 v1.36.3
+	github.com/aws/aws-sdk-go-v2/config v1.29.14
+	github.com/aws/aws-sdk-go-v2/credentials v1.17.67
+	github.com/aws/aws-sdk-go-v2/feature/s3/manager v1.17.77
+	github.com/aws/aws-sdk-go-v2/service/s3 v1.80.0
+	github.com/go-sql-driver/mysql v1.9.2
+	github.com/google/cel-go v0.25.0
+	github.com/google/uuid v1.6.0
+	github.com/gorilla/feeds v1.2.0
+	github.com/grpc-ecosystem/go-grpc-middleware v1.4.0
+	github.com/grpc-ecosystem/grpc-gateway/v2 v2.26.3
+	github.com/improbable-eng/grpc-web v0.15.0
+	github.com/joho/godotenv v1.5.1
+	github.com/labstack/echo/v4 v4.13.4
+	github.com/lib/pq v1.10.9
+	github.com/lithammer/shortuuid/v4 v4.2.0
 	github.com/pkg/errors v0.9.1
-	github.com/spf13/cobra v1.6.1
-	github.com/spf13/viper v1.15.0
-	github.com/stretchr/testify v1.8.1
-	go.uber.org/zap v1.24.0
-	golang.org/x/crypto v0.1.0
-	golang.org/x/exp v0.0.0-20230111222715-75897c7a292a
-	golang.org/x/mod v0.6.0
-	golang.org/x/net v0.7.0
-	golang.org/x/oauth2 v0.5.0
+	github.com/spf13/cobra v1.9.1
+	github.com/spf13/viper v1.20.1
+	github.com/stretchr/testify v1.10.0
+	github.com/usememos/gomark v0.0.0-20250328014447-c9fa41c01bc4
+	golang.org/x/crypto v0.38.0
+	golang.org/x/mod v0.24.0
+	golang.org/x/net v0.40.0
+	golang.org/x/oauth2 v0.30.0
+	google.golang.org/genproto/googleapis/api v0.0.0-20250528174236-200df99c418a
+	google.golang.org/grpc v1.72.2
+	modernc.org/sqlite v1.37.1
 )

 require (
-	github.com/aws/aws-sdk-go-v2/aws/protocol/eventstream v1.4.10 // indirect
-	github.com/aws/aws-sdk-go-v2/feature/ec2/imds v1.12.22 // indirect
-	github.com/aws/aws-sdk-go-v2/internal/configsources v1.1.28 // indirect
-	github.com/aws/aws-sdk-go-v2/internal/endpoints/v2 v2.4.22 // indirect
-	github.com/aws/aws-sdk-go-v2/internal/ini v1.3.29 // indirect
-	github.com/aws/aws-sdk-go-v2/internal/v4a v1.0.20 // indirect
-	github.com/aws/aws-sdk-go-v2/service/internal/accept-encoding v1.9.11 // indirect
-	github.com/aws/aws-sdk-go-v2/service/internal/checksum v1.1.23 // indirect
-	github.com/aws/aws-sdk-go-v2/service/internal/presigned-url v1.9.22 // indirect
-	github.com/aws/aws-sdk-go-v2/service/internal/s3shared v1.13.22 // indirect
-	github.com/aws/aws-sdk-go-v2/service/sso v1.12.1 // indirect
-	github.com/aws/aws-sdk-go-v2/service/ssooidc v1.14.1 // indirect
-	github.com/aws/aws-sdk-go-v2/service/sts v1.18.3 // indirect
-	github.com/aws/smithy-go v1.13.5 // indirect
-	github.com/davecgh/go-spew v1.1.1 // indirect
-	github.com/fsnotify/fsnotify v1.6.0 // indirect
-	github.com/golang-jwt/jwt v3.2.2+incompatible // indirect
-	github.com/golang/protobuf v1.5.2 // indirect
-	github.com/gorilla/context v1.1.1 // indirect
-	github.com/gorilla/securecookie v1.1.1 // indirect
-	github.com/hashicorp/hcl v1.0.0 // indirect
-	github.com/inconshreveable/mousetrap v1.0.1 // indirect
-	github.com/jmespath/go-jmespath v0.4.0 // indirect
-	github.com/kr/pretty v0.3.1 // indirect
-	github.com/labstack/gommon v0.3.1 // indirect
-	github.com/magiconair/properties v1.8.7 // indirect
-	github.com/mattn/go-colorable v0.1.12 // indirect
-	github.com/mattn/go-isatty v0.0.14 // indirect
-	github.com/mitchellh/mapstructure v1.5.0 // indirect
-	github.com/pelletier/go-toml/v2 v2.0.6 // indirect
-	github.com/pmezard/go-difflib v1.0.0 // indirect
-	github.com/spf13/afero v1.9.3 // indirect
-	github.com/spf13/cast v1.5.0 // indirect
-	github.com/spf13/jwalterweatherman v1.1.0 // indirect
-	github.com/spf13/pflag v1.0.5 // indirect
-	github.com/subosito/gotenv v1.4.2 // indirect
+	cel.dev/expr v0.24.0 // indirect
+	filippo.io/edwards25519 v1.1.0 // indirect
+	github.com/antlr4-go/antlr/v4 v4.13.1 // indirect
+	github.com/cenkalti/backoff/v4 v4.3.0 // indirect
+	github.com/desertbit/timer v1.0.1 // indirect
+	github.com/dustin/go-humanize v1.0.1 // indirect
+	github.com/fsnotify/fsnotify v1.9.0 // indirect
+	github.com/go-viper/mapstructure/v2 v2.2.1 // indirect
+	github.com/ncruces/go-strftime v0.1.9 // indirect
+	github.com/pelletier/go-toml/v2 v2.2.4 // indirect
+	github.com/remyoudompheng/bigfft v0.0.0-20230129092748-24d4a6f8daec // indirect
+	github.com/rogpeppe/go-internal v1.11.0 // indirect
+	github.com/rs/cors v1.11.1 // indirect
+	github.com/sagikazarmark/locafero v0.9.0 // indirect
+	github.com/sourcegraph/conc v0.3.0 // indirect
+	github.com/spf13/afero v1.14.0 // indirect
+	github.com/spf13/cast v1.9.1 // indirect
+	github.com/stoewer/go-strcase v1.3.0 // indirect
+	github.com/subosito/gotenv v1.6.0 // indirect
+	go.uber.org/multierr v1.11.0 // indirect
+	golang.org/x/exp v0.0.0-20250531010427-b6e5de432a8b // indirect
+	golang.org/x/image v0.27.0 // indirect
+	google.golang.org/genproto/googleapis/rpc v0.0.0-20250528174236-200df99c418a // indirect
+	modernc.org/libc v1.65.8 // indirect
+	modernc.org/mathutil v1.7.1 // indirect
+	modernc.org/memory v1.11.0 // indirect
+	nhooyr.io/websocket v1.8.17 // indirect
+)
+
+require (
+	github.com/aws/aws-sdk-go-v2/aws/protocol/eventstream v1.6.10 // indirect
+	github.com/aws/aws-sdk-go-v2/feature/ec2/imds v1.16.30 // indirect
+	github.com/aws/aws-sdk-go-v2/internal/configsources v1.3.34 // indirect
+	github.com/aws/aws-sdk-go-v2/internal/endpoints/v2 v2.6.34 // indirect
+	github.com/aws/aws-sdk-go-v2/internal/ini v1.8.3 // indirect
+	github.com/aws/aws-sdk-go-v2/internal/v4a v1.3.34 // indirect
+	github.com/aws/aws-sdk-go-v2/service/internal/accept-encoding v1.12.3 // indirect
+	github.com/aws/aws-sdk-go-v2/service/internal/checksum v1.7.2 // indirect
+	github.com/aws/aws-sdk-go-v2/service/internal/presigned-url v1.12.15 // indirect
+	github.com/aws/aws-sdk-go-v2/service/internal/s3shared v1.18.15 // indirect
+	github.com/aws/aws-sdk-go-v2/service/sso v1.25.3 // indirect
+	github.com/aws/aws-sdk-go-v2/service/ssooidc v1.30.1 // indirect
+	github.com/aws/aws-sdk-go-v2/service/sts v1.33.19 // indirect
+	github.com/aws/smithy-go v1.22.3 // indirect
+	github.com/davecgh/go-spew v1.1.2-0.20180830191138-d8f796af33cc // indirect
+	github.com/disintegration/imaging v1.6.2
+	github.com/golang-jwt/jwt/v5 v5.2.2
+	github.com/inconshreveable/mousetrap v1.1.0 // indirect
+	github.com/labstack/gommon v0.4.2 // indirect
+	github.com/mattn/go-colorable v0.1.14 // indirect
+	github.com/mattn/go-isatty v0.0.20 // indirect
+	github.com/pmezard/go-difflib v1.0.1-0.20181226105442-5d4384ee4fb2 // indirect
+	github.com/soheilhy/cmux v0.1.5
+	github.com/spf13/pflag v1.0.6 // indirect
 	github.com/valyala/bytebufferpool v1.0.0 // indirect
-	github.com/valyala/fasttemplate v1.2.1 // indirect
-	go.uber.org/atomic v1.9.0 // indirect
-	go.uber.org/multierr v1.8.0 // indirect
-	golang.org/x/sys v0.5.0 // indirect
-	golang.org/x/text v0.7.0 // indirect
-	golang.org/x/time v0.1.0 // indirect
-	google.golang.org/appengine v1.6.7 // indirect
-	google.golang.org/protobuf v1.28.1 // indirect
-	gopkg.in/check.v1 v1.0.0-20201130134442-10cb98267c6c // indirect
-	gopkg.in/ini.v1 v1.67.0 // indirect
+	github.com/valyala/fasttemplate v1.2.2 // indirect
+	golang.org/x/sys v0.33.0 // indirect
+	golang.org/x/text v0.25.0 // indirect
+	golang.org/x/time v0.11.0 // indirect
+	google.golang.org/protobuf v1.36.6
 	gopkg.in/yaml.v3 v3.0.1 // indirect
 )
@@ -0,0 +1,7 @@
+package base
+
+import "regexp"
+
+var (
+	UIDMatcher = regexp.MustCompile("^[a-zA-Z0-9]([a-zA-Z0-9-]{0,30}[a-zA-Z0-9])?$")
+)
@@ -0,0 +1,35 @@
+package base
+
+import (
+	"testing"
+)
+
+func TestUIDMatcher(t *testing.T) {
+	tests := []struct {
+		input    string
+		expected bool
+	}{
+		{"", false},
+		{"-abc123", false},
+		{"012345678901234567890123456789", true},
+		{"1abc-123", true},
+		{"A123B456C789", true},
+		{"a", true},
+		{"ab", true},
+		{"a*b&c", false},
+		{"a--b", true},
+		{"a-1b-2c", true},
+		{"a1234567890123456789012345678901", true},
+		{"abc123", true},
+		{"abc123-", false},
+	}
+
+	for _, test := range tests {
+		t.Run(test.input, func(*testing.T) {
+			result := UIDMatcher.MatchString(test.input)
+			if result != test.expected {
+				t.Errorf("For input '%s', expected %v but got %v", test.input, test.expected, result)
+			}
+		})
+	}
+}
@@ -0,0 +1,92 @@
+package profile
+
+import (
+	"fmt"
+	"log/slog"
+	"os"
+	"path/filepath"
+	"runtime"
+	"strings"
+
+	"github.com/pkg/errors"
+)
+
+// Profile is the configuration to start main server.
+type Profile struct {
+	// Mode can be "prod" or "dev" or "demo"
+	Mode string
+	// Addr is the binding address for server
+	Addr string
+	// Port is the binding port for server
+	Port int
+	// UNIXSock is the IPC binding path. Overrides Addr and Port
+	UNIXSock string
+	// Data is the data directory
+	Data string
+	// DSN points to where memos stores its own data
+	DSN string
+	// Driver is the database driver
+	// sqlite, mysql
+	Driver string
+	// Version is the current version of server
+	Version string
+	// InstanceURL is the url of your memos instance.
+	InstanceURL string
+}
+
+func (p *Profile) IsDev() bool {
+	return p.Mode != "prod"
+}
+
+func checkDataDir(dataDir string) (string, error) {
+	// Convert to absolute path if relative path is supplied.
+	if !filepath.IsAbs(dataDir) {
+		relativeDir := filepath.Join(filepath.Dir(os.Args[0]), dataDir)
+		absDir, err := filepath.Abs(relativeDir)
+		if err != nil {
+			return "", err
+		}
+		dataDir = absDir
+	}
+
+	// Trim trailing \ or / in case user supplies
+	dataDir = strings.TrimRight(dataDir, "\\/")
+	if _, err := os.Stat(dataDir); err != nil {
+		return "", errors.Wrapf(err, "unable to access data folder %s", dataDir)
+	}
+	return dataDir, nil
+}
+
+func (p *Profile) Validate() error {
+	if p.Mode != "demo" && p.Mode != "dev" && p.Mode != "prod" {
+		p.Mode = "demo"
+	}
+
+	if p.Mode == "prod" && p.Data == "" {
+		if runtime.GOOS == "windows" {
+			p.Data = filepath.Join(os.Getenv("ProgramData"), "memos")
+			if _, err := os.Stat(p.Data); os.IsNotExist(err) {
+				if err := os.MkdirAll(p.Data, 0770); err != nil {
+					slog.Error("failed to create data directory", slog.String("data", p.Data), slog.String("error", err.Error()))
+					return err
+				}
+			}
+		} else {
+			p.Data = "/var/opt/memos"
+		}
+	}
+
+	dataDir, err := checkDataDir(p.Data)
+	if err != nil {
+		slog.Error("failed to check dsn", slog.String("data", dataDir), slog.String("error", err.Error()))
+		return err
+	}
+
+	p.Data = dataDir
+	if p.Driver == "sqlite" && p.DSN == "" {
+		dbFile := fmt.Sprintf("memos_%s.db", p.Mode)
+		p.DSN = filepath.Join(dataDir, dbFile)
+	}
+
+	return nil
+}
@@ -1,14 +1,24 @@
-package common
+package util

 import (
 	"crypto/rand"
 	"math/big"
 	"net/mail"
+	"strconv"
 	"strings"

 	"github.com/google/uuid"
 )

+// ConvertStringToInt32 converts a string to int32.
+func ConvertStringToInt32(src string) (int32, error) {
+	parsed, err := strconv.ParseInt(src, 10, 32)
+	if err != nil {
+		return 0, err
+	}
+	return int32(parsed), nil
+}
+
 // HasPrefixes returns true if the string s has any of the given prefixes.
 func HasPrefixes(src string, prefixes ...string) bool {
 	for _, prefix := range prefixes {
@@ -31,13 +41,6 @@ func GenUUID() string {
 	return uuid.New().String()
 }

-func Min(x, y int) int {
-	if x < y {
-		return x
-	}
-	return y
-}
-
 var letters = []rune("0123456789abcdefghijklmnopqrstuvwxyzABCDEFGHIJKLMNOPQRSTUVWXYZ")

 // RandomString returns a random string with length n.
@@ -58,3 +61,13 @@ func RandomString(n int) (string, error) {
 	}
 	return sb.String(), nil
 }
+
+// ReplaceString replaces all occurrences of old in slice with new.
+func ReplaceString(slice []string, old, new string) []string {
+	for i, s := range slice {
+		if s == old {
+			slice[i] = new
+		}
+	}
+	return slice
+}
@@ -1,4 +1,4 @@
-package common
+package util

 import (
 	"testing"
@@ -14,7 +14,7 @@ func TestValidateEmail(t *testing.T) {
 			want:  true,
 		},
 		{
-			email: "@qq.com",
+			email: "@usememos.com",
 			want:  false,
 		},
 		{
@@ -9,10 +9,10 @@ import (

 // Version is the service current released version.
 // Semantic versioning: https://semver.org/
-var Version = "0.11.2"
+var Version = "0.24.4"

 // DevVersion is the service current development version.
-var DevVersion = "0.11.2"
+var DevVersion = "0.24.4"

 func GetCurrentVersion(mode string) string {
 	if mode == "dev" || mode == "demo" {
@@ -29,11 +29,6 @@ func GetMinorVersion(version string) string {
 	return versionList[0] + "." + versionList[1]
 }

-func GetSchemaVersion(version string) string {
-	minorVersion := GetMinorVersion(version)
-	return minorVersion + ".0"
-}
-
 // IsVersionGreaterOrEqualThan returns true if version is greater than or equal to target.
 func IsVersionGreaterOrEqualThan(version, target string) bool {
 	return semver.Compare(fmt.Sprintf("v%s", version), fmt.Sprintf("v%s", target)) > -1
@@ -53,6 +53,11 @@ func TestIsVersionGreaterThan(t *testing.T) {
 			target:  "0.8.0",
 			want:    true,
 		},
+		{
+			version: "0.23",
+			target:  "0.22",
+			want:    true,
+		},
 		{
 			version: "0.8.0",
 			target:  "0.10.0",
@@ -63,6 +68,11 @@ func TestIsVersionGreaterThan(t *testing.T) {
 			target:  "0.9.1",
 			want:    false,
 		},
+		{
+			version: "0.22",
+			target:  "0.22",
+			want:    false,
+		},
 	}
 	for _, test := range tests {
 		result := IsVersionGreaterThan(test.version, test.target)
@@ -1,14 +0,0 @@
-package main
-
-import (
-	_ "github.com/mattn/go-sqlite3"
-
-	"github.com/usememos/memos/cmd"
-)
-
-func main() {
-	err := cmd.Execute()
-	if err != nil {
-		panic(err)
-	}
-}
@@ -0,0 +1 @@
+Fork from https://github.com/robfig/cron
@@ -0,0 +1,96 @@
+package cron
+
+import (
+	"errors"
+	"fmt"
+	"runtime"
+	"sync"
+	"time"
+)
+
+// JobWrapper decorates the given Job with some behavior.
+type JobWrapper func(Job) Job
+
+// Chain is a sequence of JobWrappers that decorates submitted jobs with
+// cross-cutting behaviors like logging or synchronization.
+type Chain struct {
+	wrappers []JobWrapper
+}
+
+// NewChain returns a Chain consisting of the given JobWrappers.
+func NewChain(c ...JobWrapper) Chain {
+	return Chain{c}
+}
+
+// Then decorates the given job with all JobWrappers in the chain.
+//
+// This:
+//
+//	NewChain(m1, m2, m3).Then(job)
+//
+// is equivalent to:
+//
+//	m1(m2(m3(job)))
+func (c Chain) Then(j Job) Job {
+	for i := range c.wrappers {
+		j = c.wrappers[len(c.wrappers)-i-1](j)
+	}
+	return j
+}
+
+// Recover panics in wrapped jobs and log them with the provided logger.
+func Recover(logger Logger) JobWrapper {
+	return func(j Job) Job {
+		return FuncJob(func() {
+			defer func() {
+				if r := recover(); r != nil {
+					const size = 64 << 10
+					buf := make([]byte, size)
+					buf = buf[:runtime.Stack(buf, false)]
+					err, ok := r.(error)
+					if !ok {
+						err = errors.New("panic: " + fmt.Sprint(r))
+					}
+					logger.Error(err, "panic", "stack", "...\n"+string(buf))
+				}
+			}()
+			j.Run()
+		})
+	}
+}
+
+// DelayIfStillRunning serializes jobs, delaying subsequent runs until the
+// previous one is complete. Jobs running after a delay of more than a minute
+// have the delay logged at Info.
+func DelayIfStillRunning(logger Logger) JobWrapper {
+	return func(j Job) Job {
+		var mu sync.Mutex
+		return FuncJob(func() {
+			start := time.Now()
+			mu.Lock()
+			defer mu.Unlock()
+			if dur := time.Since(start); dur > time.Minute {
+				logger.Info("delay", "duration", dur)
+			}
+			j.Run()
+		})
+	}
+}
+
+// SkipIfStillRunning skips an invocation of the Job if a previous invocation is
+// still running. It logs skips to the given logger at Info level.
+func SkipIfStillRunning(logger Logger) JobWrapper {
+	return func(j Job) Job {
+		var ch = make(chan struct{}, 1)
+		ch <- struct{}{}
+		return FuncJob(func() {
+			select {
+			case v := <-ch:
+				defer func() { ch <- v }()
+				j.Run()
+			default:
+				logger.Info("skip")
+			}
+		})
+	}
+}
@@ -0,0 +1,239 @@
+//nolint:all
+package cron
+
+import (
+	"io"
+	"log"
+	"reflect"
+	"sync"
+	"testing"
+	"time"
+)
+
+func appendingJob(slice *[]int, value int) Job {
+	var m sync.Mutex
+	return FuncJob(func() {
+		m.Lock()
+		*slice = append(*slice, value)
+		m.Unlock()
+	})
+}
+
+func appendingWrapper(slice *[]int, value int) JobWrapper {
+	return func(j Job) Job {
+		return FuncJob(func() {
+			appendingJob(slice, value).Run()
+			j.Run()
+		})
+	}
+}
+
+func TestChain(t *testing.T) {
+	var nums []int
+	var (
+		append1 = appendingWrapper(&nums, 1)
+		append2 = appendingWrapper(&nums, 2)
+		append3 = appendingWrapper(&nums, 3)
+		append4 = appendingJob(&nums, 4)
+	)
+	NewChain(append1, append2, append3).Then(append4).Run()
+	if !reflect.DeepEqual(nums, []int{1, 2, 3, 4}) {
+		t.Error("unexpected order of calls:", nums)
+	}
+}
+
+func TestChainRecover(t *testing.T) {
+	panickingJob := FuncJob(func() {
+		panic("panickingJob panics")
+	})
+
+	t.Run("panic exits job by default", func(*testing.T) {
+		defer func() {
+			if err := recover(); err == nil {
+				t.Errorf("panic expected, but none received")
+			}
+		}()
+		NewChain().Then(panickingJob).
+			Run()
+	})
+
+	t.Run("Recovering JobWrapper recovers", func(*testing.T) {
+		NewChain(Recover(PrintfLogger(log.New(io.Discard, "", 0)))).
+			Then(panickingJob).
+			Run()
+	})
+
+	t.Run("composed with the *IfStillRunning wrappers", func(*testing.T) {
+		NewChain(Recover(PrintfLogger(log.New(io.Discard, "", 0)))).
+			Then(panickingJob).
+			Run()
+	})
+}
+
+type countJob struct {
+	m       sync.Mutex
+	started int
+	done    int
+	delay   time.Duration
+}
+
+func (j *countJob) Run() {
+	j.m.Lock()
+	j.started++
+	j.m.Unlock()
+	time.Sleep(j.delay)
+	j.m.Lock()
+	j.done++
+	j.m.Unlock()
+}
+
+func (j *countJob) Started() int {
+	defer j.m.Unlock()
+	j.m.Lock()
+	return j.started
+}
+
+func (j *countJob) Done() int {
+	defer j.m.Unlock()
+	j.m.Lock()
+	return j.done
+}
+
+func TestChainDelayIfStillRunning(t *testing.T) {
+	t.Run("runs immediately", func(*testing.T) {
+		var j countJob
+		wrappedJob := NewChain(DelayIfStillRunning(DiscardLogger)).Then(&j)
+		go wrappedJob.Run()
+		time.Sleep(2 * time.Millisecond) // Give the job 2ms to complete.
+		if c := j.Done(); c != 1 {
+			t.Errorf("expected job run once, immediately, got %d", c)
+		}
+	})
+
+	t.Run("second run immediate if first done", func(*testing.T) {
+		var j countJob
+		wrappedJob := NewChain(DelayIfStillRunning(DiscardLogger)).Then(&j)
+		go func() {
+			go wrappedJob.Run()
+			time.Sleep(time.Millisecond)
+			go wrappedJob.Run()
+		}()
+		time.Sleep(3 * time.Millisecond) // Give both jobs 3ms to complete.
+		if c := j.Done(); c != 2 {
+			t.Errorf("expected job run twice, immediately, got %d", c)
+		}
+	})
+
+	t.Run("second run delayed if first not done", func(*testing.T) {
+		var j countJob
+		j.delay = 10 * time.Millisecond
+		wrappedJob := NewChain(DelayIfStillRunning(DiscardLogger)).Then(&j)
+		go func() {
+			go wrappedJob.Run()
+			time.Sleep(time.Millisecond)
+			go wrappedJob.Run()
+		}()
+
+		// After 5ms, the first job is still in progress, and the second job was
+		// run but should be waiting for it to finish.
+		time.Sleep(5 * time.Millisecond)
+		started, done := j.Started(), j.Done()
+		if started != 1 || done != 0 {
+			t.Error("expected first job started, but not finished, got", started, done)
+		}
+
+		// Verify that the second job completes.
+		time.Sleep(25 * time.Millisecond)
+		started, done = j.Started(), j.Done()
+		if started != 2 || done != 2 {
+			t.Error("expected both jobs done, got", started, done)
+		}
+	})
+}
+
+func TestChainSkipIfStillRunning(t *testing.T) {
+	t.Run("runs immediately", func(*testing.T) {
+		var j countJob
+		wrappedJob := NewChain(SkipIfStillRunning(DiscardLogger)).Then(&j)
+		go wrappedJob.Run()
+		time.Sleep(2 * time.Millisecond) // Give the job 2ms to complete.
+		if c := j.Done(); c != 1 {
+			t.Errorf("expected job run once, immediately, got %d", c)
+		}
+	})
+
+	t.Run("second run immediate if first done", func(*testing.T) {
+		var j countJob
+		wrappedJob := NewChain(SkipIfStillRunning(DiscardLogger)).Then(&j)
+		go func() {
+			go wrappedJob.Run()
+			time.Sleep(time.Millisecond)
+			go wrappedJob.Run()
+		}()
+		time.Sleep(3 * time.Millisecond) // Give both jobs 3ms to complete.
+		if c := j.Done(); c != 2 {
+			t.Errorf("expected job run twice, immediately, got %d", c)
+		}
+	})
+
+	t.Run("second run skipped if first not done", func(*testing.T) {
+		var j countJob
+		j.delay = 10 * time.Millisecond
+		wrappedJob := NewChain(SkipIfStillRunning(DiscardLogger)).Then(&j)
+		go func() {
+			go wrappedJob.Run()
+			time.Sleep(time.Millisecond)
+			go wrappedJob.Run()
+		}()
+
+		// After 5ms, the first job is still in progress, and the second job was
+		// aleady skipped.
+		time.Sleep(5 * time.Millisecond)
+		started, done := j.Started(), j.Done()
+		if started != 1 || done != 0 {
+			t.Error("expected first job started, but not finished, got", started, done)
+		}
+
+		// Verify that the first job completes and second does not run.
+		time.Sleep(25 * time.Millisecond)
+		started, done = j.Started(), j.Done()
+		if started != 1 || done != 1 {
+			t.Error("expected second job skipped, got", started, done)
+		}
+	})
+
+	t.Run("skip 10 jobs on rapid fire", func(*testing.T) {
+		var j countJob
+		j.delay = 10 * time.Millisecond
+		wrappedJob := NewChain(SkipIfStillRunning(DiscardLogger)).Then(&j)
+		for i := 0; i < 11; i++ {
+			go wrappedJob.Run()
+		}
+		time.Sleep(200 * time.Millisecond)
+		done := j.Done()
+		if done != 1 {
+			t.Error("expected 1 jobs executed, 10 jobs dropped, got", done)
+		}
+	})
+
+	t.Run("different jobs independent", func(*testing.T) {
+		var j1, j2 countJob
+		j1.delay = 10 * time.Millisecond
+		j2.delay = 10 * time.Millisecond
+		chain := NewChain(SkipIfStillRunning(DiscardLogger))
+		wrappedJob1 := chain.Then(&j1)
+		wrappedJob2 := chain.Then(&j2)
+		for i := 0; i < 11; i++ {
+			go wrappedJob1.Run()
+			go wrappedJob2.Run()
+		}
+		time.Sleep(100 * time.Millisecond)
+		var (
+			done1 = j1.Done()
+			done2 = j2.Done()
+		)
+		if done1 != 1 || done2 != 1 {
+			t.Error("expected both jobs executed once, got", done1, "and", done2)
+		}
+	})
+}
@@ -0,0 +1,27 @@
+package cron
+
+import "time"
+
+// ConstantDelaySchedule represents a simple recurring duty cycle, e.g. "Every 5 minutes".
+// It does not support jobs more frequent than once a second.
+type ConstantDelaySchedule struct {
+	Delay time.Duration
+}
+
+// Every returns a crontab Schedule that activates once every duration.
+// Delays of less than a second are not supported (will round up to 1 second).
+// Any fields less than a Second are truncated.
+func Every(duration time.Duration) ConstantDelaySchedule {
+	if duration < time.Second {
+		duration = time.Second
+	}
+	return ConstantDelaySchedule{
+		Delay: duration - time.Duration(duration.Nanoseconds())%time.Second,
+	}
+}
+
+// Next returns the next time this should be run.
+// This rounds so that the next activation time will be on the second.
+func (schedule ConstantDelaySchedule) Next(t time.Time) time.Time {
+	return t.Add(schedule.Delay - time.Duration(t.Nanosecond())*time.Nanosecond)
+}
@@ -0,0 +1,55 @@
+//nolint:all
+package cron
+
+import (
+	"testing"
+	"time"
+)
+
+func TestConstantDelayNext(t *testing.T) {
+	tests := []struct {
+		time     string
+		delay    time.Duration
+		expected string
+	}{
+		// Simple cases
+		{"Mon Jul 9 14:45 2012", 15*time.Minute + 50*time.Nanosecond, "Mon Jul 9 15:00 2012"},
+		{"Mon Jul 9 14:59 2012", 15 * time.Minute, "Mon Jul 9 15:14 2012"},
+		{"Mon Jul 9 14:59:59 2012", 15 * time.Minute, "Mon Jul 9 15:14:59 2012"},
+
+		// Wrap around hours
+		{"Mon Jul 9 15:45 2012", 35 * time.Minute, "Mon Jul 9 16:20 2012"},
+
+		// Wrap around days
+		{"Mon Jul 9 23:46 2012", 14 * time.Minute, "Tue Jul 10 00:00 2012"},
+		{"Mon Jul 9 23:45 2012", 35 * time.Minute, "Tue Jul 10 00:20 2012"},
+		{"Mon Jul 9 23:35:51 2012", 44*time.Minute + 24*time.Second, "Tue Jul 10 00:20:15 2012"},
+		{"Mon Jul 9 23:35:51 2012", 25*time.Hour + 44*time.Minute + 24*time.Second, "Thu Jul 11 01:20:15 2012"},
+
+		// Wrap around months
+		{"Mon Jul 9 23:35 2012", 91*24*time.Hour + 25*time.Minute, "Thu Oct 9 00:00 2012"},
+
+		// Wrap around minute, hour, day, month, and year
+		{"Mon Dec 31 23:59:45 2012", 15 * time.Second, "Tue Jan 1 00:00:00 2013"},
+
+		// Round to nearest second on the delay
+		{"Mon Jul 9 14:45 2012", 15*time.Minute + 50*time.Nanosecond, "Mon Jul 9 15:00 2012"},
+
+		// Round up to 1 second if the duration is less.
+		{"Mon Jul 9 14:45:00 2012", 15 * time.Millisecond, "Mon Jul 9 14:45:01 2012"},
+
+		// Round to nearest second when calculating the next time.
+		{"Mon Jul 9 14:45:00.005 2012", 15 * time.Minute, "Mon Jul 9 15:00 2012"},
+
+		// Round to nearest second for both.
+		{"Mon Jul 9 14:45:00.005 2012", 15*time.Minute + 50*time.Nanosecond, "Mon Jul 9 15:00 2012"},
+	}
+
+	for _, c := range tests {
+		actual := Every(c.delay).Next(getTime(c.time))
+		expected := getTime(c.expected)
+		if actual != expected {
+			t.Errorf("%s, \"%s\": (expected) %v != %v (actual)", c.time, c.delay, expected, actual)
+		}
+	}
+}
@@ -0,0 +1,355 @@
+package cron
+
+import (
+	"context"
+	"sort"
+	"sync"
+	"time"
+)
+
+// Cron keeps track of any number of entries, invoking the associated func as
+// specified by the schedule. It may be started, stopped, and the entries may
+// be inspected while running.
+type Cron struct {
+	entries   []*Entry
+	chain     Chain
+	stop      chan struct{}
+	add       chan *Entry
+	remove    chan EntryID
+	snapshot  chan chan []Entry
+	running   bool
+	logger    Logger
+	runningMu sync.Mutex
+	location  *time.Location
+	parser    ScheduleParser
+	nextID    EntryID
+	jobWaiter sync.WaitGroup
+}
+
+// ScheduleParser is an interface for schedule spec parsers that return a Schedule.
+type ScheduleParser interface {
+	Parse(spec string) (Schedule, error)
+}
+
+// Job is an interface for submitted cron jobs.
+type Job interface {
+	Run()
+}
+
+// Schedule describes a job's duty cycle.
+type Schedule interface {
+	// Next returns the next activation time, later than the given time.
+	// Next is invoked initially, and then each time the job is run.
+	Next(time.Time) time.Time
+}
+
+// EntryID identifies an entry within a Cron instance.
+type EntryID int
+
+// Entry consists of a schedule and the func to execute on that schedule.
+type Entry struct {
+	// ID is the cron-assigned ID of this entry, which may be used to look up a
+	// snapshot or remove it.
+	ID EntryID
+
+	// Schedule on which this job should be run.
+	Schedule Schedule
+
+	// Next time the job will run, or the zero time if Cron has not been
+	// started or this entry's schedule is unsatisfiable
+	Next time.Time
+
+	// Prev is the last time this job was run, or the zero time if never.
+	Prev time.Time
+
+	// WrappedJob is the thing to run when the Schedule is activated.
+	WrappedJob Job
+
+	// Job is the thing that was submitted to cron.
+	// It is kept around so that user code that needs to get at the job later,
+	// e.g. via Entries() can do so.
+	Job Job
+}
+
+// Valid returns true if this is not the zero entry.
+func (e Entry) Valid() bool { return e.ID != 0 }
+
+// byTime is a wrapper for sorting the entry array by time
+// (with zero time at the end).
+type byTime []*Entry
+
+func (s byTime) Len() int      { return len(s) }
+func (s byTime) Swap(i, j int) { s[i], s[j] = s[j], s[i] }
+func (s byTime) Less(i, j int) bool {
+	// Two zero times should return false.
+	// Otherwise, zero is "greater" than any other time.
+	// (To sort it at the end of the list.)
+	if s[i].Next.IsZero() {
+		return false
+	}
+	if s[j].Next.IsZero() {
+		return true
+	}
+	return s[i].Next.Before(s[j].Next)
+}
+
+// New returns a new Cron job runner, modified by the given options.
+//
+// Available Settings
+//
+//	Time Zone
+//	  Description: The time zone in which schedules are interpreted
+//	  Default:     time.Local
+//
+//	Parser
+//	  Description: Parser converts cron spec strings into cron.Schedules.
+//	  Default:     Accepts this spec: https://en.wikipedia.org/wiki/Cron
+//
+//	Chain
+//	  Description: Wrap submitted jobs to customize behavior.
+//	  Default:     A chain that recovers panics and logs them to stderr.
+//
+// See "cron.With*" to modify the default behavior.
+func New(opts ...Option) *Cron {
+	c := &Cron{
+		entries:   nil,
+		chain:     NewChain(),
+		add:       make(chan *Entry),
+		stop:      make(chan struct{}),
+		snapshot:  make(chan chan []Entry),
+		remove:    make(chan EntryID),
+		running:   false,
+		runningMu: sync.Mutex{},
+		logger:    DefaultLogger,
+		location:  time.Local,
+		parser:    standardParser,
+	}
+	for _, opt := range opts {
+		opt(c)
+	}
+	return c
+}
+
+// FuncJob is a wrapper that turns a func() into a cron.Job.
+type FuncJob func()
+
+func (f FuncJob) Run() { f() }
+
+// AddFunc adds a func to the Cron to be run on the given schedule.
+// The spec is parsed using the time zone of this Cron instance as the default.
+// An opaque ID is returned that can be used to later remove it.
+func (c *Cron) AddFunc(spec string, cmd func()) (EntryID, error) {
+	return c.AddJob(spec, FuncJob(cmd))
+}
+
+// AddJob adds a Job to the Cron to be run on the given schedule.
+// The spec is parsed using the time zone of this Cron instance as the default.
+// An opaque ID is returned that can be used to later remove it.
+func (c *Cron) AddJob(spec string, cmd Job) (EntryID, error) {
+	schedule, err := c.parser.Parse(spec)
+	if err != nil {
+		return 0, err
+	}
+	return c.Schedule(schedule, cmd), nil
+}
+
+// Schedule adds a Job to the Cron to be run on the given schedule.
+// The job is wrapped with the configured Chain.
+func (c *Cron) Schedule(schedule Schedule, cmd Job) EntryID {
+	c.runningMu.Lock()
+	defer c.runningMu.Unlock()
+	c.nextID++
+	entry := &Entry{
+		ID:         c.nextID,
+		Schedule:   schedule,
+		WrappedJob: c.chain.Then(cmd),
+		Job:        cmd,
+	}
+	if !c.running {
+		c.entries = append(c.entries, entry)
+	} else {
+		c.add <- entry
+	}
+	return entry.ID
+}
+
+// Entries returns a snapshot of the cron entries.
+func (c *Cron) Entries() []Entry {
+	c.runningMu.Lock()
+	defer c.runningMu.Unlock()
+	if c.running {
+		replyChan := make(chan []Entry, 1)
+		c.snapshot <- replyChan
+		return <-replyChan
+	}
+	return c.entrySnapshot()
+}
+
+// Location gets the time zone location.
+func (c *Cron) Location() *time.Location {
+	return c.location
+}
+
+// Entry returns a snapshot of the given entry, or nil if it couldn't be found.
+func (c *Cron) Entry(id EntryID) Entry {
+	for _, entry := range c.Entries() {
+		if id == entry.ID {
+			return entry
+		}
+	}
+	return Entry{}
+}
+
+// Remove an entry from being run in the future.
+func (c *Cron) Remove(id EntryID) {
+	c.runningMu.Lock()
+	defer c.runningMu.Unlock()
+	if c.running {
+		c.remove <- id
+	} else {
+		c.removeEntry(id)
+	}
+}
+
+// Start the cron scheduler in its own goroutine, or no-op if already started.
+func (c *Cron) Start() {
+	c.runningMu.Lock()
+	defer c.runningMu.Unlock()
+	if c.running {
+		return
+	}
+	c.running = true
+	go c.runScheduler()
+}
+
+// Run the cron scheduler, or no-op if already running.
+func (c *Cron) Run() {
+	c.runningMu.Lock()
+	if c.running {
+		c.runningMu.Unlock()
+		return
+	}
+	c.running = true
+	c.runningMu.Unlock()
+	c.runScheduler()
+}
+
+// runScheduler runs the scheduler.. this is private just due to the need to synchronize
+// access to the 'running' state variable.
+func (c *Cron) runScheduler() {
+	c.logger.Info("start")
+
+	// Figure out the next activation times for each entry.
+	now := c.now()
+	for _, entry := range c.entries {
+		entry.Next = entry.Schedule.Next(now)
+		c.logger.Info("schedule", "now", now, "entry", entry.ID, "next", entry.Next)
+	}
+
+	for {
+		// Determine the next entry to run.
+		sort.Sort(byTime(c.entries))
+
+		var timer *time.Timer
+		if len(c.entries) == 0 || c.entries[0].Next.IsZero() {
+			// If there are no entries yet, just sleep - it still handles new entries
+			// and stop requests.
+			timer = time.NewTimer(100000 * time.Hour)
+		} else {
+			timer = time.NewTimer(c.entries[0].Next.Sub(now))
+		}
+
+		for {
+			select {
+			case now = <-timer.C:
+				now = now.In(c.location)
+				c.logger.Info("wake", "now", now)
+
+				// Run every entry whose next time was less than now
+				for _, e := range c.entries {
+					if e.Next.After(now) || e.Next.IsZero() {
+						break
+					}
+					c.startJob(e.WrappedJob)
+					e.Prev = e.Next
+					e.Next = e.Schedule.Next(now)
+					c.logger.Info("run", "now", now, "entry", e.ID, "next", e.Next)
+				}
+
+			case newEntry := <-c.add:
+				timer.Stop()
+				now = c.now()
+				newEntry.Next = newEntry.Schedule.Next(now)
+				c.entries = append(c.entries, newEntry)
+				c.logger.Info("added", "now", now, "entry", newEntry.ID, "next", newEntry.Next)
+
+			case replyChan := <-c.snapshot:
+				replyChan <- c.entrySnapshot()
+				continue
+
+			case <-c.stop:
+				timer.Stop()
+				c.logger.Info("stop")
+				return
+
+			case id := <-c.remove:
+				timer.Stop()
+				now = c.now()
+				c.removeEntry(id)
+				c.logger.Info("removed", "entry", id)
+			}
+
+			break
+		}
+	}
+}
+
+// startJob runs the given job in a new goroutine.
+func (c *Cron) startJob(j Job) {
+	c.jobWaiter.Add(1)
+	go func() {
+		defer c.jobWaiter.Done()
+		j.Run()
+	}()
+}
+
+// now returns current time in c location.
+func (c *Cron) now() time.Time {
+	return time.Now().In(c.location)
+}
+
+// Stop stops the cron scheduler if it is running; otherwise it does nothing.
+// A context is returned so the caller can wait for running jobs to complete.
+func (c *Cron) Stop() context.Context {
+	c.runningMu.Lock()
+	defer c.runningMu.Unlock()
+	if c.running {
+		c.stop <- struct{}{}
+		c.running = false
+	}
+	ctx, cancel := context.WithCancel(context.Background())
+	go func() {
+		c.jobWaiter.Wait()
+		cancel()
+	}()
+	return ctx
+}
+
+// entrySnapshot returns a copy of the current cron entry list.
+func (c *Cron) entrySnapshot() []Entry {
+	var entries = make([]Entry, len(c.entries))
+	for i, e := range c.entries {
+		entries[i] = *e
+	}
+	return entries
+}
+
+func (c *Cron) removeEntry(id EntryID) {
+	var entries []*Entry
+	for _, e := range c.entries {
+		if e.ID != id {
+			entries = append(entries, e)
+		}
+	}
+	c.entries = entries
+}
@@ -0,0 +1,702 @@
+//nolint:all
+package cron
+
+import (
+	"bytes"
+	"fmt"
+	"log"
+	"strings"
+	"sync"
+	"sync/atomic"
+	"testing"
+	"time"
+)
+
+// Many tests schedule a job for every second, and then wait at most a second
+// for it to run.  This amount is just slightly larger than 1 second to
+// compensate for a few milliseconds of runtime.
+const OneSecond = 1*time.Second + 50*time.Millisecond
+
+type syncWriter struct {
+	wr bytes.Buffer
+	m  sync.Mutex
+}
+
+func (sw *syncWriter) Write(data []byte) (n int, err error) {
+	sw.m.Lock()
+	n, err = sw.wr.Write(data)
+	sw.m.Unlock()
+	return
+}
+
+func (sw *syncWriter) String() string {
+	sw.m.Lock()
+	defer sw.m.Unlock()
+	return sw.wr.String()
+}
+
+func newBufLogger(sw *syncWriter) Logger {
+	return PrintfLogger(log.New(sw, "", log.LstdFlags))
+}
+
+func TestFuncPanicRecovery(t *testing.T) {
+	var buf syncWriter
+	cron := New(WithParser(secondParser),
+		WithChain(Recover(newBufLogger(&buf))))
+	cron.Start()
+	defer cron.Stop()
+	cron.AddFunc("* * * * * ?", func() {
+		panic("YOLO")
+	})
+
+	select {
+	case <-time.After(OneSecond):
+		if !strings.Contains(buf.String(), "YOLO") {
+			t.Error("expected a panic to be logged, got none")
+		}
+		return
+	}
+}
+
+type DummyJob struct{}
+
+func (DummyJob) Run() {
+	panic("YOLO")
+}
+
+func TestJobPanicRecovery(t *testing.T) {
+	var job DummyJob
+
+	var buf syncWriter
+	cron := New(WithParser(secondParser),
+		WithChain(Recover(newBufLogger(&buf))))
+	cron.Start()
+	defer cron.Stop()
+	cron.AddJob("* * * * * ?", job)
+
+	select {
+	case <-time.After(OneSecond):
+		if !strings.Contains(buf.String(), "YOLO") {
+			t.Error("expected a panic to be logged, got none")
+		}
+		return
+	}
+}
+
+// Start and stop cron with no entries.
+func TestNoEntries(t *testing.T) {
+	cron := newWithSeconds()
+	cron.Start()
+
+	select {
+	case <-time.After(OneSecond):
+		t.Fatal("expected cron will be stopped immediately")
+	case <-stop(cron):
+	}
+}
+
+// Start, stop, then add an entry. Verify entry doesn't run.
+func TestStopCausesJobsToNotRun(t *testing.T) {
+	wg := &sync.WaitGroup{}
+	wg.Add(1)
+
+	cron := newWithSeconds()
+	cron.Start()
+	cron.Stop()
+	cron.AddFunc("* * * * * ?", func() { wg.Done() })
+
+	select {
+	case <-time.After(OneSecond):
+		// No job ran!
+	case <-wait(wg):
+		t.Fatal("expected stopped cron does not run any job")
+	}
+}
+
+// Add a job, start cron, expect it runs.
+func TestAddBeforeRunning(t *testing.T) {
+	wg := &sync.WaitGroup{}
+	wg.Add(1)
+
+	cron := newWithSeconds()
+	cron.AddFunc("* * * * * ?", func() { wg.Done() })
+	cron.Start()
+	defer cron.Stop()
+
+	// Give cron 2 seconds to run our job (which is always activated).
+	select {
+	case <-time.After(OneSecond):
+		t.Fatal("expected job runs")
+	case <-wait(wg):
+	}
+}
+
+// Start cron, add a job, expect it runs.
+func TestAddWhileRunning(t *testing.T) {
+	wg := &sync.WaitGroup{}
+	wg.Add(1)
+
+	cron := newWithSeconds()
+	cron.Start()
+	defer cron.Stop()
+	cron.AddFunc("* * * * * ?", func() { wg.Done() })
+
+	select {
+	case <-time.After(OneSecond):
+		t.Fatal("expected job runs")
+	case <-wait(wg):
+	}
+}
+
+// Test for #34. Adding a job after calling start results in multiple job invocations
+func TestAddWhileRunningWithDelay(t *testing.T) {
+	cron := newWithSeconds()
+	cron.Start()
+	defer cron.Stop()
+	time.Sleep(5 * time.Second)
+	var calls int64
+	cron.AddFunc("* * * * * *", func() { atomic.AddInt64(&calls, 1) })
+
+	<-time.After(OneSecond)
+	if atomic.LoadInt64(&calls) != 1 {
+		t.Errorf("called %d times, expected 1\n", calls)
+	}
+}
+
+// Add a job, remove a job, start cron, expect nothing runs.
+func TestRemoveBeforeRunning(t *testing.T) {
+	wg := &sync.WaitGroup{}
+	wg.Add(1)
+
+	cron := newWithSeconds()
+	id, _ := cron.AddFunc("* * * * * ?", func() { wg.Done() })
+	cron.Remove(id)
+	cron.Start()
+	defer cron.Stop()
+
+	select {
+	case <-time.After(OneSecond):
+		// Success, shouldn't run
+	case <-wait(wg):
+		t.FailNow()
+	}
+}
+
+// Start cron, add a job, remove it, expect it doesn't run.
+func TestRemoveWhileRunning(t *testing.T) {
+	wg := &sync.WaitGroup{}
+	wg.Add(1)
+
+	cron := newWithSeconds()
+	cron.Start()
+	defer cron.Stop()
+	id, _ := cron.AddFunc("* * * * * ?", func() { wg.Done() })
+	cron.Remove(id)
+
+	select {
+	case <-time.After(OneSecond):
+	case <-wait(wg):
+		t.FailNow()
+	}
+}
+
+// Test timing with Entries.
+func TestSnapshotEntries(t *testing.T) {
+	wg := &sync.WaitGroup{}
+	wg.Add(1)
+
+	cron := New()
+	cron.AddFunc("@every 2s", func() { wg.Done() })
+	cron.Start()
+	defer cron.Stop()
+
+	// Cron should fire in 2 seconds. After 1 second, call Entries.
+	select {
+	case <-time.After(OneSecond):
+		cron.Entries()
+	}
+
+	// Even though Entries was called, the cron should fire at the 2 second mark.
+	select {
+	case <-time.After(OneSecond):
+		t.Error("expected job runs at 2 second mark")
+	case <-wait(wg):
+	}
+}
+
+// Test that the entries are correctly sorted.
+// Add a bunch of long-in-the-future entries, and an immediate entry, and ensure
+// that the immediate entry runs immediately.
+// Also: Test that multiple jobs run in the same instant.
+func TestMultipleEntries(t *testing.T) {
+	wg := &sync.WaitGroup{}
+	wg.Add(2)
+
+	cron := newWithSeconds()
+	cron.AddFunc("0 0 0 1 1 ?", func() {})
+	cron.AddFunc("* * * * * ?", func() { wg.Done() })
+	id1, _ := cron.AddFunc("* * * * * ?", func() { t.Fatal() })
+	id2, _ := cron.AddFunc("* * * * * ?", func() { t.Fatal() })
+	cron.AddFunc("0 0 0 31 12 ?", func() {})
+	cron.AddFunc("* * * * * ?", func() { wg.Done() })
+
+	cron.Remove(id1)
+	cron.Start()
+	cron.Remove(id2)
+	defer cron.Stop()
+
+	select {
+	case <-time.After(OneSecond):
+		t.Error("expected job run in proper order")
+	case <-wait(wg):
+	}
+}
+
+// Test running the same job twice.
+func TestRunningJobTwice(t *testing.T) {
+	wg := &sync.WaitGroup{}
+	wg.Add(2)
+
+	cron := newWithSeconds()
+	cron.AddFunc("0 0 0 1 1 ?", func() {})
+	cron.AddFunc("0 0 0 31 12 ?", func() {})
+	cron.AddFunc("* * * * * ?", func() { wg.Done() })
+
+	cron.Start()
+	defer cron.Stop()
+
+	select {
+	case <-time.After(2 * OneSecond):
+		t.Error("expected job fires 2 times")
+	case <-wait(wg):
+	}
+}
+
+func TestRunningMultipleSchedules(t *testing.T) {
+	wg := &sync.WaitGroup{}
+	wg.Add(2)
+
+	cron := newWithSeconds()
+	cron.AddFunc("0 0 0 1 1 ?", func() {})
+	cron.AddFunc("0 0 0 31 12 ?", func() {})
+	cron.AddFunc("* * * * * ?", func() { wg.Done() })
+	cron.Schedule(Every(time.Minute), FuncJob(func() {}))
+	cron.Schedule(Every(time.Second), FuncJob(func() { wg.Done() }))
+	cron.Schedule(Every(time.Hour), FuncJob(func() {}))
+
+	cron.Start()
+	defer cron.Stop()
+
+	select {
+	case <-time.After(2 * OneSecond):
+		t.Error("expected job fires 2 times")
+	case <-wait(wg):
+	}
+}
+
+// Test that the cron is run in the local time zone (as opposed to UTC).
+func TestLocalTimezone(t *testing.T) {
+	wg := &sync.WaitGroup{}
+	wg.Add(2)
+
+	now := time.Now()
+	// FIX: Issue #205
+	// This calculation doesn't work in seconds 58 or 59.
+	// Take the easy way out and sleep.
+	if now.Second() >= 58 {
+		time.Sleep(2 * time.Second)
+		now = time.Now()
+	}
+	spec := fmt.Sprintf("%d,%d %d %d %d %d ?",
+		now.Second()+1, now.Second()+2, now.Minute(), now.Hour(), now.Day(), now.Month())
+
+	cron := newWithSeconds()
+	cron.AddFunc(spec, func() { wg.Done() })
+	cron.Start()
+	defer cron.Stop()
+
+	select {
+	case <-time.After(OneSecond * 2):
+		t.Error("expected job fires 2 times")
+	case <-wait(wg):
+	}
+}
+
+// Test that the cron is run in the given time zone (as opposed to local).
+func TestNonLocalTimezone(t *testing.T) {
+	wg := &sync.WaitGroup{}
+	wg.Add(2)
+
+	loc, err := time.LoadLocation("Atlantic/Cape_Verde")
+	if err != nil {
+		fmt.Printf("Failed to load time zone Atlantic/Cape_Verde: %+v", err)
+		t.Fail()
+	}
+
+	now := time.Now().In(loc)
+	// FIX: Issue #205
+	// This calculation doesn't work in seconds 58 or 59.
+	// Take the easy way out and sleep.
+	if now.Second() >= 58 {
+		time.Sleep(2 * time.Second)
+		now = time.Now().In(loc)
+	}
+	spec := fmt.Sprintf("%d,%d %d %d %d %d ?",
+		now.Second()+1, now.Second()+2, now.Minute(), now.Hour(), now.Day(), now.Month())
+
+	cron := New(WithLocation(loc), WithParser(secondParser))
+	cron.AddFunc(spec, func() { wg.Done() })
+	cron.Start()
+	defer cron.Stop()
+
+	select {
+	case <-time.After(OneSecond * 2):
+		t.Error("expected job fires 2 times")
+	case <-wait(wg):
+	}
+}
+
+// Test that calling stop before start silently returns without
+// blocking the stop channel.
+func TestStopWithoutStart(t *testing.T) {
+	cron := New()
+	cron.Stop()
+}
+
+type testJob struct {
+	wg   *sync.WaitGroup
+	name string
+}
+
+func (t testJob) Run() {
+	t.wg.Done()
+}
+
+// Test that adding an invalid job spec returns an error
+func TestInvalidJobSpec(t *testing.T) {
+	cron := New()
+	_, err := cron.AddJob("this will not parse", nil)
+	if err == nil {
+		t.Errorf("expected an error with invalid spec, got nil")
+	}
+}
+
+// Test blocking run method behaves as Start()
+func TestBlockingRun(t *testing.T) {
+	wg := &sync.WaitGroup{}
+	wg.Add(1)
+
+	cron := newWithSeconds()
+	cron.AddFunc("* * * * * ?", func() { wg.Done() })
+
+	var unblockChan = make(chan struct{})
+
+	go func() {
+		cron.Run()
+		close(unblockChan)
+	}()
+	defer cron.Stop()
+
+	select {
+	case <-time.After(OneSecond):
+		t.Error("expected job fires")
+	case <-unblockChan:
+		t.Error("expected that Run() blocks")
+	case <-wait(wg):
+	}
+}
+
+// Test that double-running is a no-op
+func TestStartNoop(t *testing.T) {
+	var tickChan = make(chan struct{}, 2)
+
+	cron := newWithSeconds()
+	cron.AddFunc("* * * * * ?", func() {
+		tickChan <- struct{}{}
+	})
+
+	cron.Start()
+	defer cron.Stop()
+
+	// Wait for the first firing to ensure the runner is going
+	<-tickChan
+
+	cron.Start()
+
+	<-tickChan
+
+	// Fail if this job fires again in a short period, indicating a double-run
+	select {
+	case <-time.After(time.Millisecond):
+	case <-tickChan:
+		t.Error("expected job fires exactly twice")
+	}
+}
+
+// Simple test using Runnables.
+func TestJob(t *testing.T) {
+	wg := &sync.WaitGroup{}
+	wg.Add(1)
+
+	cron := newWithSeconds()
+	cron.AddJob("0 0 0 30 Feb ?", testJob{wg, "job0"})
+	cron.AddJob("0 0 0 1 1 ?", testJob{wg, "job1"})
+	job2, _ := cron.AddJob("* * * * * ?", testJob{wg, "job2"})
+	cron.AddJob("1 0 0 1 1 ?", testJob{wg, "job3"})
+	cron.Schedule(Every(5*time.Second+5*time.Nanosecond), testJob{wg, "job4"})
+	job5 := cron.Schedule(Every(5*time.Minute), testJob{wg, "job5"})
+
+	// Test getting an Entry pre-Start.
+	if actualName := cron.Entry(job2).Job.(testJob).name; actualName != "job2" {
+		t.Error("wrong job retrieved:", actualName)
+	}
+	if actualName := cron.Entry(job5).Job.(testJob).name; actualName != "job5" {
+		t.Error("wrong job retrieved:", actualName)
+	}
+
+	cron.Start()
+	defer cron.Stop()
+
+	select {
+	case <-time.After(OneSecond):
+		t.FailNow()
+	case <-wait(wg):
+	}
+
+	// Ensure the entries are in the right order.
+	expecteds := []string{"job2", "job4", "job5", "job1", "job3", "job0"}
+
+	var actuals []string
+	for _, entry := range cron.Entries() {
+		actuals = append(actuals, entry.Job.(testJob).name)
+	}
+
+	for i, expected := range expecteds {
+		if actuals[i] != expected {
+			t.Fatalf("Jobs not in the right order.  (expected) %s != %s (actual)", expecteds, actuals)
+		}
+	}
+
+	// Test getting Entries.
+	if actualName := cron.Entry(job2).Job.(testJob).name; actualName != "job2" {
+		t.Error("wrong job retrieved:", actualName)
+	}
+	if actualName := cron.Entry(job5).Job.(testJob).name; actualName != "job5" {
+		t.Error("wrong job retrieved:", actualName)
+	}
+}
+
+// Issue #206
+// Ensure that the next run of a job after removing an entry is accurate.
+func TestScheduleAfterRemoval(t *testing.T) {
+	var wg1 sync.WaitGroup
+	var wg2 sync.WaitGroup
+	wg1.Add(1)
+	wg2.Add(1)
+
+	// The first time this job is run, set a timer and remove the other job
+	// 750ms later. Correct behavior would be to still run the job again in
+	// 250ms, but the bug would cause it to run instead 1s later.
+
+	var calls int
+	var mu sync.Mutex
+
+	cron := newWithSeconds()
+	hourJob := cron.Schedule(Every(time.Hour), FuncJob(func() {}))
+	cron.Schedule(Every(time.Second), FuncJob(func() {
+		mu.Lock()
+		defer mu.Unlock()
+		switch calls {
+		case 0:
+			wg1.Done()
+			calls++
+		case 1:
+			time.Sleep(750 * time.Millisecond)
+			cron.Remove(hourJob)
+			calls++
+		case 2:
+			calls++
+			wg2.Done()
+		case 3:
+			panic("unexpected 3rd call")
+		}
+	}))
+
+	cron.Start()
+	defer cron.Stop()
+
+	// the first run might be any length of time 0 - 1s, since the schedule
+	// rounds to the second. wait for the first run to true up.
+	wg1.Wait()
+
+	select {
+	case <-time.After(2 * OneSecond):
+		t.Error("expected job fires 2 times")
+	case <-wait(&wg2):
+	}
+}
+
+type ZeroSchedule struct{}
+
+func (*ZeroSchedule) Next(time.Time) time.Time {
+	return time.Time{}
+}
+
+// Tests that job without time does not run
+func TestJobWithZeroTimeDoesNotRun(t *testing.T) {
+	cron := newWithSeconds()
+	var calls int64
+	cron.AddFunc("* * * * * *", func() { atomic.AddInt64(&calls, 1) })
+	cron.Schedule(new(ZeroSchedule), FuncJob(func() { t.Error("expected zero task will not run") }))
+	cron.Start()
+	defer cron.Stop()
+	<-time.After(OneSecond)
+	if atomic.LoadInt64(&calls) != 1 {
+		t.Errorf("called %d times, expected 1\n", calls)
+	}
+}
+
+func TestStopAndWait(t *testing.T) {
+	t.Run("nothing running, returns immediately", func(*testing.T) {
+		cron := newWithSeconds()
+		cron.Start()
+		ctx := cron.Stop()
+		select {
+		case <-ctx.Done():
+		case <-time.After(time.Millisecond):
+			t.Error("context was not done immediately")
+		}
+	})
+
+	t.Run("repeated calls to Stop", func(*testing.T) {
+		cron := newWithSeconds()
+		cron.Start()
+		_ = cron.Stop()
+		time.Sleep(time.Millisecond)
+		ctx := cron.Stop()
+		select {
+		case <-ctx.Done():
+		case <-time.After(time.Millisecond):
+			t.Error("context was not done immediately")
+		}
+	})
+
+	t.Run("a couple fast jobs added, still returns immediately", func(*testing.T) {
+		cron := newWithSeconds()
+		cron.AddFunc("* * * * * *", func() {})
+		cron.Start()
+		cron.AddFunc("* * * * * *", func() {})
+		cron.AddFunc("* * * * * *", func() {})
+		cron.AddFunc("* * * * * *", func() {})
+		time.Sleep(time.Second)
+		ctx := cron.Stop()
+		select {
+		case <-ctx.Done():
+		case <-time.After(time.Millisecond):
+			t.Error("context was not done immediately")
+		}
+	})
+
+	t.Run("a couple fast jobs and a slow job added, waits for slow job", func(*testing.T) {
+		cron := newWithSeconds()
+		cron.AddFunc("* * * * * *", func() {})
+		cron.Start()
+		cron.AddFunc("* * * * * *", func() { time.Sleep(2 * time.Second) })
+		cron.AddFunc("* * * * * *", func() {})
+		time.Sleep(time.Second)
+
+		ctx := cron.Stop()
+
+		// Verify that it is not done for at least 750ms
+		select {
+		case <-ctx.Done():
+			t.Error("context was done too quickly immediately")
+		case <-time.After(750 * time.Millisecond):
+			// expected, because the job sleeping for 1 second is still running
+		}
+
+		// Verify that it IS done in the next 500ms (giving 250ms buffer)
+		select {
+		case <-ctx.Done():
+			// expected
+		case <-time.After(1500 * time.Millisecond):
+			t.Error("context not done after job should have completed")
+		}
+	})
+
+	t.Run("repeated calls to stop, waiting for completion and after", func(*testing.T) {
+		cron := newWithSeconds()
+		cron.AddFunc("* * * * * *", func() {})
+		cron.AddFunc("* * * * * *", func() { time.Sleep(2 * time.Second) })
+		cron.Start()
+		cron.AddFunc("* * * * * *", func() {})
+		time.Sleep(time.Second)
+		ctx := cron.Stop()
+		ctx2 := cron.Stop()
+
+		// Verify that it is not done for at least 1500ms
+		select {
+		case <-ctx.Done():
+			t.Error("context was done too quickly immediately")
+		case <-ctx2.Done():
+			t.Error("context2 was done too quickly immediately")
+		case <-time.After(1500 * time.Millisecond):
+			// expected, because the job sleeping for 2 seconds is still running
+		}
+
+		// Verify that it IS done in the next 1s (giving 500ms buffer)
+		select {
+		case <-ctx.Done():
+			// expected
+		case <-time.After(time.Second):
+			t.Error("context not done after job should have completed")
+		}
+
+		// Verify that ctx2 is also done.
+		select {
+		case <-ctx2.Done():
+			// expected
+		case <-time.After(time.Millisecond):
+			t.Error("context2 not done even though context1 is")
+		}
+
+		// Verify that a new context retrieved from stop is immediately done.
+		ctx3 := cron.Stop()
+		select {
+		case <-ctx3.Done():
+			// expected
+		case <-time.After(time.Millisecond):
+			t.Error("context not done even when cron Stop is completed")
+		}
+	})
+}
+
+func TestMultiThreadedStartAndStop(t *testing.T) {
+	cron := New()
+	go cron.Run()
+	time.Sleep(2 * time.Millisecond)
+	cron.Stop()
+}
+
+func wait(wg *sync.WaitGroup) chan bool {
+	ch := make(chan bool)
+	go func() {
+		wg.Wait()
+		ch <- true
+	}()
+	return ch
+}
+
+func stop(cron *Cron) chan bool {
+	ch := make(chan bool)
+	go func() {
+		cron.Stop()
+		ch <- true
+	}()
+	return ch
+}
+
+// newWithSeconds returns a Cron with the seconds field enabled.
+func newWithSeconds() *Cron {
+	return New(WithParser(secondParser), WithChain())
+}
@@ -0,0 +1,86 @@
+package cron
+
+import (
+	"io"
+	"log"
+	"os"
+	"strings"
+	"time"
+)
+
+// DefaultLogger is used by Cron if none is specified.
+var DefaultLogger = PrintfLogger(log.New(os.Stdout, "cron: ", log.LstdFlags))
+
+// DiscardLogger can be used by callers to discard all log messages.
+var DiscardLogger = PrintfLogger(log.New(io.Discard, "", 0))
+
+// Logger is the interface used in this package for logging, so that any backend
+// can be plugged in. It is a subset of the github.com/go-logr/logr interface.
+type Logger interface {
+	// Info logs routine messages about cron's operation.
+	Info(msg string, keysAndValues ...interface{})
+	// Error logs an error condition.
+	Error(err error, msg string, keysAndValues ...interface{})
+}
+
+// PrintfLogger wraps a Printf-based logger (such as the standard library "log")
+// into an implementation of the Logger interface which logs errors only.
+func PrintfLogger(l interface{ Printf(string, ...interface{}) }) Logger {
+	return printfLogger{l, false}
+}
+
+// VerbosePrintfLogger wraps a Printf-based logger (such as the standard library
+// "log") into an implementation of the Logger interface which logs everything.
+func VerbosePrintfLogger(l interface{ Printf(string, ...interface{}) }) Logger {
+	return printfLogger{l, true}
+}
+
+type printfLogger struct {
+	logger  interface{ Printf(string, ...interface{}) }
+	logInfo bool
+}
+
+func (pl printfLogger) Info(msg string, keysAndValues ...interface{}) {
+	if pl.logInfo {
+		keysAndValues = formatTimes(keysAndValues)
+		pl.logger.Printf(
+			formatString(len(keysAndValues)),
+			append([]interface{}{msg}, keysAndValues...)...)
+	}
+}
+
+func (pl printfLogger) Error(err error, msg string, keysAndValues ...interface{}) {
+	keysAndValues = formatTimes(keysAndValues)
+	pl.logger.Printf(
+		formatString(len(keysAndValues)+2),
+		append([]interface{}{msg, "error", err}, keysAndValues...)...)
+}
+
+// formatString returns a logfmt-like format string for the number of
+// key/values.
+func formatString(numKeysAndValues int) string {
+	var sb strings.Builder
+	sb.WriteString("%s")
+	if numKeysAndValues > 0 {
+		sb.WriteString(", ")
+	}
+	for i := 0; i < numKeysAndValues/2; i++ {
+		if i > 0 {
+			sb.WriteString(", ")
+		}
+		sb.WriteString("%v=%v")
+	}
+	return sb.String()
+}
+
+// formatTimes formats any time.Time values as RFC3339.
+func formatTimes(keysAndValues []interface{}) []interface{} {
+	var formattedArgs []interface{}
+	for _, arg := range keysAndValues {
+		if t, ok := arg.(time.Time); ok {
+			arg = t.Format(time.RFC3339)
+		}
+		formattedArgs = append(formattedArgs, arg)
+	}
+	return formattedArgs
+}
@@ -0,0 +1,45 @@
+package cron
+
+import (
+	"time"
+)
+
+// Option represents a modification to the default behavior of a Cron.
+type Option func(*Cron)
+
+// WithLocation overrides the timezone of the cron instance.
+func WithLocation(loc *time.Location) Option {
+	return func(c *Cron) {
+		c.location = loc
+	}
+}
+
+// WithSeconds overrides the parser used for interpreting job schedules to
+// include a seconds field as the first one.
+func WithSeconds() Option {
+	return WithParser(NewParser(
+		Second | Minute | Hour | Dom | Month | Dow | Descriptor,
+	))
+}
+
+// WithParser overrides the parser used for interpreting job schedules.
+func WithParser(p ScheduleParser) Option {
+	return func(c *Cron) {
+		c.parser = p
+	}
+}
+
+// WithChain specifies Job wrappers to apply to all jobs added to this cron.
+// Refer to the Chain* functions in this package for provided wrappers.
+func WithChain(wrappers ...JobWrapper) Option {
+	return func(c *Cron) {
+		c.chain = NewChain(wrappers...)
+	}
+}
+
+// WithLogger uses the provided logger.
+func WithLogger(logger Logger) Option {
+	return func(c *Cron) {
+		c.logger = logger
+	}
+}
@@ -0,0 +1,43 @@
+//nolint:all
+package cron
+
+import (
+	"log"
+	"strings"
+	"testing"
+	"time"
+)
+
+func TestWithLocation(t *testing.T) {
+	c := New(WithLocation(time.UTC))
+	if c.location != time.UTC {
+		t.Errorf("expected UTC, got %v", c.location)
+	}
+}
+
+func TestWithParser(t *testing.T) {
+	var parser = NewParser(Dow)
+	c := New(WithParser(parser))
+	if c.parser != parser {
+		t.Error("expected provided parser")
+	}
+}
+
+func TestWithVerboseLogger(t *testing.T) {
+	var buf syncWriter
+	var logger = log.New(&buf, "", log.LstdFlags)
+	c := New(WithLogger(VerbosePrintfLogger(logger)))
+	if c.logger.(printfLogger).logger != logger {
+		t.Error("expected provided logger")
+	}
+
+	c.AddFunc("@every 1s", func() {})
+	c.Start()
+	time.Sleep(OneSecond)
+	c.Stop()
+	out := buf.String()
+	if !strings.Contains(out, "schedule,") ||
+		!strings.Contains(out, "run,") {
+		t.Error("expected to see some actions, got:", out)
+	}
+}
@@ -0,0 +1,435 @@
+package cron
+
+import (
+	"math"
+	"strconv"
+	"strings"
+	"time"
+
+	"github.com/pkg/errors"
+)
+
+// Configuration options for creating a parser. Most options specify which
+// fields should be included, while others enable features. If a field is not
+// included the parser will assume a default value. These options do not change
+// the order fields are parse in.
+type ParseOption int
+
+const (
+	Second         ParseOption = 1 << iota // Seconds field, default 0
+	SecondOptional                         // Optional seconds field, default 0
+	Minute                                 // Minutes field, default 0
+	Hour                                   // Hours field, default 0
+	Dom                                    // Day of month field, default *
+	Month                                  // Month field, default *
+	Dow                                    // Day of week field, default *
+	DowOptional                            // Optional day of week field, default *
+	Descriptor                             // Allow descriptors such as @monthly, @weekly, etc.
+)
+
+var places = []ParseOption{
+	Second,
+	Minute,
+	Hour,
+	Dom,
+	Month,
+	Dow,
+}
+
+var defaults = []string{
+	"0",
+	"0",
+	"0",
+	"*",
+	"*",
+	"*",
+}
+
+// A custom Parser that can be configured.
+type Parser struct {
+	options ParseOption
+}
+
+// NewParser creates a Parser with custom options.
+//
+// It panics if more than one Optional is given, since it would be impossible to
+// correctly infer which optional is provided or missing in general.
+//
+// Examples
+//
+//	// Standard parser without descriptors
+//	specParser := NewParser(Minute | Hour | Dom | Month | Dow)
+//	sched, err := specParser.Parse("0 0 15 */3 *")
+//
+//	// Same as above, just excludes time fields
+//	specParser := NewParser(Dom | Month | Dow)
+//	sched, err := specParser.Parse("15 */3 *")
+//
+//	// Same as above, just makes Dow optional
+//	specParser := NewParser(Dom | Month | DowOptional)
+//	sched, err := specParser.Parse("15 */3")
+func NewParser(options ParseOption) Parser {
+	optionals := 0
+	if options&DowOptional > 0 {
+		optionals++
+	}
+	if options&SecondOptional > 0 {
+		optionals++
+	}
+	if optionals > 1 {
+		panic("multiple optionals may not be configured")
+	}
+	return Parser{options}
+}
+
+// Parse returns a new crontab schedule representing the given spec.
+// It returns a descriptive error if the spec is not valid.
+// It accepts crontab specs and features configured by NewParser.
+func (p Parser) Parse(spec string) (Schedule, error) {
+	if len(spec) == 0 {
+		return nil, errors.New("empty spec string")
+	}
+
+	// Extract timezone if present
+	var loc = time.Local
+	if strings.HasPrefix(spec, "TZ=") || strings.HasPrefix(spec, "CRON_TZ=") {
+		var err error
+		i := strings.Index(spec, " ")
+		eq := strings.Index(spec, "=")
+		if loc, err = time.LoadLocation(spec[eq+1 : i]); err != nil {
+			return nil, errors.Wrap(err, "provided bad location")
+		}
+		spec = strings.TrimSpace(spec[i:])
+	}
+
+	// Handle named schedules (descriptors), if configured
+	if strings.HasPrefix(spec, "@") {
+		if p.options&Descriptor == 0 {
+			return nil, errors.New("descriptors not enabled")
+		}
+		return parseDescriptor(spec, loc)
+	}
+
+	// Split on whitespace.
+	fields := strings.Fields(spec)
+
+	// Validate & fill in any omitted or optional fields
+	var err error
+	fields, err = normalizeFields(fields, p.options)
+	if err != nil {
+		return nil, err
+	}
+
+	field := func(field string, r bounds) uint64 {
+		if err != nil {
+			return 0
+		}
+		var bits uint64
+		bits, err = getField(field, r)
+		return bits
+	}
+
+	var (
+		second     = field(fields[0], seconds)
+		minute     = field(fields[1], minutes)
+		hour       = field(fields[2], hours)
+		dayofmonth = field(fields[3], dom)
+		month      = field(fields[4], months)
+		dayofweek  = field(fields[5], dow)
+	)
+	if err != nil {
+		return nil, err
+	}
+
+	return &SpecSchedule{
+		Second:   second,
+		Minute:   minute,
+		Hour:     hour,
+		Dom:      dayofmonth,
+		Month:    month,
+		Dow:      dayofweek,
+		Location: loc,
+	}, nil
+}
+
+// normalizeFields takes a subset set of the time fields and returns the full set
+// with defaults (zeroes) populated for unset fields.
+//
+// As part of performing this function, it also validates that the provided
+// fields are compatible with the configured options.
+func normalizeFields(fields []string, options ParseOption) ([]string, error) {
+	// Validate optionals & add their field to options
+	optionals := 0
+	if options&SecondOptional > 0 {
+		options |= Second
+		optionals++
+	}
+	if options&DowOptional > 0 {
+		options |= Dow
+		optionals++
+	}
+	if optionals > 1 {
+		return nil, errors.New("multiple optionals may not be configured")
+	}
+
+	// Figure out how many fields we need
+	max := 0
+	for _, place := range places {
+		if options&place > 0 {
+			max++
+		}
+	}
+	min := max - optionals
+
+	// Validate number of fields
+	if count := len(fields); count < min || count > max {
+		if min == max {
+			return nil, errors.New("incorrect number of fields")
+		}
+		return nil, errors.New("incorrect number of fields, expected " + strconv.Itoa(min) + "-" + strconv.Itoa(max))
+	}
+
+	// Populate the optional field if not provided
+	if min < max && len(fields) == min {
+		switch {
+		case options&DowOptional > 0:
+			fields = append(fields, defaults[5]) // TODO: improve access to default
+		case options&SecondOptional > 0:
+			fields = append([]string{defaults[0]}, fields...)
+		default:
+			return nil, errors.New("unexpected optional field")
+		}
+	}
+
+	// Populate all fields not part of options with their defaults
+	n := 0
+	expandedFields := make([]string, len(places))
+	copy(expandedFields, defaults)
+	for i, place := range places {
+		if options&place > 0 {
+			expandedFields[i] = fields[n]
+			n++
+		}
+	}
+	return expandedFields, nil
+}
+
+var standardParser = NewParser(
+	Minute | Hour | Dom | Month | Dow | Descriptor,
+)
+
+// ParseStandard returns a new crontab schedule representing the given
+// standardSpec (https://en.wikipedia.org/wiki/Cron). It requires 5 entries
+// representing: minute, hour, day of month, month and day of week, in that
+// order. It returns a descriptive error if the spec is not valid.
+//
+// It accepts
+//   - Standard crontab specs, e.g. "* * * * ?"
+//   - Descriptors, e.g. "@midnight", "@every 1h30m"
+func ParseStandard(standardSpec string) (Schedule, error) {
+	return standardParser.Parse(standardSpec)
+}
+
+// getField returns an Int with the bits set representing all of the times that
+// the field represents or error parsing field value.  A "field" is a comma-separated
+// list of "ranges".
+func getField(field string, r bounds) (uint64, error) {
+	var bits uint64
+	ranges := strings.FieldsFunc(field, func(r rune) bool { return r == ',' })
+	for _, expr := range ranges {
+		bit, err := getRange(expr, r)
+		if err != nil {
+			return bits, err
+		}
+		bits |= bit
+	}
+	return bits, nil
+}
+
+// getRange returns the bits indicated by the given expression:
+//
+//	number | number "-" number [ "/" number ]
+//
+// or error parsing range.
+func getRange(expr string, r bounds) (uint64, error) {
+	var (
+		start, end, step uint
+		rangeAndStep     = strings.Split(expr, "/")
+		lowAndHigh       = strings.Split(rangeAndStep[0], "-")
+		singleDigit      = len(lowAndHigh) == 1
+		err              error
+	)
+
+	var extra uint64
+	if lowAndHigh[0] == "*" || lowAndHigh[0] == "?" {
+		start = r.min
+		end = r.max
+		extra = starBit
+	} else {
+		start, err = parseIntOrName(lowAndHigh[0], r.names)
+		if err != nil {
+			return 0, err
+		}
+		switch len(lowAndHigh) {
+		case 1:
+			end = start
+		case 2:
+			end, err = parseIntOrName(lowAndHigh[1], r.names)
+			if err != nil {
+				return 0, err
+			}
+		default:
+			return 0, errors.New("too many hyphens: " + expr)
+		}
+	}
+
+	switch len(rangeAndStep) {
+	case 1:
+		step = 1
+	case 2:
+		step, err = mustParseInt(rangeAndStep[1])
+		if err != nil {
+			return 0, err
+		}
+
+		// Special handling: "N/step" means "N-max/step".
+		if singleDigit {
+			end = r.max
+		}
+		if step > 1 {
+			extra = 0
+		}
+	default:
+		return 0, errors.New("too many slashes: " + expr)
+	}
+
+	if start < r.min {
+		return 0, errors.New("beginning of range below minimum: " + expr)
+	}
+	if end > r.max {
+		return 0, errors.New("end of range above maximum: " + expr)
+	}
+	if start > end {
+		return 0, errors.New("beginning of range after end: " + expr)
+	}
+	if step == 0 {
+		return 0, errors.New("step cannot be zero: " + expr)
+	}
+
+	return getBits(start, end, step) | extra, nil
+}
+
+// parseIntOrName returns the (possibly-named) integer contained in expr.
+func parseIntOrName(expr string, names map[string]uint) (uint, error) {
+	if names != nil {
+		if namedInt, ok := names[strings.ToLower(expr)]; ok {
+			return namedInt, nil
+		}
+	}
+	return mustParseInt(expr)
+}
+
+// mustParseInt parses the given expression as an int or returns an error.
+func mustParseInt(expr string) (uint, error) {
+	num, err := strconv.Atoi(expr)
+	if err != nil {
+		return 0, errors.Wrap(err, "failed to parse number")
+	}
+	if num < 0 {
+		return 0, errors.New("number must be positive")
+	}
+
+	return uint(num), nil
+}
+
+// getBits sets all bits in the range [min, max], modulo the given step size.
+func getBits(min, max, step uint) uint64 {
+	var bits uint64
+
+	// If step is 1, use shifts.
+	if step == 1 {
+		return ^(math.MaxUint64 << (max + 1)) & (math.MaxUint64 << min)
+	}
+
+	// Else, use a simple loop.
+	for i := min; i <= max; i += step {
+		bits |= 1 << i
+	}
+	return bits
+}
+
+// all returns all bits within the given bounds.
+func all(r bounds) uint64 {
+	return getBits(r.min, r.max, 1) | starBit
+}
+
+// parseDescriptor returns a predefined schedule for the expression, or error if none matches.
+func parseDescriptor(descriptor string, loc *time.Location) (Schedule, error) {
+	switch descriptor {
+	case "@yearly", "@annually":
+		return &SpecSchedule{
+			Second:   1 << seconds.min,
+			Minute:   1 << minutes.min,
+			Hour:     1 << hours.min,
+			Dom:      1 << dom.min,
+			Month:    1 << months.min,
+			Dow:      all(dow),
+			Location: loc,
+		}, nil
+
+	case "@monthly":
+		return &SpecSchedule{
+			Second:   1 << seconds.min,
+			Minute:   1 << minutes.min,
+			Hour:     1 << hours.min,
+			Dom:      1 << dom.min,
+			Month:    all(months),
+			Dow:      all(dow),
+			Location: loc,
+		}, nil
+
+	case "@weekly":
+		return &SpecSchedule{
+			Second:   1 << seconds.min,
+			Minute:   1 << minutes.min,
+			Hour:     1 << hours.min,
+			Dom:      all(dom),
+			Month:    all(months),
+			Dow:      1 << dow.min,
+			Location: loc,
+		}, nil
+
+	case "@daily", "@midnight":
+		return &SpecSchedule{
+			Second:   1 << seconds.min,
+			Minute:   1 << minutes.min,
+			Hour:     1 << hours.min,
+			Dom:      all(dom),
+			Month:    all(months),
+			Dow:      all(dow),
+			Location: loc,
+		}, nil
+
+	case "@hourly":
+		return &SpecSchedule{
+			Second:   1 << seconds.min,
+			Minute:   1 << minutes.min,
+			Hour:     all(hours),
+			Dom:      all(dom),
+			Month:    all(months),
+			Dow:      all(dow),
+			Location: loc,
+		}, nil
+	}
+
+	const every = "@every "
+	if strings.HasPrefix(descriptor, every) {
+		duration, err := time.ParseDuration(descriptor[len(every):])
+		if err != nil {
+			return nil, errors.Wrap(err, "failed to parse duration")
+		}
+		return Every(duration), nil
+	}
+
+	return nil, errors.New("unrecognized descriptor: " + descriptor)
+}
@@ -0,0 +1,384 @@
+//nolint:all
+package cron
+
+import (
+	"reflect"
+	"strings"
+	"testing"
+	"time"
+)
+
+var secondParser = NewParser(Second | Minute | Hour | Dom | Month | DowOptional | Descriptor)
+
+func TestRange(t *testing.T) {
+	zero := uint64(0)
+	ranges := []struct {
+		expr     string
+		min, max uint
+		expected uint64
+		err      string
+	}{
+		{"5", 0, 7, 1 << 5, ""},
+		{"0", 0, 7, 1 << 0, ""},
+		{"7", 0, 7, 1 << 7, ""},
+
+		{"5-5", 0, 7, 1 << 5, ""},
+		{"5-6", 0, 7, 1<<5 | 1<<6, ""},
+		{"5-7", 0, 7, 1<<5 | 1<<6 | 1<<7, ""},
+
+		{"5-6/2", 0, 7, 1 << 5, ""},
+		{"5-7/2", 0, 7, 1<<5 | 1<<7, ""},
+		{"5-7/1", 0, 7, 1<<5 | 1<<6 | 1<<7, ""},
+
+		{"*", 1, 3, 1<<1 | 1<<2 | 1<<3 | starBit, ""},
+		{"*/2", 1, 3, 1<<1 | 1<<3, ""},
+
+		{"5--5", 0, 0, zero, "too many hyphens"},
+		{"jan-x", 0, 0, zero, `failed to parse number: strconv.Atoi: parsing "jan": invalid syntax`},
+		{"2-x", 1, 5, zero, `failed to parse number: strconv.Atoi: parsing "x": invalid syntax`},
+		{"*/-12", 0, 0, zero, "number must be positive"},
+		{"*//2", 0, 0, zero, "too many slashes"},
+		{"1", 3, 5, zero, "below minimum"},
+		{"6", 3, 5, zero, "above maximum"},
+		{"5-3", 3, 5, zero, "beginning of range after end: 5-3"},
+		{"*/0", 0, 0, zero, "step cannot be zero: */0"},
+	}
+
+	for _, c := range ranges {
+		actual, err := getRange(c.expr, bounds{c.min, c.max, nil})
+		if len(c.err) != 0 && (err == nil || !strings.Contains(err.Error(), c.err)) {
+			t.Errorf("%s => expected %v, got %v", c.expr, c.err, err)
+		}
+		if len(c.err) == 0 && err != nil {
+			t.Errorf("%s => unexpected error %v", c.expr, err)
+		}
+		if actual != c.expected {
+			t.Errorf("%s => expected %d, got %d", c.expr, c.expected, actual)
+		}
+	}
+}
+
+func TestField(t *testing.T) {
+	fields := []struct {
+		expr     string
+		min, max uint
+		expected uint64
+	}{
+		{"5", 1, 7, 1 << 5},
+		{"5,6", 1, 7, 1<<5 | 1<<6},
+		{"5,6,7", 1, 7, 1<<5 | 1<<6 | 1<<7},
+		{"1,5-7/2,3", 1, 7, 1<<1 | 1<<5 | 1<<7 | 1<<3},
+	}
+
+	for _, c := range fields {
+		actual, _ := getField(c.expr, bounds{c.min, c.max, nil})
+		if actual != c.expected {
+			t.Errorf("%s => expected %d, got %d", c.expr, c.expected, actual)
+		}
+	}
+}
+
+func TestAll(t *testing.T) {
+	allBits := []struct {
+		r        bounds
+		expected uint64
+	}{
+		{minutes, 0xfffffffffffffff}, // 0-59: 60 ones
+		{hours, 0xffffff},            // 0-23: 24 ones
+		{dom, 0xfffffffe},            // 1-31: 31 ones, 1 zero
+		{months, 0x1ffe},             // 1-12: 12 ones, 1 zero
+		{dow, 0x7f},                  // 0-6: 7 ones
+	}
+
+	for _, c := range allBits {
+		actual := all(c.r) // all() adds the starBit, so compensate for that..
+		if c.expected|starBit != actual {
+			t.Errorf("%d-%d/%d => expected %b, got %b",
+				c.r.min, c.r.max, 1, c.expected|starBit, actual)
+		}
+	}
+}
+
+func TestBits(t *testing.T) {
+	bits := []struct {
+		min, max, step uint
+		expected       uint64
+	}{
+		{0, 0, 1, 0x1},
+		{1, 1, 1, 0x2},
+		{1, 5, 2, 0x2a}, // 101010
+		{1, 4, 2, 0xa},  // 1010
+	}
+
+	for _, c := range bits {
+		actual := getBits(c.min, c.max, c.step)
+		if c.expected != actual {
+			t.Errorf("%d-%d/%d => expected %b, got %b",
+				c.min, c.max, c.step, c.expected, actual)
+		}
+	}
+}
+
+func TestParseScheduleErrors(t *testing.T) {
+	var tests = []struct{ expr, err string }{
+		{"* 5 j * * *", `failed to parse number: strconv.Atoi: parsing "j": invalid syntax`},
+		{"@every Xm", "failed to parse duration"},
+		{"@unrecognized", "unrecognized descriptor"},
+		{"* * * *", "incorrect number of fields, expected 5-6"},
+		{"", "empty spec string"},
+	}
+	for _, c := range tests {
+		actual, err := secondParser.Parse(c.expr)
+		if err == nil || !strings.Contains(err.Error(), c.err) {
+			t.Errorf("%s => expected %v, got %v", c.expr, c.err, err)
+		}
+		if actual != nil {
+			t.Errorf("expected nil schedule on error, got %v", actual)
+		}
+	}
+}
+
+func TestParseSchedule(t *testing.T) {
+	tokyo, _ := time.LoadLocation("Asia/Tokyo")
+	entries := []struct {
+		parser   Parser
+		expr     string
+		expected Schedule
+	}{
+		{secondParser, "0 5 * * * *", every5min(time.Local)},
+		{standardParser, "5 * * * *", every5min(time.Local)},
+		{secondParser, "CRON_TZ=UTC  0 5 * * * *", every5min(time.UTC)},
+		{standardParser, "CRON_TZ=UTC  5 * * * *", every5min(time.UTC)},
+		{secondParser, "CRON_TZ=Asia/Tokyo 0 5 * * * *", every5min(tokyo)},
+		{secondParser, "@every 5m", ConstantDelaySchedule{5 * time.Minute}},
+		{secondParser, "@midnight", midnight(time.Local)},
+		{secondParser, "TZ=UTC  @midnight", midnight(time.UTC)},
+		{secondParser, "TZ=Asia/Tokyo @midnight", midnight(tokyo)},
+		{secondParser, "@yearly", annual(time.Local)},
+		{secondParser, "@annually", annual(time.Local)},
+		{
+			parser: secondParser,
+			expr:   "* 5 * * * *",
+			expected: &SpecSchedule{
+				Second:   all(seconds),
+				Minute:   1 << 5,
+				Hour:     all(hours),
+				Dom:      all(dom),
+				Month:    all(months),
+				Dow:      all(dow),
+				Location: time.Local,
+			},
+		},
+	}
+
+	for _, c := range entries {
+		actual, err := c.parser.Parse(c.expr)
+		if err != nil {
+			t.Errorf("%s => unexpected error %v", c.expr, err)
+		}
+		if !reflect.DeepEqual(actual, c.expected) {
+			t.Errorf("%s => expected %b, got %b", c.expr, c.expected, actual)
+		}
+	}
+}
+
+func TestOptionalSecondSchedule(t *testing.T) {
+	parser := NewParser(SecondOptional | Minute | Hour | Dom | Month | Dow | Descriptor)
+	entries := []struct {
+		expr     string
+		expected Schedule
+	}{
+		{"0 5 * * * *", every5min(time.Local)},
+		{"5 5 * * * *", every5min5s(time.Local)},
+		{"5 * * * *", every5min(time.Local)},
+	}
+
+	for _, c := range entries {
+		actual, err := parser.Parse(c.expr)
+		if err != nil {
+			t.Errorf("%s => unexpected error %v", c.expr, err)
+		}
+		if !reflect.DeepEqual(actual, c.expected) {
+			t.Errorf("%s => expected %b, got %b", c.expr, c.expected, actual)
+		}
+	}
+}
+
+func TestNormalizeFields(t *testing.T) {
+	tests := []struct {
+		name     string
+		input    []string
+		options  ParseOption
+		expected []string
+	}{
+		{
+			"AllFields_NoOptional",
+			[]string{"0", "5", "*", "*", "*", "*"},
+			Second | Minute | Hour | Dom | Month | Dow | Descriptor,
+			[]string{"0", "5", "*", "*", "*", "*"},
+		},
+		{
+			"AllFields_SecondOptional_Provided",
+			[]string{"0", "5", "*", "*", "*", "*"},
+			SecondOptional | Minute | Hour | Dom | Month | Dow | Descriptor,
+			[]string{"0", "5", "*", "*", "*", "*"},
+		},
+		{
+			"AllFields_SecondOptional_NotProvided",
+			[]string{"5", "*", "*", "*", "*"},
+			SecondOptional | Minute | Hour | Dom | Month | Dow | Descriptor,
+			[]string{"0", "5", "*", "*", "*", "*"},
+		},
+		{
+			"SubsetFields_NoOptional",
+			[]string{"5", "15", "*"},
+			Hour | Dom | Month,
+			[]string{"0", "0", "5", "15", "*", "*"},
+		},
+		{
+			"SubsetFields_DowOptional_Provided",
+			[]string{"5", "15", "*", "4"},
+			Hour | Dom | Month | DowOptional,
+			[]string{"0", "0", "5", "15", "*", "4"},
+		},
+		{
+			"SubsetFields_DowOptional_NotProvided",
+			[]string{"5", "15", "*"},
+			Hour | Dom | Month | DowOptional,
+			[]string{"0", "0", "5", "15", "*", "*"},
+		},
+		{
+			"SubsetFields_SecondOptional_NotProvided",
+			[]string{"5", "15", "*"},
+			SecondOptional | Hour | Dom | Month,
+			[]string{"0", "0", "5", "15", "*", "*"},
+		},
+	}
+
+	for _, test := range tests {
+		t.Run(test.name, func(*testing.T) {
+			actual, err := normalizeFields(test.input, test.options)
+			if err != nil {
+				t.Errorf("unexpected error: %v", err)
+			}
+			if !reflect.DeepEqual(actual, test.expected) {
+				t.Errorf("expected %v, got %v", test.expected, actual)
+			}
+		})
+	}
+}
+
+func TestNormalizeFields_Errors(t *testing.T) {
+	tests := []struct {
+		name    string
+		input   []string
+		options ParseOption
+		err     string
+	}{
+		{
+			"TwoOptionals",
+			[]string{"0", "5", "*", "*", "*", "*"},
+			SecondOptional | Minute | Hour | Dom | Month | DowOptional,
+			"",
+		},
+		{
+			"TooManyFields",
+			[]string{"0", "5", "*", "*"},
+			SecondOptional | Minute | Hour,
+			"",
+		},
+		{
+			"NoFields",
+			[]string{},
+			SecondOptional | Minute | Hour,
+			"",
+		},
+		{
+			"TooFewFields",
+			[]string{"*"},
+			SecondOptional | Minute | Hour,
+			"",
+		},
+	}
+	for _, test := range tests {
+		t.Run(test.name, func(*testing.T) {
+			actual, err := normalizeFields(test.input, test.options)
+			if err == nil {
+				t.Errorf("expected an error, got none. results: %v", actual)
+			}
+			if !strings.Contains(err.Error(), test.err) {
+				t.Errorf("expected error %q, got %q", test.err, err.Error())
+			}
+		})
+	}
+}
+
+func TestStandardSpecSchedule(t *testing.T) {
+	entries := []struct {
+		expr     string
+		expected Schedule
+		err      string
+	}{
+		{
+			expr:     "5 * * * *",
+			expected: &SpecSchedule{1 << seconds.min, 1 << 5, all(hours), all(dom), all(months), all(dow), time.Local},
+		},
+		{
+			expr:     "@every 5m",
+			expected: ConstantDelaySchedule{time.Duration(5) * time.Minute},
+		},
+		{
+			expr: "5 j * * *",
+			err:  `failed to parse number: strconv.Atoi: parsing "j": invalid syntax`,
+		},
+		{
+			expr: "* * * *",
+			err:  "incorrect number of fields",
+		},
+	}
+
+	for _, c := range entries {
+		actual, err := ParseStandard(c.expr)
+		if len(c.err) != 0 && (err == nil || !strings.Contains(err.Error(), c.err)) {
+			t.Errorf("%s => expected %v, got %v", c.expr, c.err, err)
+		}
+		if len(c.err) == 0 && err != nil {
+			t.Errorf("%s => unexpected error %v", c.expr, err)
+		}
+		if !reflect.DeepEqual(actual, c.expected) {
+			t.Errorf("%s => expected %b, got %b", c.expr, c.expected, actual)
+		}
+	}
+}
+
+func TestNoDescriptorParser(t *testing.T) {
+	parser := NewParser(Minute | Hour)
+	_, err := parser.Parse("@every 1m")
+	if err == nil {
+		t.Error("expected an error, got none")
+	}
+}
+
+func every5min(loc *time.Location) *SpecSchedule {
+	return &SpecSchedule{1 << 0, 1 << 5, all(hours), all(dom), all(months), all(dow), loc}
+}
+
+func every5min5s(loc *time.Location) *SpecSchedule {
+	return &SpecSchedule{1 << 5, 1 << 5, all(hours), all(dom), all(months), all(dow), loc}
+}
+
+func midnight(loc *time.Location) *SpecSchedule {
+	return &SpecSchedule{1, 1, 1, all(dom), all(months), all(dow), loc}
+}
+
+func annual(loc *time.Location) *SpecSchedule {
+	return &SpecSchedule{
+		Second:   1 << seconds.min,
+		Minute:   1 << minutes.min,
+		Hour:     1 << hours.min,
+		Dom:      1 << dom.min,
+		Month:    1 << months.min,
+		Dow:      all(dow),
+		Location: loc,
+	}
+}
@@ -0,0 +1,188 @@
+package cron
+
+import "time"
+
+// SpecSchedule specifies a duty cycle (to the second granularity), based on a
+// traditional crontab specification. It is computed initially and stored as bit sets.
+type SpecSchedule struct {
+	Second, Minute, Hour, Dom, Month, Dow uint64
+
+	// Override location for this schedule.
+	Location *time.Location
+}
+
+// bounds provides a range of acceptable values (plus a map of name to value).
+type bounds struct {
+	min, max uint
+	names    map[string]uint
+}
+
+// The bounds for each field.
+var (
+	seconds = bounds{0, 59, nil}
+	minutes = bounds{0, 59, nil}
+	hours   = bounds{0, 23, nil}
+	dom     = bounds{1, 31, nil}
+	months  = bounds{1, 12, map[string]uint{
+		"jan": 1,
+		"feb": 2,
+		"mar": 3,
+		"apr": 4,
+		"may": 5,
+		"jun": 6,
+		"jul": 7,
+		"aug": 8,
+		"sep": 9,
+		"oct": 10,
+		"nov": 11,
+		"dec": 12,
+	}}
+	dow = bounds{0, 6, map[string]uint{
+		"sun": 0,
+		"mon": 1,
+		"tue": 2,
+		"wed": 3,
+		"thu": 4,
+		"fri": 5,
+		"sat": 6,
+	}}
+)
+
+const (
+	// Set the top bit if a star was included in the expression.
+	starBit = 1 << 63
+)
+
+// Next returns the next time this schedule is activated, greater than the given
+// time.  If no time can be found to satisfy the schedule, return the zero time.
+func (s *SpecSchedule) Next(t time.Time) time.Time {
+	// General approach
+	//
+	// For Month, Day, Hour, Minute, Second:
+	// Check if the time value matches.  If yes, continue to the next field.
+	// If the field doesn't match the schedule, then increment the field until it matches.
+	// While incrementing the field, a wrap-around brings it back to the beginning
+	// of the field list (since it is necessary to re-verify previous field
+	// values)
+
+	// Convert the given time into the schedule's timezone, if one is specified.
+	// Save the original timezone so we can convert back after we find a time.
+	// Note that schedules without a time zone specified (time.Local) are treated
+	// as local to the time provided.
+	origLocation := t.Location()
+	loc := s.Location
+	if loc == time.Local {
+		loc = t.Location()
+	}
+	if s.Location != time.Local {
+		t = t.In(s.Location)
+	}
+
+	// Start at the earliest possible time (the upcoming second).
+	t = t.Add(1*time.Second - time.Duration(t.Nanosecond())*time.Nanosecond)
+
+	// This flag indicates whether a field has been incremented.
+	added := false
+
+	// If no time is found within five years, return zero.
+	yearLimit := t.Year() + 5
+
+WRAP:
+	if t.Year() > yearLimit {
+		return time.Time{}
+	}
+
+	// Find the first applicable month.
+	// If it's this month, then do nothing.
+	for 1<<uint(t.Month())&s.Month == 0 {
+		// If we have to add a month, reset the other parts to 0.
+		if !added {
+			added = true
+			// Otherwise, set the date at the beginning (since the current time is irrelevant).
+			t = time.Date(t.Year(), t.Month(), 1, 0, 0, 0, 0, loc)
+		}
+		t = t.AddDate(0, 1, 0)
+
+		// Wrapped around.
+		if t.Month() == time.January {
+			goto WRAP
+		}
+	}
+
+	// Now get a day in that month.
+	//
+	// NOTE: This causes issues for daylight savings regimes where midnight does
+	// not exist.  For example: Sao Paulo has DST that transforms midnight on
+	// 11/3 into 1am. Handle that by noticing when the Hour ends up != 0.
+	for !dayMatches(s, t) {
+		if !added {
+			added = true
+			t = time.Date(t.Year(), t.Month(), t.Day(), 0, 0, 0, 0, loc)
+		}
+		t = t.AddDate(0, 0, 1)
+		// Notice if the hour is no longer midnight due to DST.
+		// Add an hour if it's 23, subtract an hour if it's 1.
+		if t.Hour() != 0 {
+			if t.Hour() > 12 {
+				t = t.Add(time.Duration(24-t.Hour()) * time.Hour)
+			} else {
+				t = t.Add(time.Duration(-t.Hour()) * time.Hour)
+			}
+		}
+
+		if t.Day() == 1 {
+			goto WRAP
+		}
+	}
+
+	for 1<<uint(t.Hour())&s.Hour == 0 {
+		if !added {
+			added = true
+			t = time.Date(t.Year(), t.Month(), t.Day(), t.Hour(), 0, 0, 0, loc)
+		}
+		t = t.Add(1 * time.Hour)
+
+		if t.Hour() == 0 {
+			goto WRAP
+		}
+	}
+
+	for 1<<uint(t.Minute())&s.Minute == 0 {
+		if !added {
+			added = true
+			t = t.Truncate(time.Minute)
+		}
+		t = t.Add(1 * time.Minute)
+
+		if t.Minute() == 0 {
+			goto WRAP
+		}
+	}
+
+	for 1<<uint(t.Second())&s.Second == 0 {
+		if !added {
+			added = true
+			t = t.Truncate(time.Second)
+		}
+		t = t.Add(1 * time.Second)
+
+		if t.Second() == 0 {
+			goto WRAP
+		}
+	}
+
+	return t.In(origLocation)
+}
+
+// dayMatches returns true if the schedule's day-of-week and day-of-month
+// restrictions are satisfied by the given time.
+func dayMatches(s *SpecSchedule, t time.Time) bool {
+	var (
+		domMatch = 1<<uint(t.Day())&s.Dom > 0
+		dowMatch = 1<<uint(t.Weekday())&s.Dow > 0
+	)
+	if s.Dom&starBit > 0 || s.Dow&starBit > 0 {
+		return domMatch && dowMatch
+	}
+	return domMatch || dowMatch
+}
@@ -0,0 +1,301 @@
+//nolint:all
+package cron
+
+import (
+	"strings"
+	"testing"
+	"time"
+)
+
+func TestActivation(t *testing.T) {
+	tests := []struct {
+		time, spec string
+		expected   bool
+	}{
+		// Every fifteen minutes.
+		{"Mon Jul 9 15:00 2012", "0/15 * * * *", true},
+		{"Mon Jul 9 15:45 2012", "0/15 * * * *", true},
+		{"Mon Jul 9 15:40 2012", "0/15 * * * *", false},
+
+		// Every fifteen minutes, starting at 5 minutes.
+		{"Mon Jul 9 15:05 2012", "5/15 * * * *", true},
+		{"Mon Jul 9 15:20 2012", "5/15 * * * *", true},
+		{"Mon Jul 9 15:50 2012", "5/15 * * * *", true},
+
+		// Named months
+		{"Sun Jul 15 15:00 2012", "0/15 * * Jul *", true},
+		{"Sun Jul 15 15:00 2012", "0/15 * * Jun *", false},
+
+		// Everything set.
+		{"Sun Jul 15 08:30 2012", "30 08 ? Jul Sun", true},
+		{"Sun Jul 15 08:30 2012", "30 08 15 Jul ?", true},
+		{"Mon Jul 16 08:30 2012", "30 08 ? Jul Sun", false},
+		{"Mon Jul 16 08:30 2012", "30 08 15 Jul ?", false},
+
+		// Predefined schedules
+		{"Mon Jul 9 15:00 2012", "@hourly", true},
+		{"Mon Jul 9 15:04 2012", "@hourly", false},
+		{"Mon Jul 9 15:00 2012", "@daily", false},
+		{"Mon Jul 9 00:00 2012", "@daily", true},
+		{"Mon Jul 9 00:00 2012", "@weekly", false},
+		{"Sun Jul 8 00:00 2012", "@weekly", true},
+		{"Sun Jul 8 01:00 2012", "@weekly", false},
+		{"Sun Jul 8 00:00 2012", "@monthly", false},
+		{"Sun Jul 1 00:00 2012", "@monthly", true},
+
+		// Test interaction of DOW and DOM.
+		// If both are restricted, then only one needs to match.
+		{"Sun Jul 15 00:00 2012", "* * 1,15 * Sun", true},
+		{"Fri Jun 15 00:00 2012", "* * 1,15 * Sun", true},
+		{"Wed Aug 1 00:00 2012", "* * 1,15 * Sun", true},
+		{"Sun Jul 15 00:00 2012", "* * */10 * Sun", true}, // verifies #70
+
+		// However, if one has a star, then both need to match.
+		{"Sun Jul 15 00:00 2012", "* * * * Mon", false},
+		{"Mon Jul 9 00:00 2012", "* * 1,15 * *", false},
+		{"Sun Jul 15 00:00 2012", "* * 1,15 * *", true},
+		{"Sun Jul 15 00:00 2012", "* * */2 * Sun", true},
+	}
+
+	for _, test := range tests {
+		sched, err := ParseStandard(test.spec)
+		if err != nil {
+			t.Error(err)
+			continue
+		}
+		actual := sched.Next(getTime(test.time).Add(-1 * time.Second))
+		expected := getTime(test.time)
+		if test.expected && expected != actual || !test.expected && expected == actual {
+			t.Errorf("Fail evaluating %s on %s: (expected) %s != %s (actual)",
+				test.spec, test.time, expected, actual)
+		}
+	}
+}
+
+func TestNext(t *testing.T) {
+	runs := []struct {
+		time, spec string
+		expected   string
+	}{
+		// Simple cases
+		{"Mon Jul 9 14:45 2012", "0 0/15 * * * *", "Mon Jul 9 15:00 2012"},
+		{"Mon Jul 9 14:59 2012", "0 0/15 * * * *", "Mon Jul 9 15:00 2012"},
+		{"Mon Jul 9 14:59:59 2012", "0 0/15 * * * *", "Mon Jul 9 15:00 2012"},
+
+		// Wrap around hours
+		{"Mon Jul 9 15:45 2012", "0 20-35/15 * * * *", "Mon Jul 9 16:20 2012"},
+
+		// Wrap around days
+		{"Mon Jul 9 23:46 2012", "0 */15 * * * *", "Tue Jul 10 00:00 2012"},
+		{"Mon Jul 9 23:45 2012", "0 20-35/15 * * * *", "Tue Jul 10 00:20 2012"},
+		{"Mon Jul 9 23:35:51 2012", "15/35 20-35/15 * * * *", "Tue Jul 10 00:20:15 2012"},
+		{"Mon Jul 9 23:35:51 2012", "15/35 20-35/15 1/2 * * *", "Tue Jul 10 01:20:15 2012"},
+		{"Mon Jul 9 23:35:51 2012", "15/35 20-35/15 10-12 * * *", "Tue Jul 10 10:20:15 2012"},
+
+		{"Mon Jul 9 23:35:51 2012", "15/35 20-35/15 1/2 */2 * *", "Thu Jul 11 01:20:15 2012"},
+		{"Mon Jul 9 23:35:51 2012", "15/35 20-35/15 * 9-20 * *", "Wed Jul 10 00:20:15 2012"},
+		{"Mon Jul 9 23:35:51 2012", "15/35 20-35/15 * 9-20 Jul *", "Wed Jul 10 00:20:15 2012"},
+
+		// Wrap around months
+		{"Mon Jul 9 23:35 2012", "0 0 0 9 Apr-Oct ?", "Thu Aug 9 00:00 2012"},
+		{"Mon Jul 9 23:35 2012", "0 0 0 */5 Apr,Aug,Oct Mon", "Tue Aug 1 00:00 2012"},
+		{"Mon Jul 9 23:35 2012", "0 0 0 */5 Oct Mon", "Mon Oct 1 00:00 2012"},
+
+		// Wrap around years
+		{"Mon Jul 9 23:35 2012", "0 0 0 * Feb Mon", "Mon Feb 4 00:00 2013"},
+		{"Mon Jul 9 23:35 2012", "0 0 0 * Feb Mon/2", "Fri Feb 1 00:00 2013"},
+
+		// Wrap around minute, hour, day, month, and year
+		{"Mon Dec 31 23:59:45 2012", "0 * * * * *", "Tue Jan 1 00:00:00 2013"},
+
+		// Leap year
+		{"Mon Jul 9 23:35 2012", "0 0 0 29 Feb ?", "Mon Feb 29 00:00 2016"},
+
+		// Daylight savings time 2am EST (-5) -> 3am EDT (-4)
+		{"2012-03-11T00:00:00-0500", "TZ=America/New_York 0 30 2 11 Mar ?", "2013-03-11T02:30:00-0400"},
+
+		// hourly job
+		{"2012-03-11T00:00:00-0500", "TZ=America/New_York 0 0 * * * ?", "2012-03-11T01:00:00-0500"},
+		{"2012-03-11T01:00:00-0500", "TZ=America/New_York 0 0 * * * ?", "2012-03-11T03:00:00-0400"},
+		{"2012-03-11T03:00:00-0400", "TZ=America/New_York 0 0 * * * ?", "2012-03-11T04:00:00-0400"},
+		{"2012-03-11T04:00:00-0400", "TZ=America/New_York 0 0 * * * ?", "2012-03-11T05:00:00-0400"},
+
+		// hourly job using CRON_TZ
+		{"2012-03-11T00:00:00-0500", "CRON_TZ=America/New_York 0 0 * * * ?", "2012-03-11T01:00:00-0500"},
+		{"2012-03-11T01:00:00-0500", "CRON_TZ=America/New_York 0 0 * * * ?", "2012-03-11T03:00:00-0400"},
+		{"2012-03-11T03:00:00-0400", "CRON_TZ=America/New_York 0 0 * * * ?", "2012-03-11T04:00:00-0400"},
+		{"2012-03-11T04:00:00-0400", "CRON_TZ=America/New_York 0 0 * * * ?", "2012-03-11T05:00:00-0400"},
+
+		// 1am nightly job
+		{"2012-03-11T00:00:00-0500", "TZ=America/New_York 0 0 1 * * ?", "2012-03-11T01:00:00-0500"},
+		{"2012-03-11T01:00:00-0500", "TZ=America/New_York 0 0 1 * * ?", "2012-03-12T01:00:00-0400"},
+
+		// 2am nightly job (skipped)
+		{"2012-03-11T00:00:00-0500", "TZ=America/New_York 0 0 2 * * ?", "2012-03-12T02:00:00-0400"},
+
+		// Daylight savings time 2am EDT (-4) => 1am EST (-5)
+		{"2012-11-04T00:00:00-0400", "TZ=America/New_York 0 30 2 04 Nov ?", "2012-11-04T02:30:00-0500"},
+		{"2012-11-04T01:45:00-0400", "TZ=America/New_York 0 30 1 04 Nov ?", "2012-11-04T01:30:00-0500"},
+
+		// hourly job
+		{"2012-11-04T00:00:00-0400", "TZ=America/New_York 0 0 * * * ?", "2012-11-04T01:00:00-0400"},
+		{"2012-11-04T01:00:00-0400", "TZ=America/New_York 0 0 * * * ?", "2012-11-04T01:00:00-0500"},
+		{"2012-11-04T01:00:00-0500", "TZ=America/New_York 0 0 * * * ?", "2012-11-04T02:00:00-0500"},
+
+		// 1am nightly job (runs twice)
+		{"2012-11-04T00:00:00-0400", "TZ=America/New_York 0 0 1 * * ?", "2012-11-04T01:00:00-0400"},
+		{"2012-11-04T01:00:00-0400", "TZ=America/New_York 0 0 1 * * ?", "2012-11-04T01:00:00-0500"},
+		{"2012-11-04T01:00:00-0500", "TZ=America/New_York 0 0 1 * * ?", "2012-11-05T01:00:00-0500"},
+
+		// 2am nightly job
+		{"2012-11-04T00:00:00-0400", "TZ=America/New_York 0 0 2 * * ?", "2012-11-04T02:00:00-0500"},
+		{"2012-11-04T02:00:00-0500", "TZ=America/New_York 0 0 2 * * ?", "2012-11-05T02:00:00-0500"},
+
+		// 3am nightly job
+		{"2012-11-04T00:00:00-0400", "TZ=America/New_York 0 0 3 * * ?", "2012-11-04T03:00:00-0500"},
+		{"2012-11-04T03:00:00-0500", "TZ=America/New_York 0 0 3 * * ?", "2012-11-05T03:00:00-0500"},
+
+		// hourly job
+		{"TZ=America/New_York 2012-11-04T00:00:00-0400", "0 0 * * * ?", "2012-11-04T01:00:00-0400"},
+		{"TZ=America/New_York 2012-11-04T01:00:00-0400", "0 0 * * * ?", "2012-11-04T01:00:00-0500"},
+		{"TZ=America/New_York 2012-11-04T01:00:00-0500", "0 0 * * * ?", "2012-11-04T02:00:00-0500"},
+
+		// 1am nightly job (runs twice)
+		{"TZ=America/New_York 2012-11-04T00:00:00-0400", "0 0 1 * * ?", "2012-11-04T01:00:00-0400"},
+		{"TZ=America/New_York 2012-11-04T01:00:00-0400", "0 0 1 * * ?", "2012-11-04T01:00:00-0500"},
+		{"TZ=America/New_York 2012-11-04T01:00:00-0500", "0 0 1 * * ?", "2012-11-05T01:00:00-0500"},
+
+		// 2am nightly job
+		{"TZ=America/New_York 2012-11-04T00:00:00-0400", "0 0 2 * * ?", "2012-11-04T02:00:00-0500"},
+		{"TZ=America/New_York 2012-11-04T02:00:00-0500", "0 0 2 * * ?", "2012-11-05T02:00:00-0500"},
+
+		// 3am nightly job
+		{"TZ=America/New_York 2012-11-04T00:00:00-0400", "0 0 3 * * ?", "2012-11-04T03:00:00-0500"},
+		{"TZ=America/New_York 2012-11-04T03:00:00-0500", "0 0 3 * * ?", "2012-11-05T03:00:00-0500"},
+
+		// Unsatisfiable
+		{"Mon Jul 9 23:35 2012", "0 0 0 30 Feb ?", ""},
+		{"Mon Jul 9 23:35 2012", "0 0 0 31 Apr ?", ""},
+
+		// Monthly job
+		{"TZ=America/New_York 2012-11-04T00:00:00-0400", "0 0 3 3 * ?", "2012-12-03T03:00:00-0500"},
+
+		// Test the scenario of DST resulting in midnight not being a valid time.
+		// https://github.com/robfig/cron/issues/157
+		{"2018-10-17T05:00:00-0400", "TZ=America/Sao_Paulo 0 0 9 10 * ?", "2018-11-10T06:00:00-0500"},
+		{"2018-02-14T05:00:00-0500", "TZ=America/Sao_Paulo 0 0 9 22 * ?", "2018-02-22T07:00:00-0500"},
+	}
+
+	for _, c := range runs {
+		sched, err := secondParser.Parse(c.spec)
+		if err != nil {
+			t.Error(err)
+			continue
+		}
+		actual := sched.Next(getTime(c.time))
+		expected := getTime(c.expected)
+		if !actual.Equal(expected) {
+			t.Errorf("%s, \"%s\": (expected) %v != %v (actual)", c.time, c.spec, expected, actual)
+		}
+	}
+}
+
+func TestErrors(t *testing.T) {
+	invalidSpecs := []string{
+		"xyz",
+		"60 0 * * *",
+		"0 60 * * *",
+		"0 0 * * XYZ",
+	}
+	for _, spec := range invalidSpecs {
+		_, err := ParseStandard(spec)
+		if err == nil {
+			t.Error("expected an error parsing: ", spec)
+		}
+	}
+}
+
+func getTime(value string) time.Time {
+	if value == "" {
+		return time.Time{}
+	}
+
+	var location = time.Local
+	if strings.HasPrefix(value, "TZ=") {
+		parts := strings.Fields(value)
+		loc, err := time.LoadLocation(parts[0][len("TZ="):])
+		if err != nil {
+			panic("could not parse location:" + err.Error())
+		}
+		location = loc
+		value = parts[1]
+	}
+
+	var layouts = []string{
+		"Mon Jan 2 15:04 2006",
+		"Mon Jan 2 15:04:05 2006",
+	}
+	for _, layout := range layouts {
+		if t, err := time.ParseInLocation(layout, value, location); err == nil {
+			return t
+		}
+	}
+	if t, err := time.ParseInLocation("2006-01-02T15:04:05-0700", value, location); err == nil {
+		return t
+	}
+	panic("could not parse time value " + value)
+}
+
+func TestNextWithTz(t *testing.T) {
+	runs := []struct {
+		time, spec string
+		expected   string
+	}{
+		// Failing tests
+		{"2016-01-03T13:09:03+0530", "14 14 * * *", "2016-01-03T14:14:00+0530"},
+		{"2016-01-03T04:09:03+0530", "14 14 * * ?", "2016-01-03T14:14:00+0530"},
+
+		// Passing tests
+		{"2016-01-03T14:09:03+0530", "14 14 * * *", "2016-01-03T14:14:00+0530"},
+		{"2016-01-03T14:00:00+0530", "14 14 * * ?", "2016-01-03T14:14:00+0530"},
+	}
+	for _, c := range runs {
+		sched, err := ParseStandard(c.spec)
+		if err != nil {
+			t.Error(err)
+			continue
+		}
+		actual := sched.Next(getTimeTZ(c.time))
+		expected := getTimeTZ(c.expected)
+		if !actual.Equal(expected) {
+			t.Errorf("%s, \"%s\": (expected) %v != %v (actual)", c.time, c.spec, expected, actual)
+		}
+	}
+}
+
+func getTimeTZ(value string) time.Time {
+	if value == "" {
+		return time.Time{}
+	}
+	t, err := time.Parse("Mon Jan 2 15:04 2006", value)
+	if err != nil {
+		t, err = time.Parse("Mon Jan 2 15:04:05 2006", value)
+		if err != nil {
+			t, err = time.Parse("2006-01-02T15:04:05-0700", value)
+			if err != nil {
+				panic(err)
+			}
+		}
+	}
+
+	return t
+}
+
+// https://github.com/robfig/cron/issues/144
+func TestSlash0NoHang(t *testing.T) {
+	schedule := "TZ=America/New_York 15/0 * * * *"
+	_, err := ParseStandard(schedule)
+	if err == nil {
+		t.Error("expected an error on 0 increment")
+	}
+}
@@ -0,0 +1,20 @@
+package filter
+
+import (
+	"strings"
+)
+
+type ConvertContext struct {
+	Buffer strings.Builder
+	Args   []any
+	// The offset of the next argument in the condition string.
+	// Mainly using for PostgreSQL.
+	ArgsOffset int
+}
+
+func NewConvertContext() *ConvertContext {
+	return &ConvertContext{
+		Buffer: strings.Builder{},
+		Args:   []any{},
+	}
+}
@@ -0,0 +1,127 @@
+package filter
+
+import (
+	"errors"
+	"time"
+
+	exprv1 "google.golang.org/genproto/googleapis/api/expr/v1alpha1"
+)
+
+// GetConstValue returns the constant value of the expression.
+func GetConstValue(expr *exprv1.Expr) (any, error) {
+	v, ok := expr.ExprKind.(*exprv1.Expr_ConstExpr)
+	if !ok {
+		return nil, errors.New("invalid constant expression")
+	}
+
+	switch v.ConstExpr.ConstantKind.(type) {
+	case *exprv1.Constant_StringValue:
+		return v.ConstExpr.GetStringValue(), nil
+	case *exprv1.Constant_Int64Value:
+		return v.ConstExpr.GetInt64Value(), nil
+	case *exprv1.Constant_Uint64Value:
+		return v.ConstExpr.GetUint64Value(), nil
+	case *exprv1.Constant_DoubleValue:
+		return v.ConstExpr.GetDoubleValue(), nil
+	case *exprv1.Constant_BoolValue:
+		return v.ConstExpr.GetBoolValue(), nil
+	default:
+		return nil, errors.New("unexpected constant type")
+	}
+}
+
+// GetIdentExprName returns the name of the identifier expression.
+func GetIdentExprName(expr *exprv1.Expr) (string, error) {
+	_, ok := expr.ExprKind.(*exprv1.Expr_IdentExpr)
+	if !ok {
+		return "", errors.New("invalid identifier expression")
+	}
+	return expr.GetIdentExpr().GetName(), nil
+}
+
+// GetFunctionValue evaluates CEL function calls and returns their value.
+// This is specifically for time functions like now().
+func GetFunctionValue(expr *exprv1.Expr) (any, error) {
+	callExpr, ok := expr.ExprKind.(*exprv1.Expr_CallExpr)
+	if !ok {
+		return nil, errors.New("invalid function call expression")
+	}
+
+	switch callExpr.CallExpr.Function {
+	case "now":
+		if len(callExpr.CallExpr.Args) != 0 {
+			return nil, errors.New("now() function takes no arguments")
+		}
+		return time.Now().Unix(), nil
+	case "_-_":
+		// Handle subtraction for expressions like "now() - 60 * 60 * 24"
+		if len(callExpr.CallExpr.Args) != 2 {
+			return nil, errors.New("subtraction requires exactly two arguments")
+		}
+		left, err := GetExprValue(callExpr.CallExpr.Args[0])
+		if err != nil {
+			return nil, err
+		}
+		right, err := GetExprValue(callExpr.CallExpr.Args[1])
+		if err != nil {
+			return nil, err
+		}
+		leftInt, ok1 := left.(int64)
+		rightInt, ok2 := right.(int64)
+		if !ok1 || !ok2 {
+			return nil, errors.New("subtraction operands must be integers")
+		}
+		return leftInt - rightInt, nil
+	case "_*_":
+		// Handle multiplication for expressions like "60 * 60 * 24"
+		if len(callExpr.CallExpr.Args) != 2 {
+			return nil, errors.New("multiplication requires exactly two arguments")
+		}
+		left, err := GetExprValue(callExpr.CallExpr.Args[0])
+		if err != nil {
+			return nil, err
+		}
+		right, err := GetExprValue(callExpr.CallExpr.Args[1])
+		if err != nil {
+			return nil, err
+		}
+		leftInt, ok1 := left.(int64)
+		rightInt, ok2 := right.(int64)
+		if !ok1 || !ok2 {
+			return nil, errors.New("multiplication operands must be integers")
+		}
+		return leftInt * rightInt, nil
+	case "_+_":
+		// Handle addition
+		if len(callExpr.CallExpr.Args) != 2 {
+			return nil, errors.New("addition requires exactly two arguments")
+		}
+		left, err := GetExprValue(callExpr.CallExpr.Args[0])
+		if err != nil {
+			return nil, err
+		}
+		right, err := GetExprValue(callExpr.CallExpr.Args[1])
+		if err != nil {
+			return nil, err
+		}
+		leftInt, ok1 := left.(int64)
+		rightInt, ok2 := right.(int64)
+		if !ok1 || !ok2 {
+			return nil, errors.New("addition operands must be integers")
+		}
+		return leftInt + rightInt, nil
+	default:
+		return nil, errors.New("unsupported function: " + callExpr.CallExpr.Function)
+	}
+}
+
+// GetExprValue attempts to get a value from an expression, trying constants first, then functions.
+func GetExprValue(expr *exprv1.Expr) (any, error) {
+	// Try to get constant value first
+	if constValue, err := GetConstValue(expr); err == nil {
+		return constValue, nil
+	}
+
+	// If not a constant, try to evaluate as a function
+	return GetFunctionValue(expr)
+}
@@ -0,0 +1,47 @@
+package filter
+
+import (
+	"time"
+
+	"github.com/google/cel-go/cel"
+	"github.com/google/cel-go/common/types"
+	"github.com/google/cel-go/common/types/ref"
+	"github.com/pkg/errors"
+	exprv1 "google.golang.org/genproto/googleapis/api/expr/v1alpha1"
+)
+
+// MemoFilterCELAttributes are the CEL attributes for memo.
+var MemoFilterCELAttributes = []cel.EnvOption{
+	cel.Variable("content", cel.StringType),
+	cel.Variable("creator_id", cel.IntType),
+	cel.Variable("created_ts", cel.IntType),
+	cel.Variable("updated_ts", cel.IntType),
+	cel.Variable("pinned", cel.BoolType),
+	cel.Variable("tag", cel.StringType),
+	cel.Variable("visibility", cel.StringType),
+	cel.Variable("has_task_list", cel.BoolType),
+	// Current timestamp function.
+	cel.Function("now",
+		cel.Overload("now",
+			[]*cel.Type{},
+			cel.IntType,
+			cel.FunctionBinding(func(_ ...ref.Val) ref.Val {
+				return types.Int(time.Now().Unix())
+			}),
+		),
+	),
+}
+
+// Parse parses the filter string and returns the parsed expression.
+// The filter string should be a CEL expression.
+func Parse(filter string, opts ...cel.EnvOption) (expr *exprv1.ParsedExpr, err error) {
+	e, err := cel.NewEnv(opts...)
+	if err != nil {
+		return nil, errors.Wrap(err, "failed to create CEL environment")
+	}
+	ast, issues := e.Compile(filter)
+	if issues != nil {
+		return nil, errors.Errorf("failed to compile filter: %v", issues)
+	}
+	return cel.AstToParsedExpr(ast)
+}
@@ -1,28 +0,0 @@
-package getter
-
-import (
-	"testing"
-
-	"github.com/stretchr/testify/require"
-)
-
-func TestGetHTMLMeta(t *testing.T) {
-	tests := []struct {
-		urlStr   string
-		htmlMeta HTMLMeta
-	}{
-		{
-			urlStr: "https://www.bytebase.com/blog/sql-review-tool-for-devs",
-			htmlMeta: HTMLMeta{
-				Title:       "The SQL Review Tool for Developers",
-				Description: "Reviewing SQL can be somewhat tedious, yet is essential to keep your database fleet reliable. At Bytebase, we are building a developer-first SQL review tool to empower the DevOps system.",
-				Image:       "https://www.bytebase.com/static/blog/sql-review-tool-for-devs/dev-fighting-dba.webp",
-			},
-		},
-	}
-	for _, test := range tests {
-		metadata, err := GetHTMLMeta(test.urlStr)
-		require.NoError(t, err)
-		require.Equal(t, test.htmlMeta, *metadata)
-	}
-}
@@ -1,4 +0,0 @@
-// Package getter is using to get resources from url.
-// * Get metadata for website;
-// * Get image blob to avoid CORS;
-package getter
@@ -1,21 +0,0 @@
-package getter
-
-import (
-	"testing"
-
-	"github.com/stretchr/testify/require"
-)
-
-func TestGetImage(t *testing.T) {
-	tests := []struct {
-		urlStr string
-	}{
-		{
-			urlStr: "https://star-history.com/bytebase.webp",
-		},
-	}
-	for _, test := range tests {
-		_, err := GetImage(test.urlStr)
-		require.NoError(t, err)
-	}
-}
@@ -1,15 +1,31 @@
-package getter
+package httpgetter

 import (
 	"fmt"
 	"io"
+	"net"
 	"net/http"
 	"net/url"

+	"github.com/pkg/errors"
 	"golang.org/x/net/html"
 	"golang.org/x/net/html/atom"
 )

+var ErrInternalIP = errors.New("internal IP addresses are not allowed")
+
+var httpClient = &http.Client{
+	CheckRedirect: func(req *http.Request, via []*http.Request) error {
+		if err := validateURL(req.URL.String()); err != nil {
+			return errors.Wrap(err, "redirect to internal IP")
+		}
+		if len(via) >= 10 {
+			return errors.New("too many redirects")
+		}
+		return nil
+	},
+}
+
 type HTMLMeta struct {
 	Title       string `json:"title"`
 	Description string `json:"description"`
@@ -17,11 +33,11 @@ type HTMLMeta struct {
 }

 func GetHTMLMeta(urlStr string) (*HTMLMeta, error) {
-	if _, err := url.Parse(urlStr); err != nil {
+	if err := validateURL(urlStr); err != nil {
 		return nil, err
 	}

-	response, err := http.Get(urlStr)
+	response, err := httpClient.Get(urlStr)
 	if err != nil {
 		return nil, err
 	}
@@ -32,10 +48,13 @@ func GetHTMLMeta(urlStr string) (*HTMLMeta, error) {
 		return nil, err
 	}
 	if mediatype != "text/html" {
-		return nil, fmt.Errorf("Wrong website mediatype")
+		return nil, errors.New("not a HTML page")
 	}

+	// TODO: limit the size of the response body
+
 	htmlMeta := extractHTMLMeta(response.Body)
+	enrichSiteMeta(response.Request.URL, htmlMeta)
 	return htmlMeta, nil
 }

@@ -96,3 +115,52 @@ func extractMetaProperty(token html.Token, prop string) (content string, ok bool
 	}
 	return content, ok
 }
+
+func validateURL(urlStr string) error {
+	u, err := url.Parse(urlStr)
+	if err != nil {
+		return errors.New("invalid URL format")
+	}
+
+	if u.Scheme != "http" && u.Scheme != "https" {
+		return errors.New("only http/https protocols are allowed")
+	}
+
+	host := u.Hostname()
+	if host == "" {
+		return errors.New("empty hostname")
+	}
+
+	// check if the hostname is an IP
+	if ip := net.ParseIP(host); ip != nil {
+		if ip.IsLoopback() || ip.IsPrivate() || ip.IsLinkLocalUnicast() {
+			return errors.Wrap(ErrInternalIP, ip.String())
+		}
+		return nil
+	}
+
+	// check if it's a hostname, resolve it and check all returned IPs
+	ips, err := net.LookupIP(host)
+	if err != nil {
+		return errors.Errorf("failed to resolve hostname: %v", err)
+	}
+
+	for _, ip := range ips {
+		if ip.IsLoopback() || ip.IsPrivate() || ip.IsLinkLocalUnicast() {
+			return errors.Wrapf(ErrInternalIP, "host=%s, ip=%s", host, ip.String())
+		}
+	}
+
+	return nil
+}
+
+func enrichSiteMeta(url *url.URL, meta *HTMLMeta) {
+	if url.Hostname() == "www.youtube.com" {
+		if url.Path == "/watch" {
+			vid := url.Query().Get("v")
+			if vid != "" {
+				meta.Image = fmt.Sprintf("https://img.youtube.com/vi/%s/mqdefault.jpg", vid)
+			}
+		}
+	}
+}
@@ -0,0 +1,32 @@
+package httpgetter
+
+import (
+	"errors"
+	"testing"
+
+	"github.com/stretchr/testify/require"
+)
+
+func TestGetHTMLMeta(t *testing.T) {
+	tests := []struct {
+		urlStr   string
+		htmlMeta HTMLMeta
+	}{}
+	for _, test := range tests {
+		metadata, err := GetHTMLMeta(test.urlStr)
+		require.NoError(t, err)
+		require.Equal(t, test.htmlMeta, *metadata)
+	}
+}
+
+func TestGetHTMLMetaForInternal(t *testing.T) {
+	// test for internal IP
+	if _, err := GetHTMLMeta("http://192.168.0.1"); !errors.Is(err, ErrInternalIP) {
+		t.Errorf("Expected error for internal IP, got %v", err)
+	}
+
+	// test for resolved internal IP
+	if _, err := GetHTMLMeta("http://localhost"); !errors.Is(err, ErrInternalIP) {
+		t.Errorf("Expected error for resolved internal IP, got %v", err)
+	}
+}
@@ -0,0 +1,4 @@
+// Package httpgetter is using to get resources from url.
+// * Get metadata for website;
+// * Get image blob to avoid CORS;
+package httpgetter
@@ -1,7 +1,7 @@
-package getter
+package httpgetter

 import (
-	"fmt"
+	"errors"
 	"io"
 	"net/http"
 	"net/url"
@@ -29,7 +29,7 @@ func GetImage(urlStr string) (*Image, error) {
 		return nil, err
 	}
 	if !strings.HasPrefix(mediatype, "image/") {
-		return nil, fmt.Errorf("Wrong image mediatype")
+		return nil, errors.New("wrong image mediatype")
 	}

 	bodyBytes, err := io.ReadAll(response.Body)
@@ -1,4 +1,4 @@
-package getter
+package httpgetter

 import (
 	"mime"
@@ -4,4 +4,5 @@ type IdentityProviderUserInfo struct {
 	Identifier  string
 	DisplayName string
 	Email       string
+	AvatarURL   string
 }
@@ -6,26 +6,28 @@ import (
 	"encoding/json"
 	"fmt"
 	"io"
+	"log/slog"
 	"net/http"

 	"github.com/pkg/errors"
-	"github.com/usememos/memos/plugin/idp"
-	"github.com/usememos/memos/store"
 	"golang.org/x/oauth2"
+
+	"github.com/usememos/memos/plugin/idp"
+	storepb "github.com/usememos/memos/proto/gen/store"
 )

 // IdentityProvider represents an OAuth2 Identity Provider.
 type IdentityProvider struct {
-	config *store.IdentityProviderOAuth2Config
+	config *storepb.OAuth2Config
 }

 // NewIdentityProvider initializes a new OAuth2 Identity Provider with the given configuration.
-func NewIdentityProvider(config *store.IdentityProviderOAuth2Config) (*IdentityProvider, error) {
+func NewIdentityProvider(config *storepb.OAuth2Config) (*IdentityProvider, error) {
 	for v, field := range map[string]string{
-		config.ClientID:                "clientId",
+		config.ClientId:                "clientId",
 		config.ClientSecret:            "clientSecret",
-		config.TokenURL:                "tokenUrl",
-		config.UserInfoURL:             "userInfoUrl",
+		config.TokenUrl:                "tokenUrl",
+		config.UserInfoUrl:             "userInfoUrl",
 		config.FieldMapping.Identifier: "fieldMapping.identifier",
 	} {
 		if v == "" {
@@ -41,13 +43,13 @@ func NewIdentityProvider(config *store.IdentityProviderOAuth2Config) (*IdentityP
 // ExchangeToken returns the exchanged OAuth2 token using the given authorization code.
 func (p *IdentityProvider) ExchangeToken(ctx context.Context, redirectURL, code string) (string, error) {
 	conf := &oauth2.Config{
-		ClientID:     p.config.ClientID,
+		ClientID:     p.config.ClientId,
 		ClientSecret: p.config.ClientSecret,
 		RedirectURL:  redirectURL,
 		Scopes:       p.config.Scopes,
 		Endpoint: oauth2.Endpoint{
-			AuthURL:   p.config.AuthURL,
-			TokenURL:  p.config.TokenURL,
+			AuthURL:   p.config.AuthUrl,
+			TokenURL:  p.config.TokenUrl,
 			AuthStyle: oauth2.AuthStyleInParams,
 		},
 	}
@@ -68,7 +70,7 @@ func (p *IdentityProvider) ExchangeToken(ctx context.Context, redirectURL, code
 // UserInfo returns the parsed user information using the given OAuth2 token.
 func (p *IdentityProvider) UserInfo(token string) (*idp.IdentityProviderUserInfo, error) {
 	client := &http.Client{}
-	req, err := http.NewRequest(http.MethodGet, p.config.UserInfoURL, nil)
+	req, err := http.NewRequest(http.MethodGet, p.config.UserInfoUrl, nil)
 	if err != nil {
 		return nil, errors.Wrap(err, "failed to new http request")
 	}
@@ -82,13 +84,13 @@ func (p *IdentityProvider) UserInfo(token string) (*idp.IdentityProviderUserInfo
 	if err != nil {
 		return nil, errors.Wrap(err, "failed to read response body")
 	}
+	defer resp.Body.Close()

 	var claims map[string]any
-	err = json.Unmarshal(body, &claims)
-	if err != nil {
+	if err := json.Unmarshal(body, &claims); err != nil {
 		return nil, errors.Wrap(err, "failed to unmarshal response body")
 	}
-
+	slog.Info("user info claims", "claims", claims)
 	userInfo := &idp.IdentityProviderUserInfo{}
 	if v, ok := claims[p.config.FieldMapping.Identifier].(string); ok {
 		userInfo.Identifier = v
@@ -111,5 +113,11 @@ func (p *IdentityProvider) UserInfo(token string) (*idp.IdentityProviderUserInfo
 			userInfo.Email = v
 		}
 	}
+	if p.config.FieldMapping.AvatarUrl != "" {
+		if v, ok := claims[p.config.FieldMapping.AvatarUrl].(string); ok {
+			userInfo.AvatarURL = v
+		}
+	}
+	slog.Info("user info", "userInfo", userInfo)
 	return userInfo, nil
 }
@@ -12,25 +12,26 @@ import (

 	"github.com/stretchr/testify/assert"
 	"github.com/stretchr/testify/require"
+
 	"github.com/usememos/memos/plugin/idp"
-	"github.com/usememos/memos/store"
+	storepb "github.com/usememos/memos/proto/gen/store"
 )

 func TestNewIdentityProvider(t *testing.T) {
 	tests := []struct {
 		name        string
-		config      *store.IdentityProviderOAuth2Config
+		config      *storepb.OAuth2Config
 		containsErr string
 	}{
 		{
 			name: "no tokenUrl",
-			config: &store.IdentityProviderOAuth2Config{
-				ClientID:     "test-client-id",
+			config: &storepb.OAuth2Config{
+				ClientId:     "test-client-id",
 				ClientSecret: "test-client-secret",
-				AuthURL:      "",
-				TokenURL:     "",
-				UserInfoURL:  "https://example.com/api/user",
-				FieldMapping: &store.FieldMapping{
+				AuthUrl:      "",
+				TokenUrl:     "",
+				UserInfoUrl:  "https://example.com/api/user",
+				FieldMapping: &storepb.FieldMapping{
 					Identifier: "login",
 				},
 			},
@@ -38,13 +39,13 @@ func TestNewIdentityProvider(t *testing.T) {
 		},
 		{
 			name: "no userInfoUrl",
-			config: &store.IdentityProviderOAuth2Config{
-				ClientID:     "test-client-id",
+			config: &storepb.OAuth2Config{
+				ClientId:     "test-client-id",
 				ClientSecret: "test-client-secret",
-				AuthURL:      "",
-				TokenURL:     "https://example.com/token",
-				UserInfoURL:  "",
-				FieldMapping: &store.FieldMapping{
+				AuthUrl:      "",
+				TokenUrl:     "https://example.com/token",
+				UserInfoUrl:  "",
+				FieldMapping: &storepb.FieldMapping{
 					Identifier: "login",
 				},
 			},
@@ -52,13 +53,13 @@ func TestNewIdentityProvider(t *testing.T) {
 		},
 		{
 			name: "no field mapping identifier",
-			config: &store.IdentityProviderOAuth2Config{
-				ClientID:     "test-client-id",
+			config: &storepb.OAuth2Config{
+				ClientId:     "test-client-id",
 				ClientSecret: "test-client-secret",
-				AuthURL:      "",
-				TokenURL:     "https://example.com/token",
-				UserInfoURL:  "https://example.com/api/user",
-				FieldMapping: &store.FieldMapping{
+				AuthUrl:      "",
+				TokenUrl:     "https://example.com/token",
+				UserInfoUrl:  "https://example.com/api/user",
+				FieldMapping: &storepb.FieldMapping{
 					Identifier: "",
 				},
 			},
@@ -66,7 +67,7 @@ func TestNewIdentityProvider(t *testing.T) {
 		},
 	}
 	for _, test := range tests {
-		t.Run(test.name, func(t *testing.T) {
+		t.Run(test.name, func(*testing.T) {
 			_, err := NewIdentityProvider(test.config)
 			assert.ErrorContains(t, err, test.containsErr)
 		})
@@ -90,15 +91,14 @@ func newMockServer(t *testing.T, code, accessToken string, userinfo []byte) *htt

 		w.Header().Set("Content-Type", "application/json")
 		err = json.NewEncoder(w).Encode(map[string]any{
-			"access_token":  accessToken,
-			"token_type":    "Bearer",
-			"refresh_token": "test-refresh-token",
-			"expires_in":    3600,
-			"id_token":      rawIDToken,
+			"access_token": accessToken,
+			"token_type":   "Bearer",
+			"expires_in":   3600,
+			"id_token":     rawIDToken,
 		})
 		require.NoError(t, err)
 	})
-	mux.HandleFunc("/oauth2/userinfo", func(w http.ResponseWriter, r *http.Request) {
+	mux.HandleFunc("/oauth2/userinfo", func(w http.ResponseWriter, _ *http.Request) {
 		w.Header().Set("Content-Type", "application/json")
 		_, err := w.Write(userinfo)
 		require.NoError(t, err)
@@ -132,12 +132,12 @@ func TestIdentityProvider(t *testing.T) {
 	s := newMockServer(t, testCode, testAccessToken, userInfo)

 	oauth2, err := NewIdentityProvider(
-		&store.IdentityProviderOAuth2Config{
-			ClientID:     testClientID,
+		&storepb.OAuth2Config{
+			ClientId:     testClientID,
 			ClientSecret: "test-client-secret",
-			TokenURL:     fmt.Sprintf("%s/oauth2/token", s.URL),
-			UserInfoURL:  fmt.Sprintf("%s/oauth2/userinfo", s.URL),
-			FieldMapping: &store.FieldMapping{
+			TokenUrl:     fmt.Sprintf("%s/oauth2/token", s.URL),
+			UserInfoUrl:  fmt.Sprintf("%s/oauth2/userinfo", s.URL),
+			FieldMapping: &storepb.FieldMapping{
 				Identifier:  "sub",
 				DisplayName: "name",
 				Email:       "email",
@@ -1,84 +0,0 @@
-package openai
-
-import (
-	"bytes"
-	"encoding/json"
-	"errors"
-	"io"
-	"net/http"
-	"net/url"
-)
-
-type ChatCompletionMessage struct {
-	Role    string `json:"role"`
-	Content string `json:"content"`
-}
-
-type ChatCompletionChoice struct {
-	Message *ChatCompletionMessage `json:"message"`
-}
-
-type ChatCompletionResponse struct {
-	Error   interface{}            `json:"error"`
-	Model   string                 `json:"model"`
-	Choices []ChatCompletionChoice `json:"choices"`
-}
-
-func PostChatCompletion(prompt string, apiKey string, apiHost string) (string, error) {
-	if apiHost == "" {
-		apiHost = "https://api.openai.com"
-	}
-	url, err := url.JoinPath(apiHost, "/v1/chat/completions")
-	if err != nil {
-		return "", err
-	}
-
-	values := map[string]interface{}{
-		"model":    "gpt-3.5-turbo",
-		"messages": []map[string]string{{"role": "user", "content": prompt}},
-	}
-	jsonValue, err := json.Marshal(values)
-	if err != nil {
-		return "", err
-	}
-
-	req, err := http.NewRequest("POST", url, bytes.NewBuffer(jsonValue))
-	if err != nil {
-		return "", err
-	}
-
-	// Set the API key in the request header
-	req.Header.Set("Content-Type", "application/json")
-	req.Header.Set("Authorization", "Bearer "+apiKey)
-
-	// Send the request to OpenAI's API
-	client := http.Client{}
-	resp, err := client.Do(req)
-	if err != nil {
-		return "", err
-	}
-	defer resp.Body.Close()
-
-	// Read the response body
-	responseBody, err := io.ReadAll(resp.Body)
-	if err != nil {
-		return "", err
-	}
-
-	chatCompletionResponse := ChatCompletionResponse{}
-	err = json.Unmarshal(responseBody, &chatCompletionResponse)
-	if err != nil {
-		return "", err
-	}
-	if chatCompletionResponse.Error != nil {
-		errorBytes, err := json.Marshal(chatCompletionResponse.Error)
-		if err != nil {
-			return "", err
-		}
-		return "", errors.New(string(errorBytes))
-	}
-	if len(chatCompletionResponse.Choices) == 0 {
-		return "", nil
-	}
-	return chatCompletionResponse.Choices[0].Message.Content, nil
-}
@@ -1,83 +0,0 @@
-package openai
-
-import (
-	"bytes"
-	"encoding/json"
-	"errors"
-	"io"
-	"net/http"
-	"net/url"
-)
-
-type TextCompletionChoice struct {
-	Text string `json:"text"`
-}
-
-type TextCompletionResponse struct {
-	Error   interface{}            `json:"error"`
-	Model   string                 `json:"model"`
-	Choices []TextCompletionChoice `json:"choices"`
-}
-
-func PostTextCompletion(prompt string, apiKey string, apiHost string) (string, error) {
-	if apiHost == "" {
-		apiHost = "https://api.openai.com"
-	}
-	url, err := url.JoinPath(apiHost, "/v1/chat/completions")
-	if err != nil {
-		return "", err
-	}
-
-	values := map[string]interface{}{
-		"model":       "gpt-3.5-turbo",
-		"prompt":      prompt,
-		"temperature": 0.5,
-		"max_tokens":  100,
-		"n":           1,
-		"stop":        ".",
-	}
-	jsonValue, err := json.Marshal(values)
-	if err != nil {
-		return "", err
-	}
-
-	req, err := http.NewRequest("POST", url, bytes.NewBuffer(jsonValue))
-	if err != nil {
-		return "", err
-	}
-
-	// Set the API key in the request header
-	req.Header.Set("Content-Type", "application/json")
-	req.Header.Set("Authorization", "Bearer "+apiKey)
-
-	// Send the request to OpenAI's API
-	client := http.Client{}
-	resp, err := client.Do(req)
-	if err != nil {
-		return "", err
-	}
-	defer resp.Body.Close()
-
-	// Read the response body
-	responseBody, err := io.ReadAll(resp.Body)
-	if err != nil {
-		return "", err
-	}
-
-	textCompletionResponse := TextCompletionResponse{}
-	err = json.Unmarshal(responseBody, &textCompletionResponse)
-	if err != nil {
-		return "", err
-	}
-	if textCompletionResponse.Error != nil {
-		errorBytes, err := json.Marshal(textCompletionResponse.Error)
-		if err != nil {
-			return "", err
-		}
-		return "", errors.New(string(errorBytes))
-	}
-	if len(textCompletionResponse.Choices) == 0 {
-		return "", nil
-	}
-	return textCompletionResponse.Choices[0].Text, nil
-}
@@ -2,75 +2,91 @@ package s3

 import (
 	"context"
-	"fmt"
 	"io"
+	"time"

 	"github.com/aws/aws-sdk-go-v2/aws"
-	s3config "github.com/aws/aws-sdk-go-v2/config"
+	"github.com/aws/aws-sdk-go-v2/config"
 	"github.com/aws/aws-sdk-go-v2/credentials"
 	"github.com/aws/aws-sdk-go-v2/feature/s3/manager"
-	awss3 "github.com/aws/aws-sdk-go-v2/service/s3"
-	"github.com/aws/aws-sdk-go-v2/service/s3/types"
+	"github.com/aws/aws-sdk-go-v2/service/s3"
+	"github.com/pkg/errors"
+
+	storepb "github.com/usememos/memos/proto/gen/store"
 )

-type Config struct {
-	AccessKey string
-	SecretKey string
-	Bucket    string
-	EndPoint  string
-	Region    string
-	URLPrefix string
-}
-
 type Client struct {
-	Client *awss3.Client
-	Config *Config
+	Client *s3.Client
+	Bucket *string
 }

-func NewClient(ctx context.Context, config *Config) (*Client, error) {
-	resolver := aws.EndpointResolverWithOptionsFunc(func(service, region string, options ...interface{}) (aws.Endpoint, error) {
-		return aws.Endpoint{
-			URL:           config.EndPoint,
-			SigningRegion: config.Region,
-		}, nil
-	})
-
-	awsConfig, err := s3config.LoadDefaultConfig(ctx,
-		s3config.WithEndpointResolverWithOptions(resolver),
-		s3config.WithCredentialsProvider(credentials.NewStaticCredentialsProvider(config.AccessKey, config.SecretKey, "")),
+func NewClient(ctx context.Context, s3Config *storepb.StorageS3Config) (*Client, error) {
+	cfg, err := config.LoadDefaultConfig(ctx,
+		config.WithCredentialsProvider(credentials.NewStaticCredentialsProvider(s3Config.AccessKeyId, s3Config.AccessKeySecret, "")),
+		config.WithRegion(s3Config.Region),
 	)
 	if err != nil {
-		return nil, err
+		return nil, errors.Wrap(err, "failed to load s3 config")
 	}

-	client := awss3.NewFromConfig(awsConfig)
-
+	client := s3.NewFromConfig(cfg, func(o *s3.Options) {
+		o.BaseEndpoint = aws.String(s3Config.Endpoint)
+		o.UsePathStyle = s3Config.UsePathStyle
+		o.RequestChecksumCalculation = aws.RequestChecksumCalculationWhenRequired
+		o.ResponseChecksumValidation = aws.ResponseChecksumValidationWhenRequired
+	})
 	return &Client{
 		Client: client,
-		Config: config,
+		Bucket: aws.String(s3Config.Bucket),
 	}, nil
 }

-func (client *Client) UploadFile(ctx context.Context, filename string, fileType string, src io.Reader) (string, error) {
-	uploader := manager.NewUploader(client.Client)
-	uploadOutput, err := uploader.Upload(ctx, &awss3.PutObjectInput{
-		Bucket:      aws.String(client.Config.Bucket),
-		Key:         aws.String(filename),
-		Body:        src,
+// UploadObject uploads an object to S3.
+func (c *Client) UploadObject(ctx context.Context, key string, fileType string, content io.Reader) (string, error) {
+	uploader := manager.NewUploader(c.Client)
+	putInput := s3.PutObjectInput{
+		Bucket:      c.Bucket,
+		Key:         aws.String(key),
 		ContentType: aws.String(fileType),
-		ACL:         types.ObjectCannedACL(*aws.String("public-read")),
-	})
+		Body:        content,
+	}
+	result, err := uploader.Upload(ctx, &putInput)
 	if err != nil {
 		return "", err
 	}

-	link := uploadOutput.Location
-	// If url prefix is set, use it as the file link.
-	if client.Config.URLPrefix != "" {
-		link = fmt.Sprintf("%s/%s", client.Config.URLPrefix, filename)
+	resultKey := result.Key
+	if resultKey == nil || *resultKey == "" {
+		return "", errors.New("failed to get file key")
 	}
-	if link == "" {
-		return "", fmt.Errorf("failed to get file link")
-	}
-	return link, nil
+	return *resultKey, nil
+}
+
+// PresignGetObject presigns an object in S3.
+func (c *Client) PresignGetObject(ctx context.Context, key string) (string, error) {
+	presignClient := s3.NewPresignClient(c.Client)
+	presignResult, err := presignClient.PresignGetObject(ctx, &s3.GetObjectInput{
+		Bucket: aws.String(*c.Bucket),
+		Key:    aws.String(key),
+	}, func(opts *s3.PresignOptions) {
+		// Set the expiration time of the presigned URL to 5 days.
+		// Reference: https://docs.aws.amazon.com/AmazonS3/latest/API/sigv4-query-string-auth.html
+		opts.Expires = time.Duration(5 * 24 * time.Hour)
+	})
+	if err != nil {
+		return "", errors.Wrap(err, "failed to presign put object")
+	}
+	return presignResult.URL, nil
+}
+
+// DeleteObject deletes an object in S3.
+func (c *Client) DeleteObject(ctx context.Context, key string) error {
+	_, err := c.Client.DeleteObject(ctx, &s3.DeleteObjectInput{
+		Bucket: c.Bucket,
+		Key:    aws.String(key),
+	})
+	if err != nil {
+		return errors.Wrap(err, "failed to delete object")
+	}
+	return nil
 }
@@ -0,0 +1,80 @@
+package webhook
+
+import (
+	"bytes"
+	"encoding/json"
+	"io"
+	"log/slog"
+	"net/http"
+	"time"
+
+	"github.com/pkg/errors"
+	"google.golang.org/protobuf/encoding/protojson"
+
+	v1pb "github.com/usememos/memos/proto/gen/api/v1"
+)
+
+var (
+	// timeout is the timeout for webhook request. Default to 30 seconds.
+	timeout = 30 * time.Second
+)
+
+// Post posts the message to webhook endpoint.
+func Post(requestPayload *v1pb.WebhookRequestPayload) error {
+	body, err := protojson.Marshal(requestPayload)
+	if err != nil {
+		return errors.Wrapf(err, "failed to marshal webhook request to %s", requestPayload.Url)
+	}
+
+	req, err := http.NewRequest("POST", requestPayload.Url, bytes.NewBuffer(body))
+	if err != nil {
+		return errors.Wrapf(err, "failed to construct webhook request to %s", requestPayload.Url)
+	}
+
+	req.Header.Set("Content-Type", "application/json")
+	client := &http.Client{
+		Timeout: timeout,
+	}
+	resp, err := client.Do(req)
+	if err != nil {
+		return errors.Wrapf(err, "failed to post webhook to %s", requestPayload.Url)
+	}
+
+	b, err := io.ReadAll(resp.Body)
+	if err != nil {
+		return errors.Wrapf(err, "failed to read webhook response from %s", requestPayload.Url)
+	}
+	defer resp.Body.Close()
+
+	if resp.StatusCode < 200 || resp.StatusCode > 299 {
+		return errors.Errorf("failed to post webhook %s, status code: %d, response body: %s", requestPayload.Url, resp.StatusCode, b)
+	}
+
+	response := &struct {
+		Code    int    `json:"code"`
+		Message string `json:"message"`
+	}{}
+	if err := json.Unmarshal(b, response); err != nil {
+		return errors.Wrapf(err, "failed to unmarshal webhook response from %s", requestPayload.Url)
+	}
+
+	if response.Code != 0 {
+		return errors.Errorf("receive error code sent by webhook server, code %d, msg: %s", response.Code, response.Message)
+	}
+
+	return nil
+}
+
+// PostAsync posts the message to webhook endpoint asynchronously.
+// It spawns a new goroutine to handle the request and does not wait for the response.
+func PostAsync(requestPayload *v1pb.WebhookRequestPayload) {
+	go func() {
+		if err := Post(requestPayload); err != nil {
+			// Since we're in a goroutine, we can only log the error
+			slog.Warn("Failed to dispatch webhook asynchronously",
+				slog.String("url", requestPayload.Url),
+				slog.String("activityType", requestPayload.ActivityType),
+				slog.Any("err", err))
+		}
+	}()
+}
@@ -0,0 +1 @@
+package webhook
@@ -0,0 +1,17 @@
+# Guide
+
+## Prerequisites
+
+- [buf](https://docs.buf.build/installation)
+
+## Generate
+
+```sh
+buf generate
+```
+
+## Format
+
+```sh
+buf format -w
+```
@@ -0,0 +1,3 @@
+# Memos API Design
+
+This API design should follow the guidelines and best practices outlined in the [Google API Improvement Proposals (AIPs)](https://google.aip.dev/).
@@ -0,0 +1,57 @@
+syntax = "proto3";
+
+package memos.api.v1;
+
+import "google/api/annotations.proto";
+import "google/api/client.proto";
+import "google/api/field_behavior.proto";
+import "google/protobuf/timestamp.proto";
+
+option go_package = "gen/api/v1";
+
+service ActivityService {
+  // GetActivity returns the activity with the given id.
+  rpc GetActivity(GetActivityRequest) returns (Activity) {
+    option (google.api.http) = {get: "/api/v1/{name=activities/*}"};
+    option (google.api.method_signature) = "name";
+  }
+}
+
+message Activity {
+  // The name of the activity.
+  // Format: activities/{id}
+  string name = 1 [
+    (google.api.field_behavior) = OUTPUT_ONLY,
+    (google.api.field_behavior) = IDENTIFIER
+  ];
+  // The name of the creator.
+  // Format: users/{user}
+  string creator = 2;
+  // The type of the activity.
+  string type = 3;
+  // The level of the activity.
+  string level = 4;
+  // The create time of the activity.
+  google.protobuf.Timestamp create_time = 5 [(google.api.field_behavior) = OUTPUT_ONLY];
+  // The payload of the activity.
+  ActivityPayload payload = 6;
+}
+
+message ActivityPayload {
+  ActivityMemoCommentPayload memo_comment = 1;
+}
+
+// ActivityMemoCommentPayload represents the payload of a memo comment activity.
+message ActivityMemoCommentPayload {
+  // The memo name of comment.
+  // Refer to `Memo.name`.
+  string memo = 1;
+  // The name of related memo.
+  string related_memo = 2;
+}
+
+message GetActivityRequest {
+  // The name of the activity.
+  // Format: activities/{id}, id is the system generated auto-incremented id.
+  string name = 1;
+}
@@ -0,0 +1,72 @@
+syntax = "proto3";
+
+package memos.api.v1;
+
+import "api/v1/user_service.proto";
+import "google/api/annotations.proto";
+import "google/protobuf/empty.proto";
+
+option go_package = "gen/api/v1";
+
+service AuthService {
+  // GetAuthStatus returns the current auth status of the user.
+  rpc GetAuthStatus(GetAuthStatusRequest) returns (User) {
+    option (google.api.http) = {post: "/api/v1/auth/status"};
+  }
+  // SignIn signs in the user.
+  rpc SignIn(SignInRequest) returns (User) {
+    option (google.api.http) = {post: "/api/v1/auth/signin"};
+  }
+  // SignUp signs up the user with the given username and password.
+  rpc SignUp(SignUpRequest) returns (User) {
+    option (google.api.http) = {post: "/api/v1/auth/signup"};
+  }
+  // SignOut signs out the user.
+  rpc SignOut(SignOutRequest) returns (google.protobuf.Empty) {
+    option (google.api.http) = {post: "/api/v1/auth/signout"};
+  }
+}
+
+message GetAuthStatusRequest {}
+
+message GetAuthStatusResponse {
+  User user = 1;
+}
+
+message SignInRequest {
+  // Provide one authentication method (username/password or SSO).
+  oneof method {
+    // Username and password authentication method.
+    PasswordCredentials password_credentials = 1;
+
+    // SSO provider authentication method.
+    SSOCredentials sso_credentials = 2;
+  }
+  // Whether the session should never expire.
+  bool never_expire = 3;
+}
+
+message PasswordCredentials {
+  // The username to sign in with.
+  string username = 1;
+  // The password to sign in with.
+  string password = 2;
+}
+
+message SSOCredentials {
+  // The ID of the SSO provider.
+  int32 idp_id = 1;
+  // The code to sign in with.
+  string code = 2;
+  // The redirect URI.
+  string redirect_uri = 3;
+}
+
+message SignUpRequest {
+  // The username to sign up with.
+  string username = 1;
+  // The password to sign up with.
+  string password = 2;
+}
+
+message SignOutRequest {}
@@ -0,0 +1,23 @@
+syntax = "proto3";
+
+package memos.api.v1;
+
+option go_package = "gen/api/v1";
+
+enum State {
+  STATE_UNSPECIFIED = 0;
+  NORMAL = 1;
+  ARCHIVED = 2;
+}
+
+// Used internally for obfuscating the page token.
+message PageToken {
+  int32 limit = 1;
+  int32 offset = 2;
+}
+
+enum Direction {
+  DIRECTION_UNSPECIFIED = 0;
+  ASC = 1;
+  DESC = 2;
+}
--- a/Show More
+++ b/Show More