diff --git a/.github/scripts/ci_report.py b/.github/scripts/ci_report.py new file mode 100644 index 0000000..2fbb31a --- /dev/null +++ b/.github/scripts/ci_report.py @@ -0,0 +1,187 @@ +"""Rebuilds the one CI report comment of the pull request whose head commit a finished workflow run tested.""" + +import io +import json +import os +import re +import subprocess +import sys +import zipfile +from datetime import datetime, timezone + +MARKER = "" +FRAGMENT_PREFIX = "ci-report-" +FRAGMENT_FILE = "report.md" +MAX_FRAGMENT_BYTES = 65536 +MAX_SUMMARY_CHARS = 200 +MAX_DETAILS_CHARS = 12000 +MAX_BODY_CHARS = 60000 +MAX_CELL_SUMMARIES = 3 +# a summary that reports a failure, which opens its section when the run failed +FAILING = re.compile( + r"\b([1-9][0-9]* (failed|new findings?|of [0-9]+ scenarios differ)|has a blocking vulnerability)\b") +ICONS = { + "success": "✅ passed", + "failure": "❌ failed", + "cancelled": "⚪ cancelled", + "timed_out": "⌛ timed out", + "skipped": "⏭️ skipped", + "neutral": "➖ neutral", + "action_required": "⚠️ action required", + "stale": "⚪ stale", + "startup_failure": "❌ did not start", +} +ORDER = {"failure": 0, "startup_failure": 0, "timed_out": 0, "action_required": 1, "running": 2, "cancelled": 3} + + +def gh(*args, raw=False): + """Runs gh with the given arguments and returns its output, parsed as JSON unless raw.""" + out = subprocess.run(["gh", *args], check=True, capture_output=True).stdout + return out if raw else json.loads(out or b"null") + + +def paged(path): + """Returns every page of a list endpoint, merged, for endpoints that answer with a list or with one keyed list.""" + pages = gh("api", "--paginate", "--slurp", path) + items = [] + for page in pages: + if isinstance(page, list): + items.extend(page) + else: + items.extend(next(value for value in page.values() if isinstance(value, list))) + return items + + +def pull_requests(repo, sha): + """Returns the numbers of the open pull requests whose head is the given commit.""" + return [pr["number"] for pr in paged(f"repos/{repo}/pulls?state=open&per_page=100") if pr["head"]["sha"] == sha] + + +def latest_runs(repo, sha, own_name): + """Returns the newest pull request run of each workflow for the commit, leaving out this report's own workflow.""" + runs = {} + for run in paged(f"repos/{repo}/actions/runs?head_sha={sha}&event=pull_request&per_page=100"): + if run["name"] == own_name: + continue + kept = runs.get(run["name"]) + if kept is None or (run["created_at"], run["id"]) > (kept["created_at"], kept["id"]): + runs[run["name"]] = run + return list(runs.values()) + + +def defused(text): + """Returns untrusted Markdown that cannot mention anyone, close the report's sections or fake its marker.""" + text = text.replace(MARKER, "") + text = re.sub(r"@(?=[A-Za-z0-9])", "@​", text) + # a fragment's own collapsible sections become bold headings, since they would close the report's section + text = re.sub(r"]*>\s*]*>(.*?)", r"**\1**", text, flags=re.IGNORECASE | re.DOTALL) + text = re.sub(r"", "", text, flags=re.IGNORECASE) + return re.sub(r"<(/?)(details|summary)", r"<\1\2", text, flags=re.IGNORECASE) + + +def fragments(repo, run): + """Returns the report fragments the run uploaded, each as a dict with key, title, summary and details.""" + found = [] + for artifact in paged(f"repos/{repo}/actions/runs/{run['id']}/artifacts?per_page=100"): + if not artifact["name"].startswith(FRAGMENT_PREFIX) or artifact.get("expired"): + continue + zipped = gh("api", f"repos/{repo}/actions/artifacts/{artifact['id']}/zip", raw=True) + archive = zipfile.ZipFile(io.BytesIO(zipped)) + if FRAGMENT_FILE not in archive.namelist(): + continue + key = artifact["name"][len(FRAGMENT_PREFIX):] + data = archive.read(FRAGMENT_FILE)[:MAX_FRAGMENT_BYTES].decode("utf-8", "replace") + lines = defused(data).replace("\r\n", "\n").split("\n") + title = lines[0].strip() or key + summary = (lines[1].strip() if len(lines) > 1 else "")[:MAX_SUMMARY_CHARS] + details = "\n".join(lines[2:]).strip() + if len(details) > MAX_DETAILS_CHARS: + details = details[:MAX_DETAILS_CHARS] + "\n\n…cut here; the run's job summary has the rest." + found.append({"key": key, "title": title, "summary": summary, "details": details}) + return sorted(found, key=lambda fragment: fragment["key"]) + + +def failing_jobs(repo, run): + """Returns the names of the run's jobs that did not succeed or get skipped.""" + jobs = paged(f"repos/{repo}/actions/runs/{run['id']}/jobs?per_page=100") + return [job["name"] for job in jobs if job.get("conclusion") not in (None, "success", "skipped", "neutral")] + + +def state(run): + """Returns the run's conclusion, or "running" while it has none.""" + return run["conclusion"] if run["status"] == "completed" and run["conclusion"] else "running" + + +def label(run, fragment): + """Returns the fragment's title, or nothing when the title only repeats its workflow's name.""" + return "" if fragment["title"].casefold() == run["name"].casefold() else fragment["title"] + + +def joined(*parts): + """Returns the non-empty parts joined by a colon.""" + return ": ".join(part for part in parts if part) + + +def body(repo, sha, runs): + """Returns the comment: a table with one row per workflow, then a collapsible section per fragment.""" + rows, sections = [], [] + for run in sorted(runs, key=lambda run: (ORDER.get(state(run), 4), run["name"].lower())): + result = state(run) + found = fragments(repo, run) if result != "running" else [] + parts = [joined(label(run, fragment), fragment["summary"]) for fragment in found if fragment["summary"]] + if len(parts) > MAX_CELL_SUMMARIES: + parts = parts[:MAX_CELL_SUMMARIES] + [f"{len(parts) - MAX_CELL_SUMMARIES} more below"] + failed = failing_jobs(repo, run) if result in ("failure", "timed_out") else [] + if failed: + parts.insert(0, "Failed: " + ", ".join(failed)) + summary = "; ".join(parts) + icon = "⏳ running" if result == "running" else ICONS.get(result, result) + cell = summary.replace("|", "\\|") + rows.append(f"| [{run['name']}]({run['html_url']}) | {icon} | {cell} |") + for fragment in found: + opened = " open" if result in ("failure", "timed_out") and FAILING.search(fragment["summary"]) else "" + heading = joined(run["name"], label(run, fragment)) + if fragment["summary"]: + heading += f", {fragment['summary']}" + details = fragment["details"] or "No details." + sections.append(f"\n{heading}\n\n{details}\n\n\n") + when = datetime.now(timezone.utc).strftime("%Y-%m-%d %H:%M UTC") + head = [MARKER, "### CI report", "", "| Check | Result | Summary |", "| --- | --- | --- |", *rows, ""] + tail = [f"For {sha[:7]}, updated {when}. Each check's run page has its full log."] + text = "\n".join(head + sections + tail) + while len(text) > MAX_BODY_CHARS and sections: + sections.pop() + text = "\n".join(head + sections + ["…more sections did not fit in one comment.", ""] + tail) + return text + + +def publish(repo, number, text): + """Updates the pull request's report comment, or posts it when there is none yet.""" + comments = paged(f"repos/{repo}/issues/{number}/comments?per_page=100") + mine = [comment for comment in comments + if comment["user"]["login"] == "github-actions[bot]" and comment["body"].startswith(MARKER)] + if mine: + gh("api", "--method", "PATCH", f"repos/{repo}/issues/comments/{mine[-1]['id']}", "-f", f"body={text}") + else: + gh("api", "--method", "POST", f"repos/{repo}/issues/{number}/comments", "-f", f"body={text}") + + +def main(): + """Rebuilds the report for the commit in HEAD_SHA, or prints it when DRY_RUN is set.""" + repo, sha = os.environ["REPO"], os.environ["HEAD_SHA"] + numbers = [int(os.environ["PR"])] if os.environ.get("PR") else pull_requests(repo, sha) + if not numbers: + print(f"No open pull request has {sha} as its head, so there is nothing to report on.") + return 0 + text = body(repo, sha, latest_runs(repo, sha, os.environ.get("OWN_WORKFLOW", "CI report"))) + if os.environ.get("DRY_RUN"): + print(text) + return 0 + for number in numbers: + publish(repo, number, text) + print(f"Updated the CI report of #{number}.") + return 0 + + +if __name__ == "__main__": + sys.exit(main()) diff --git a/.github/scripts/public_api.mjs b/.github/scripts/public_api.mjs new file mode 100644 index 0000000..08424b6 --- /dev/null +++ b/.github/scripts/public_api.mjs @@ -0,0 +1,70 @@ +// Prints the public surface of a JavaScript SDK module as sorted " " lines, so two versions can be compared. +// Usage: node public_api.mjs = [= ...] +// Each expression is evaluated with `sdk` bound to the module's export and is listed under its name, for example +// Countly=sdk or Instance='new sdk.CountlyClass({ app_key: "key", url: "https://example.invalid" })'. +import { writeSync } from "node:fs"; +import { pathToFileURL } from "node:url"; +import { resolve } from "node:path"; + +const MAX_DEPTH = 4; + +/** + * Returns the kind printed for a value: its typeof, with null and arrays told apart. + * @param {*} value the value to describe + * @returns {string} "null", "array" or the typeof of the value + */ +function kindOf(value) { + if (value === null) { + return "null"; + } + return Array.isArray(value) ? "array" : typeof value; +} + +/** + * Adds a line for the value at path and, for objects and functions, for each public member below it. + * Names that start with an underscore are private by convention and skipped, and array elements are data. + * @param {*} value the value to describe + * @param {string} path the dotted path that reaches the value + * @param {string[]} lines the lines collected so far + * @param {WeakSet} seen the objects already described, so cycles end + * @param {number} depth how many members deep the value is + */ +function describe(value, path, lines, seen, depth) { + const kind = kindOf(value); + lines.push(`${path} ${kind}`); + if ((kind !== "object" && kind !== "function") || depth >= MAX_DEPTH || seen.has(value)) { + return; + } + seen.add(value); + for (const key of Object.keys(value)) { + if (!key.startsWith("_")) { + describe(value[key], `${path}.${key}`, lines, seen, depth + 1); + } + } + if (kind === "function" && value.prototype) { + for (const key of Object.getOwnPropertyNames(value.prototype)) { + if (key !== "constructor" && !key.startsWith("_")) { + lines.push(`${path}.prototype.${key} ${kindOf(value.prototype[key])}`); + } + } + } +} + +const [modulePath, ...roots] = process.argv.slice(2); +if (!modulePath || roots.length === 0) { + console.error("Usage: node public_api.mjs = [...]"); + process.exit(2); +} +const loaded = await import(pathToFileURL(resolve(modulePath)).href); +const sdk = loaded.default ?? loaded; +const lines = []; +for (const root of roots) { + const separator = root.indexOf("="); + const name = root.slice(0, separator); + const value = new Function("sdk", `return (${root.slice(separator + 1)});`)(sdk); + describe(value, name, lines, new WeakSet(), 0); +} +// A synchronous write, because the exit below would cut off an asynchronous write to a pipe. +writeSync(1, [...new Set(lines)].sort().join("\n") + "\n"); +// The SDK may have started timers (an instance's heartbeat, for example), so the process ends here. +process.exit(0); diff --git a/.github/scripts/public_api_record.sh b/.github/scripts/public_api_record.sh new file mode 100644 index 0000000..88f5c95 --- /dev/null +++ b/.github/scripts/public_api_record.sh @@ -0,0 +1,37 @@ +#!/usr/bin/env bash +# Compares the public API this run extracted with the record committed in the repository. On a difference it lists the +# changed lines in the job summary, copies the extracted API to $RUNNER_TEMP/public-api-record/ under the record's path, +# for the workflow to upload, and fails: a deliberate change is committed together with a changelog line. +# $@ pairs "=" +set -euo pipefail +out="$RUNNER_TEMP/public-api-record" +status=0 +current="$RUNNER_TEMP/public-api-current.txt" +recorded="$RUNNER_TEMP/public-api-recorded.txt" +for pair in "$@"; do + extracted=${pair%%=*} + record=${pair#*=} + # Line endings do not count: .NET writes CRLF on Windows, and a Windows checkout can give the record CRLF too. + tr -d '\r' < "$extracted" > "$current" + if [ -f "$record" ] && tr -d '\r' < "$record" | cmp -s - "$current"; then + echo "The public API is the one $record records." + continue + fi + status=1 + mkdir -p "$out/$(dirname "$record")" + cp "$current" "$out/$record" + { + printf '### The public API differs from %s\n\n' "$record" + printf "Commit \`%s\` from the \`public-api-record\` artifact of this run, with a changelog line for the change.\n\n" "$record" + if [ -f "$record" ]; then + printf '```diff\n' + tr -d '\r' < "$record" > "$recorded" + diff -u "$recorded" "$current" | tail -n +3 | head -n 300 || true + printf '```\n\n' + else + printf 'There is no record yet.\n\n' + fi + } >> "$GITHUB_STEP_SUMMARY" + echo "::error title=Public API record::The public API differs from $record. Commit the file from this run's public-api-record artifact and add a changelog line." +done +exit "$status" diff --git a/.github/scripts/public_api_report.sh b/.github/scripts/public_api_report.sh new file mode 100644 index 0000000..6c32e49 --- /dev/null +++ b/.github/scripts/public_api_report.sh @@ -0,0 +1,59 @@ +#!/usr/bin/env bash +# Writes the report of a pull request's public API changes to the job summary, to the step output "report", which +# the workflow's comment job posts on the pull request, and to $RUNNER_TEMP/ci-report-public-api/report.md, the +# fragment the CI report comment shows. The comment and the fragment list at most 200 lines per section. +# $1 a file with one removed or changed declaration per line +# $2 a file with one declaration per line that the pull request adds to the public API +set -euo pipefail +breaking=$1 +added=$2 +marker='' + +# Prints a section titled $1 and explained by $2 with the lines of file $3, at most $4 of them when $4 is not 0. +section() { + local count + count=$(grep -c . "$3" || true) + [ "$count" -gt 0 ] || return 0 + printf '**%s: %s.** %s\n\n```\n' "$1" "$count" "$2" + if [ "$4" -gt 0 ]; then + head -n "$4" "$3" + else + cat "$3" + fi + printf '```\n' + if [ "$4" -gt 0 ] && [ "$count" -gt "$4" ]; then + printf '\n%s more in the job summary.\n' "$((count - $4))" + fi + printf '\n' +} + +# Prints the whole report, with at most $1 lines per section when $1 is not 0. +report() { + printf '%s\n### Public API changes\n\n' "$marker" + if ! grep -q . "$breaking" && ! grep -q . "$added"; then + printf 'No public API change.\n' + return + fi + section 'Removed or changed' 'Each needs a CHANGELOG entry that marks it as a breaking change.' "$breaking" "$1" + section 'Added' 'Check that each one is meant to be public.' "$added" "$1" +} + +report 0 >> "$GITHUB_STEP_SUMMARY" +delimiter="EOF_$(od -An -N8 -tx1 /dev/urandom | tr -d ' \n')" +{ + echo "report<<$delimiter" + report 200 + echo "$delimiter" +} >> "$GITHUB_OUTPUT" + +removed=$(grep -c . "$breaking" || true) +new=$(grep -c . "$added" || true) +summary='No public API change' +if [ "$removed" -gt 0 ] || [ "$new" -gt 0 ]; then + summary="$removed removed or changed, $new added" +fi +mkdir -p "$RUNNER_TEMP/ci-report-public-api" +{ + printf 'Public API\n%s\n' "$summary" + report 200 | tail -n +3 +} > "$RUNNER_TEMP/ci-report-public-api/report.md" diff --git a/.github/workflows/api-changelog.yml b/.github/workflows/api-changelog.yml new file mode 100644 index 0000000..c7b377c --- /dev/null +++ b/.github/workflows/api-changelog.yml @@ -0,0 +1,53 @@ +name: Public API changelog + +# A pull request that changes or removes a record of the public API, or of the requests the SDK sends, must also change +# the CHANGELOG.md that API_FILES pairs it with, so that the release notes tell integrators about every such change. A +# record the pull request adds needs no line. A path ending in "/" stands for every file under it. The API and request +# checks keep each record in step with the SDK. +on: + pull_request: + branches: [master, staging] + +concurrency: + group: ${{ github.workflow }}-${{ github.ref }} + cancel-in-progress: true + +permissions: + pull-requests: read # to list the files the pull request changes + +jobs: + changelog: + name: A public API or request change comes with a CHANGELOG line + runs-on: ubuntu-24.04 + steps: + - name: Check the files the pull request changes + env: + GH_TOKEN: ${{ github.token }} + REPO: ${{ github.repository }} + PR: ${{ github.event.pull_request.number }} + API_FILES: api/countly-sdk-nodejs.api=CHANGELOG.md api/requests/=CHANGELOG.md + run: | + changed=$(gh api "repos/$REPO/pulls/$PR/files" --paginate --jq '.[] | select(.status != "added") | .filename') + changes() { + case "$1" in + */) printf '%s\n' "$changed" | awk -v prefix="$1" 'index($0, prefix) == 1 { found = 1 } END { exit !found }' ;; + *) printf '%s\n' "$changed" | grep -qxF "$1" ;; + esac + } + recorded_changed=no + for pair in $API_FILES; do + record=${pair%%=*} + changelog=${pair#*=} + if changes "$record"; then + recorded_changed=yes + if ! changes "$changelog"; then + echo "::error::This pull request changes $record, which records the public API or the requests the SDK sends, but not $changelog. Add a line that tells integrators what changed." + exit 1 + fi + fi + done + if [ "$recorded_changed" = yes ]; then + echo "The recorded public API or requests change, and the CHANGELOG changes with them." + else + echo "This pull request changes neither the recorded public API nor the recorded requests." + fi diff --git a/.github/workflows/ci-report.yml b/.github/workflows/ci-report.yml new file mode 100644 index 0000000..31bf46a --- /dev/null +++ b/.github/workflows/ci-report.yml @@ -0,0 +1,45 @@ +name: CI report + +# Keeps one comment on each pull request with the result of every workflow that ran for its head commit, a table +# first, then one collapsible section per report fragment (an artifact named ci-report- holding report.md: a +# title line, a summary line, then the details). It runs from the default branch after each listed workflow, so a +# fork's pull request gets its report too: nothing from the pull request is checked out or run, and the fragments +# are read as untrusted text. +on: # zizmor: ignore[dangerous-triggers] the job reads the pull request's artifacts as text and never runs its code + workflow_run: + workflows: + - "CodeQL" + - "Node.js CI" + - "Public API changelog" + - "Public API changes" + types: [completed] + +permissions: {} + +concurrency: + group: ci-report-${{ github.event.workflow_run.head_sha }} + cancel-in-progress: false + +jobs: + report: + name: Update the CI report + if: github.event.workflow_run.event == 'pull_request' + runs-on: ubuntu-24.04 + permissions: + actions: read + contents: read + pull-requests: write + steps: + - name: Check out the report script + uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1 + with: + persist-credentials: false + sparse-checkout: .github/scripts/ci_report.py + sparse-checkout-cone-mode: false + + - name: Rebuild the report comment + env: + GH_TOKEN: ${{ github.token }} + REPO: ${{ github.repository }} + HEAD_SHA: ${{ github.event.workflow_run.head_sha }} + run: python3 .github/scripts/ci_report.py diff --git a/.github/workflows/public_api.yml b/.github/workflows/public_api.yml new file mode 100644 index 0000000..7fcb922 --- /dev/null +++ b/.github/workflows/public_api.yml @@ -0,0 +1,109 @@ +name: Public API changes + +on: + pull_request: + +permissions: + contents: read + +concurrency: + group: ${{ github.workflow }}-${{ github.ref }} + cancel-in-progress: true + +jobs: + api: + name: Breaking changes + outputs: + report: ${{ steps.report.outputs.report }} + runs-on: ubuntu-24.04 + steps: + - name: Checkout SDK code + uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1 + with: + fetch-depth: 2 + persist-credentials: false + + - name: Set up Node.js + uses: actions/setup-node@949feb2413d6458794dcd2491c4babbbce0c15c1 # v7.1.0 + with: + node-version: 24 + + # The first parent of the pull request's merge commit is the base branch it merges into. + - name: Compare the public API with the base branch + id: compare + run: | + git worktree add "$RUNNER_TEMP/base" HEAD^1 + roots=( + 'Countly=sdk' + 'Bulk=new sdk.Bulk({ app_key: "key", url: "https://example.invalid", persist_queue: false })' + 'BulkUser=new sdk.Bulk({ app_key: "key", url: "https://example.invalid", persist_queue: false }).add_user({ device_id: "id" })' + ) + node .github/scripts/public_api.mjs "$RUNNER_TEMP/base/lib/countly.js" "${roots[@]}" > "$RUNNER_TEMP/base.txt" + node .github/scripts/public_api.mjs lib/countly.js "${roots[@]}" > "$RUNNER_TEMP/head.txt" + LC_ALL=C comm -23 "$RUNNER_TEMP/base.txt" "$RUNNER_TEMP/head.txt" | sed 's/^/Removed or changed: /' > "$RUNNER_TEMP/breaking.txt" + LC_ALL=C comm -13 "$RUNNER_TEMP/base.txt" "$RUNNER_TEMP/head.txt" > "$RUNNER_TEMP/added.txt" + + - name: Report the public API changes + id: report + run: bash .github/scripts/public_api_report.sh "$RUNNER_TEMP/breaking.txt" "$RUNNER_TEMP/added.txt" + + - name: Upload the CI report fragment + if: ${{ !cancelled() && steps.report.outcome == 'success' }} + uses: actions/upload-artifact@cf430e030ddbb5b0abf93d22962f4752f3646cd9 # v7.0.2 + with: + name: ci-report-public-api + path: ${{ runner.temp }}/ci-report-public-api + if-no-files-found: ignore + + - name: Require a CHANGELOG entry for breaking changes + run: | + if [ ! -s "$RUNNER_TEMP/breaking.txt" ]; then + exit 0 + fi + if git diff --quiet HEAD^1 HEAD -- CHANGELOG.md; then + echo "::error title=Breaking API change::This pull request breaks the public API without a CHANGELOG.md entry. The job summary lists each break." + exit 1 + fi + echo "::warning title=Breaking API change::This pull request breaks the public API. Check that CHANGELOG.md marks it as a breaking change." + + # The committed record keeps every change to the public API visible in the pull request's diff. + - name: Compare the public API with its record + id: record + if: ${{ !cancelled() && steps.compare.outcome == 'success' }} + run: > + bash .github/scripts/public_api_record.sh + "$RUNNER_TEMP/head.txt=api/countly-sdk-nodejs.api" + + - name: Upload the new record + if: ${{ !cancelled() && steps.record.outcome == 'failure' }} + uses: actions/upload-artifact@cf430e030ddbb5b0abf93d22962f4752f3646cd9 # v7.0.2 + with: + name: public-api-record + path: ${{ runner.temp }}/public-api-record + + comment: + name: Comment the public API changes + needs: api + # A fork's or Dependabot's pull request only gets a read-only token, so its report stays in the job summary. + if: >- + always() && needs.api.outputs.report != '' && + github.event.pull_request.head.repo.full_name == github.repository && + github.event.pull_request.user.login != 'dependabot[bot]' + runs-on: ubuntu-24.04 + permissions: + pull-requests: write + steps: + - name: Post or update the comment + env: + GH_TOKEN: ${{ github.token }} + REPO: ${{ github.repository }} + PR: ${{ github.event.pull_request.number }} + REPORT: ${{ needs.api.outputs.report }} + run: | + id=$(gh api --paginate "repos/$REPO/issues/$PR/comments" --jq \ + '.[] | select(.user.login == "github-actions[bot]" and (.body | startswith(""))) | .id' | tail -n 1) + if [ -n "$id" ]; then + gh api --method PATCH "repos/$REPO/issues/comments/$id" -f "body=$REPORT" > /dev/null + elif ! grep -qx 'No public API change.' <<< "$REPORT"; then + gh api --method POST "repos/$REPO/issues/$PR/comments" -f "body=$REPORT" > /dev/null + fi diff --git a/api/countly-sdk-nodejs.api b/api/countly-sdk-nodejs.api new file mode 100644 index 0000000..cca35ef --- /dev/null +++ b/api/countly-sdk-nodejs.api @@ -0,0 +1,119 @@ +Bulk object +Bulk.add_bulk_request function +Bulk.add_event function +Bulk.add_request function +Bulk.add_user function +Bulk.conf object +Bulk.conf.app_key string +Bulk.conf.bulk_size number +Bulk.conf.debug boolean +Bulk.conf.fail_timeout number +Bulk.conf.force_post boolean +Bulk.conf.http_options null +Bulk.conf.interval number +Bulk.conf.maxBreadcrumbCount number +Bulk.conf.maxKeyLength number +Bulk.conf.maxSegmentationValues number +Bulk.conf.maxStackTraceLineLength number +Bulk.conf.maxStackTraceLinesPerThread number +Bulk.conf.maxValueSize number +Bulk.conf.max_events number +Bulk.conf.persist_queue boolean +Bulk.conf.request_timeout number +Bulk.conf.salt null +Bulk.conf.session_update number +Bulk.conf.storage_type string +Bulk.conf.url string +Bulk.queue_size function +Bulk.start function +Bulk.stop function +BulkUser object +BulkUser.add_consent function +BulkUser.add_event function +BulkUser.begin_session function +BulkUser.check_consent function +BulkUser.custom_increment function +BulkUser.custom_increment_by function +BulkUser.custom_max function +BulkUser.custom_min function +BulkUser.custom_multiply function +BulkUser.custom_pull function +BulkUser.custom_push function +BulkUser.custom_push_unique function +BulkUser.custom_save function +BulkUser.custom_set function +BulkUser.custom_set_once function +BulkUser.custom_unset function +BulkUser.group_features function +BulkUser.remove_consent function +BulkUser.remove_consent_internal function +BulkUser.report_conversion function +BulkUser.report_crash function +BulkUser.report_feedback function +BulkUser.report_trace function +BulkUser.report_view function +BulkUser.user_details function +Countly object +Countly.Bulk function +Countly.Bulk.StorageTypes object +Countly.DeviceIdType object +Countly.DeviceIdType.DEVELOPER_SUPPLIED number +Countly.DeviceIdType.SDK_GENERATED number +Countly.StorageTypes object +Countly.StorageTypes.FILE string +Countly.StorageTypes.MEMORY string +Countly.add_consent function +Countly.add_event function +Countly.add_log function +Countly.begin_session function +Countly.change_app_key function +Countly.change_id function +Countly.change_server_url function +Countly.check_any_consent function +Countly.check_consent function +Countly.end_event function +Countly.end_session function +Countly.features array +Countly.fetch_remote_config function +Countly.flush function +Countly.flush_queues function +Countly.get_device_id function +Countly.get_device_id_type function +Countly.get_remote_config function +Countly.group_features function +Countly.halt function +Countly.init function +Countly.log_error function +Countly.remove_consent function +Countly.remove_consent_internal function +Countly.remove_different_app_keys_from_queue function +Countly.replace_all_app_keys_in_queue_with_current_app_key function +Countly.report_app_start function +Countly.report_conversion function +Countly.report_feedback function +Countly.report_trace function +Countly.request function +Countly.session_duration function +Countly.setLoggingEnabled function +Countly.set_id function +Countly.set_location function +Countly.start_event function +Countly.start_time function +Countly.stop_time function +Countly.track_errors function +Countly.track_pageview function +Countly.track_view function +Countly.userData object +Countly.userData.increment function +Countly.userData.increment_by function +Countly.userData.max function +Countly.userData.min function +Countly.userData.multiply function +Countly.userData.pull function +Countly.userData.push function +Countly.userData.push_unique function +Countly.userData.save function +Countly.userData.set function +Countly.userData.set_once function +Countly.userData.unset function +Countly.user_details function diff --git a/api/requests/consent.json b/api/requests/consent.json new file mode 100644 index 0000000..fcc5a21 --- /dev/null +++ b/api/requests/consent.json @@ -0,0 +1,165 @@ +[ + { + "path": "/o/sdk", + "params": { + "app_key": "parity-app-key", + "av": "", + "device_id": "parity-device-001", + "dow": "", + "hour": "", + "method": "sc", + "sdk_name": "javascript_native_nodejs", + "sdk_version": "", + "t": "0", + "timestamp": "", + "tz": "" + } + }, + { + "path": "/i", + "params": { + "app_key": "parity-app-key", + "av": "", + "device_id": "parity-device-001", + "dow": "", + "hc": { + "bom": "", + "cbom": "", + "el": "", + "em": "", + "fu": "", + "lc": "", + "sc": "", + "wl": "" + }, + "hour": "", + "metrics": { + "_app_version": "" + }, + "sdk_name": "javascript_native_nodejs", + "sdk_version": "", + "t": "0", + "timestamp": "", + "tz": "" + } + }, + { + "path": "/i", + "params": { + "app_key": "parity-app-key", + "begin_session": "1", + "device_id": "parity-device-001", + "dow": "", + "hour": "", + "location": "", + "metrics": { + "_app_version": "", + "_os": "", + "_os_version": "" + }, + "sdk_name": "javascript_native_nodejs", + "sdk_version": "", + "t": "0", + "timestamp": "", + "tz": "" + } + }, + { + "path": "/i", + "params": { + "app_key": "parity-app-key", + "device_id": "parity-device-001", + "dow": "", + "events": [ + { + "count": 1, + "dow": "", + "hour": "", + "key": "consented", + "segmentation": {}, + "timestamp": "" + } + ], + "hour": "", + "location": "", + "sdk_name": "javascript_native_nodejs", + "sdk_version": "", + "t": "0", + "timestamp": "", + "tz": "" + } + }, + { + "path": "/i", + "params": { + "app_key": "parity-app-key", + "consent": { + "apm": false, + "attribution": false, + "crashes": false, + "events": true, + "feedback": false, + "location": false, + "remote-config": false, + "sessions": true, + "star-rating": false, + "users": false, + "views": false + }, + "device_id": "parity-device-001", + "dow": "", + "hour": "", + "location": "", + "sdk_name": "javascript_native_nodejs", + "sdk_version": "", + "t": "0", + "timestamp": "", + "tz": "" + } + }, + { + "path": "/i", + "params": { + "app_key": "parity-app-key", + "device_id": "parity-device-001", + "dow": "", + "end_session": "1", + "hour": "", + "location": "", + "sdk_name": "javascript_native_nodejs", + "sdk_version": "", + "session_duration": "", + "t": "0", + "timestamp": "", + "tz": "" + } + }, + { + "path": "/i", + "params": { + "app_key": "parity-app-key", + "consent": { + "apm": false, + "attribution": false, + "crashes": false, + "events": false, + "feedback": false, + "location": false, + "remote-config": false, + "sessions": true, + "star-rating": false, + "users": false, + "views": false + }, + "device_id": "parity-device-001", + "dow": "", + "hour": "", + "location": "", + "sdk_name": "javascript_native_nodejs", + "sdk_version": "", + "t": "0", + "timestamp": "", + "tz": "" + } + } +] diff --git a/api/requests/crash.json b/api/requests/crash.json new file mode 100644 index 0000000..f60ec35 --- /dev/null +++ b/api/requests/crash.json @@ -0,0 +1,74 @@ +[ + { + "path": "/o/sdk", + "params": { + "app_key": "parity-app-key", + "av": "", + "device_id": "parity-device-001", + "dow": "", + "hour": "", + "method": "sc", + "sdk_name": "javascript_native_nodejs", + "sdk_version": "", + "t": "0", + "timestamp": "", + "tz": "" + } + }, + { + "path": "/i", + "params": { + "app_key": "parity-app-key", + "av": "", + "device_id": "parity-device-001", + "dow": "", + "hc": { + "bom": "", + "cbom": "", + "el": "", + "em": "", + "fu": "", + "lc": "", + "sc": "", + "wl": "" + }, + "hour": "", + "metrics": { + "_app_version": "" + }, + "sdk_name": "javascript_native_nodejs", + "sdk_version": "", + "t": "0", + "timestamp": "", + "tz": "" + } + }, + { + "path": "/i", + "params": { + "app_key": "parity-app-key", + "crash": { + "_app_version": "0.0", + "_custom": { + "tier": "gold" + }, + "_error": "", + "_javascript": true, + "_logs": "breadcrumb one", + "_nonfatal": true, + "_not_os_specific": true, + "_os": "", + "_os_version": "", + "_run": "" + }, + "device_id": "parity-device-001", + "dow": "", + "hour": "", + "sdk_name": "javascript_native_nodejs", + "sdk_version": "", + "t": "0", + "timestamp": "", + "tz": "" + } + } +] diff --git a/api/requests/device-id.json b/api/requests/device-id.json new file mode 100644 index 0000000..5b85ed3 --- /dev/null +++ b/api/requests/device-id.json @@ -0,0 +1,213 @@ +[ + { + "path": "/o/sdk", + "params": { + "app_key": "parity-app-key", + "av": "", + "device_id": "parity-device-001", + "dow": "", + "hour": "", + "method": "sc", + "sdk_name": "javascript_native_nodejs", + "sdk_version": "", + "t": "0", + "timestamp": "", + "tz": "" + } + }, + { + "path": "/i", + "params": { + "app_key": "parity-app-key", + "av": "", + "device_id": "parity-device-001", + "dow": "", + "hc": { + "bom": "", + "cbom": "", + "el": "", + "em": "", + "fu": "", + "lc": "", + "sc": "", + "wl": "" + }, + "hour": "", + "metrics": { + "_app_version": "" + }, + "sdk_name": "javascript_native_nodejs", + "sdk_version": "", + "t": "0", + "timestamp": "", + "tz": "" + } + }, + { + "path": "/i", + "params": { + "app_key": "parity-app-key", + "begin_session": "1", + "device_id": "parity-device-001", + "dow": "", + "hour": "", + "metrics": { + "_app_version": "", + "_os": "", + "_os_version": "" + }, + "sdk_name": "javascript_native_nodejs", + "sdk_version": "", + "t": "0", + "timestamp": "", + "tz": "" + } + }, + { + "path": "/i", + "params": { + "app_key": "parity-app-key", + "device_id": "parity-device-002", + "dow": "", + "hour": "", + "old_device_id": "parity-device-001", + "sdk_name": "javascript_native_nodejs", + "sdk_version": "", + "t": "0", + "timestamp": "", + "tz": "" + } + }, + { + "path": "/o/sdk", + "params": { + "app_key": "parity-app-key", + "av": "", + "device_id": "parity-device-002", + "dow": "", + "hour": "", + "method": "sc", + "sdk_name": "javascript_native_nodejs", + "sdk_version": "", + "t": "0", + "timestamp": "", + "tz": "" + } + }, + { + "path": "/i", + "params": { + "app_key": "parity-app-key", + "device_id": "parity-device-002", + "dow": "", + "events": [ + { + "count": 1, + "dow": "", + "hour": "", + "key": "after_merge", + "segmentation": {}, + "timestamp": "" + } + ], + "hour": "", + "sdk_name": "javascript_native_nodejs", + "sdk_version": "", + "t": "0", + "timestamp": "", + "tz": "" + } + }, + { + "path": "/o/sdk", + "params": { + "app_key": "parity-app-key", + "av": "", + "device_id": "parity-device-003", + "dow": "", + "hour": "", + "method": "sc", + "sdk_name": "javascript_native_nodejs", + "sdk_version": "", + "t": "0", + "timestamp": "", + "tz": "" + } + }, + { + "path": "/i", + "params": { + "app_key": "parity-app-key", + "device_id": "parity-device-002", + "dow": "", + "end_session": "1", + "hour": "", + "sdk_name": "javascript_native_nodejs", + "sdk_version": "", + "session_duration": "", + "t": "0", + "timestamp": "", + "tz": "" + } + }, + { + "path": "/i", + "params": { + "app_key": "parity-app-key", + "begin_session": "1", + "device_id": "parity-device-003", + "dow": "", + "hour": "", + "metrics": { + "_app_version": "", + "_os": "", + "_os_version": "" + }, + "sdk_name": "javascript_native_nodejs", + "sdk_version": "", + "t": "0", + "timestamp": "", + "tz": "" + } + }, + { + "path": "/i", + "params": { + "app_key": "parity-app-key", + "device_id": "parity-device-003", + "dow": "", + "end_session": "1", + "hour": "", + "sdk_name": "javascript_native_nodejs", + "sdk_version": "", + "session_duration": "", + "t": "0", + "timestamp": "", + "tz": "" + } + }, + { + "path": "/i", + "params": { + "app_key": "parity-app-key", + "device_id": "parity-device-003", + "dow": "", + "events": [ + { + "count": 1, + "dow": "", + "hour": "", + "key": "after_new_id", + "segmentation": {}, + "timestamp": "" + } + ], + "hour": "", + "sdk_name": "javascript_native_nodejs", + "sdk_version": "", + "t": "0", + "timestamp": "", + "tz": "" + } + } +] diff --git a/api/requests/parity.json b/api/requests/parity.json new file mode 100644 index 0000000..c2d880b --- /dev/null +++ b/api/requests/parity.json @@ -0,0 +1,202 @@ +[ + { + "path": "/o/sdk", + "params": { + "app_key": "parity-app-key", + "av": "", + "device_id": "parity-device-001", + "dow": "", + "hour": "", + "method": "sc", + "sdk_name": "javascript_native_nodejs", + "sdk_version": "", + "t": "0", + "timestamp": "", + "tz": "" + } + }, + { + "path": "/i", + "params": { + "app_key": "parity-app-key", + "av": "", + "device_id": "parity-device-001", + "dow": "", + "hc": { + "bom": "", + "cbom": "", + "el": "", + "em": "", + "fu": "", + "lc": "", + "sc": "", + "wl": "" + }, + "hour": "", + "metrics": { + "_app_version": "" + }, + "sdk_name": "javascript_native_nodejs", + "sdk_version": "", + "t": "0", + "timestamp": "", + "tz": "" + } + }, + { + "path": "/i", + "params": { + "app_key": "parity-app-key", + "begin_session": "1", + "device_id": "parity-device-001", + "dow": "", + "hour": "", + "metrics": { + "_app_version": "", + "_os": "", + "_os_version": "" + }, + "sdk_name": "javascript_native_nodejs", + "sdk_version": "", + "t": "0", + "timestamp": "", + "tz": "" + } + }, + { + "path": "/i", + "params": { + "app_key": "parity-app-key", + "device_id": "parity-device-001", + "dow": "", + "hour": "", + "sdk_name": "javascript_native_nodejs", + "sdk_version": "", + "t": "0", + "timestamp": "", + "tz": "", + "user_details": { + "byear": 1980, + "custom": { + "age": 30, + "tier": "gold" + }, + "email": "john@example.com", + "gender": "M", + "name": "John Doe", + "organization": "Countly", + "phone": "1234567890", + "picture": "https://example.com/picture.jpg", + "username": "john_d" + } + } + }, + { + "path": "/i", + "params": { + "app_key": "parity-app-key", + "device_id": "parity-device-001", + "dow": "", + "hour": "", + "sdk_name": "javascript_native_nodejs", + "sdk_version": "", + "session_duration": "", + "t": "0", + "timestamp": "", + "tz": "" + } + }, + { + "path": "/i", + "params": { + "app_key": "parity-app-key", + "device_id": "parity-device-001", + "dow": "", + "end_session": "1", + "hour": "", + "sdk_name": "javascript_native_nodejs", + "sdk_version": "", + "session_duration": "", + "t": "0", + "timestamp": "", + "tz": "" + } + }, + { + "path": "/i", + "params": { + "app_key": "parity-app-key", + "device_id": "parity-device-001", + "dow": "", + "events": [ + { + "count": 2, + "dow": "", + "dur": 5, + "hour": "", + "key": "purchase", + "segmentation": { + "boolList": [ + true, + false, + true + ], + "doubleList": [ + 1.1, + 2.2, + 3.3 + ], + "hashirama": -2147483647, + "intList": [ + 1, + 2, + 3 + ], + "itachi": 1.7976931348623157e+308, + "kakaski": 5e-324, + "mapList": [ + { + "key1": "value1", + "key2": 2 + }, + { + "key1": "value2", + "key2": 3 + }, + { + "key1": "value3", + "key2": 4 + } + ], + "mixedList": [ + "value1", + 2, + 3.3, + true + ], + "nar": "uto", + "sakura": false, + "sasuke": 2147483647, + "stringList": [ + "value1", + "value2", + "value3" + ], + "tobi": { + "obito": "uchiha", + "zetsu": "white" + } + }, + "sum": 9.99, + "timestamp": "" + } + ], + "hour": "", + "sdk_name": "javascript_native_nodejs", + "sdk_version": "", + "t": "0", + "timestamp": "", + "tz": "" + } + } +] diff --git a/api/requests/views.json b/api/requests/views.json new file mode 100644 index 0000000..0a97272 --- /dev/null +++ b/api/requests/views.json @@ -0,0 +1,147 @@ +[ + { + "path": "/o/sdk", + "params": { + "app_key": "parity-app-key", + "av": "", + "device_id": "parity-device-001", + "dow": "", + "hour": "", + "method": "sc", + "sdk_name": "javascript_native_nodejs", + "sdk_version": "", + "t": "0", + "timestamp": "", + "tz": "" + } + }, + { + "path": "/i", + "params": { + "app_key": "parity-app-key", + "av": "", + "device_id": "parity-device-001", + "dow": "", + "hc": { + "bom": "", + "cbom": "", + "el": "", + "em": "", + "fu": "", + "lc": "", + "sc": "", + "wl": "" + }, + "hour": "", + "metrics": { + "_app_version": "" + }, + "sdk_name": "javascript_native_nodejs", + "sdk_version": "", + "t": "0", + "timestamp": "", + "tz": "" + } + }, + { + "path": "/i", + "params": { + "app_key": "parity-app-key", + "begin_session": "1", + "device_id": "parity-device-001", + "dow": "", + "hour": "", + "metrics": { + "_app_version": "", + "_os": "", + "_os_version": "" + }, + "sdk_name": "javascript_native_nodejs", + "sdk_version": "", + "t": "0", + "timestamp": "", + "tz": "" + } + }, + { + "path": "/i", + "params": { + "app_key": "parity-app-key", + "device_id": "parity-device-001", + "dow": "", + "end_session": "1", + "hour": "", + "sdk_name": "javascript_native_nodejs", + "sdk_version": "", + "session_duration": "", + "t": "0", + "timestamp": "", + "tz": "" + } + }, + { + "path": "/i", + "params": { + "app_key": "parity-app-key", + "device_id": "parity-device-001", + "dow": "", + "events": [ + { + "count": 1, + "dow": "", + "hour": "", + "key": "[CLY]_view", + "segmentation": { + "name": "Home", + "segment": "", + "source": "scenario", + "visit": 1 + }, + "timestamp": "" + }, + { + "count": 1, + "dow": "", + "dur": "", + "hour": "", + "key": "[CLY]_view", + "segmentation": { + "name": "Home", + "segment": "" + }, + "timestamp": "" + }, + { + "count": 1, + "dow": "", + "hour": "", + "key": "[CLY]_view", + "segmentation": { + "name": "Settings", + "segment": "", + "visit": 1 + }, + "timestamp": "" + }, + { + "count": 1, + "dow": "", + "dur": "", + "hour": "", + "key": "[CLY]_view", + "segmentation": { + "name": "Settings", + "segment": "" + }, + "timestamp": "" + } + ], + "hour": "", + "sdk_name": "javascript_native_nodejs", + "sdk_version": "", + "t": "0", + "timestamp": "", + "tz": "" + } + } +] diff --git a/package.json b/package.json index d584fea..f6b9ba3 100644 --- a/package.json +++ b/package.json @@ -20,7 +20,8 @@ "docs": "node_modules/.bin/jsdoc lib/countly.js lib/countly-bulk.js lib/countly-bulk-user.js README.md -c jsdoc_conf.json -d docs", "pretest": "eslint --ignore-path .eslintignore .", "test": "mocha --timeout 180000 test/tests_*.js --exit --allow-uncaught", - "coverage": "nyc --reporter=text --reporter=lcov npm test" + "coverage": "nyc --reporter=text --reporter=lcov npm test", + "requests:update": "node test/helpers/request_scenarios.js" }, "repository": { "type": "git", diff --git a/test/helpers/request_scenarios.js b/test/helpers/request_scenarios.js new file mode 100644 index 0000000..37d7509 --- /dev/null +++ b/test/helpers/request_scenarios.js @@ -0,0 +1,295 @@ +// The request scenarios of the SDK: each makes the calls the other Countly SDKs make in their own request tests and +// collects the requests the SDK sends, with the values that change from run to run masked. api/requests/ keeps the +// result of each scenario, tests_requests.js fails when the SDK no longer sends those requests, and +// npm run requests:update writes the records again. +const fs = require("fs"); +const path = require("path"); +const Countly = require("../../lib/countly"); +const CountlyStorage = require("../../lib/countly-storage"); +const hp = require("./helper_functions"); +const { startMockServer } = require("./mock_server"); + +const MASK = ""; +const MASKED_PARAMS = ["timestamp", "hour", "dow", "tz", "sdk_version", "av", "rr", "checksum", "checksum256", "session_duration"]; +const JSON_PARAMS = ["events", "metrics", "user_details", "crash", "consent", "hc"]; +const MASKED_EVENT_FIELDS = ["timestamp", "hour", "dow", "id", "pvid", "cvid", "peid"]; +const MASKED_CRASH_FIELDS = ["_error", "_run", "_os", "_os_version"]; +// a view's "segment" is the operating system the SDK runs on +const MASKED_VIEW_SEGMENTS = ["segment"]; +const MAX_INT = 2147483647; +const RECORDS = path.resolve(__dirname, "../../api/requests"); +const SEQUENCE_HEADER = "x-scenario-sequence"; + +/** + * The scenarios by name: the init config each adds to the common one, and the calls it makes. A scenario that awaits + * settle lets the SDK send everything the calls before it queued, so that what they sent stays apart from what follows. + */ +const SCENARIOS = { + parity: { + config: {}, + run: () => { + Countly.begin_session(); + Countly.add_event({ + key: "purchase", + count: 2, + sum: 9.99, + dur: 5, + segmentation: { + nar: "uto", + sasuke: MAX_INT, + sakura: false, + itachi: Number.MAX_VALUE, + kakaski: Number.MIN_VALUE, + hashirama: -MAX_INT, + tobi: { obito: "uchiha", zetsu: "white" }, + stringList: ["value1", "value2", "value3"], + intList: [1, 2, 3], + doubleList: [1.1, 2.2, 3.3], + boolList: [true, false, true], + mixedList: ["value1", 2, 3.3, true], + mapList: [{ key1: "value1", key2: 2 }, { key1: "value2", key2: 3 }, { key1: "value3", key2: 4 }], + }, + }); + Countly.user_details({ + name: "John Doe", + username: "john_d", + email: "john@example.com", + organization: "Countly", + phone: "1234567890", + picture: "https://example.com/picture.jpg", + gender: "M", + byear: 1980, + custom: { tier: "gold", age: 30 }, + }); + Countly.session_duration(60); + Countly.end_session(); + }, + }, + views: { + config: {}, + run: () => { + Countly.begin_session(); + Countly.track_view("Home", { source: "scenario" }); + Countly.track_view("Settings"); + Countly.end_session(); + }, + }, + crash: { + config: {}, + run: () => { + Countly.add_log("breadcrumb one"); + Countly.log_error(new Error("parity crash"), { tier: "gold" }); + }, + }, + consent: { + config: { require_consent: true }, + run: async(settle) => { + Countly.add_consent(["sessions", "events"]); + Countly.begin_session(); + Countly.add_event({ key: "consented" }); + await settle(); + Countly.remove_consent("events"); + Countly.add_event({ key: "not_consented" }); + Countly.end_session(); + }, + }, + "device-id": { + config: {}, + run: async(settle) => { + Countly.begin_session(); + Countly.change_id("parity-device-002", true); + Countly.add_event({ key: "after_merge" }); + await settle(); + Countly.change_id("parity-device-003", false); + Countly.add_event({ key: "after_new_id" }); + Countly.end_session(); + }, + }, +}; + +/** + * A copy of a JSON value with the keys of every object sorted, so that the order the SDK writes them in does not count + * @param {*} value - parsed JSON + * @returns {*} the sorted copy + */ +function sorted(value) { + if (Array.isArray(value)) { + return value.map(sorted); + } + if (value && typeof value === "object") { + return Object.keys(value).sort().reduce((copy, key) => { + copy[key] = sorted(value[key]); + return copy; + }, {}); + } + return value; +} + +/** + * A copy of an object with the values of the given keys masked + * @param {Object} value - object + * @param {string[]} keys - keys to mask + * @returns {Object} the masked copy + */ +function masked(value, keys) { + return Object.keys(value).reduce((copy, key) => { + copy[key] = keys.indexOf(key) === -1 ? value[key] : MASK; + return copy; + }, {}); +} + +/** + * The value of a JSON parameter with the values that change from run to run masked + * @param {string} name - parameter name + * @param {*} value - parsed parameter value + * @returns {*} the masked value + */ +function maskedJson(name, value) { + if ((name === "metrics" || name === "hc") && value && typeof value === "object") { + return masked(value, Object.keys(value)); + } + if (name === "events" && Array.isArray(value)) { + return value.map((event) => { + if (event.key !== "[CLY]_view") { + return masked(event, MASKED_EVENT_FIELDS); + } + const view = masked(event, MASKED_EVENT_FIELDS.concat("dur")); + if (view.segmentation && typeof view.segmentation === "object") { + view.segmentation = masked(view.segmentation, MASKED_VIEW_SEGMENTS); + } + return view; + }); + } + if (name === "crash" && value && typeof value === "object") { + return masked(value, MASKED_CRASH_FIELDS); + } + return value; +} + +/** + * A request as the scenario files record it: the path and the parameters, with the values that change from run to run + * masked and the JSON parameters parsed + * @param {Object} entry - request recorded by the mock server + * @returns {Object} path and params + */ +function recordedRequest(entry) { + const recorded = {}; + Object.keys(entry.params).forEach((name) => { + let value = entry.params[name]; + if (MASKED_PARAMS.indexOf(name) !== -1) { + value = MASK; + } + else if (JSON_PARAMS.indexOf(name) !== -1) { + value = maskedJson(name, JSON.parse(value)); + } + recorded[name] = value; + }); + return { path: entry.path, params: sorted(recorded) }; +} + +/** + * Waits until the SDK has sent everything it queued: both queues are empty and no request came for longer than the + * SDK's own delays, such as the one second it waits before sending a consent change + * @param {Object} server - the mock server the SDK sends to + * @returns {Promise} resolves when the SDK is idle, rejects after 15 seconds + */ +function idle(server) { + return new Promise((resolve, reject) => { + const started = Date.now(); + let count = -1; + let quietSince = started; + const check = () => { + const queued = CountlyStorage.storeGet("cly_queue", []).length + CountlyStorage.storeGet("cly_event", []).length; + if (queued || server.requests.length !== count) { + count = server.requests.length; + quietSince = Date.now(); + } + else if (Date.now() - quietSince > 1500) { + resolve(); + return; + } + if (Date.now() - started > 15000) { + reject(new Error("the SDK still had requests to send after 15 seconds")); + return; + } + setTimeout(check, 50); + }; + check(); + }); +} + +/** + * Runs a scenario on an SDK that is not initialized and gives back the requests it sent, in the order the SDK started + * them, halting the SDK afterwards + * @param {string} name - scenario name, a key of SCENARIOS + * @returns {Promise} the requests, as recordedRequest gives them + */ +async function scenarioRequests(name) { + const scenario = SCENARIOS[name]; + const server = await startMockServer(); + let sequence = 0; + try { + // halt(true), which clearing the storage calls, also stops the SDK from sending + Countly.halt(false); + Countly.init({ + app_key: "parity-app-key", + url: server.url, + device_id: "parity-device-001", + interval: 50, + // requests that are on their way at the same time can arrive in either order, so each carries its number + http_options: (options) => { + sequence += 1; + options.headers[SEQUENCE_HEADER] = String(sequence); + }, + ...scenario.config, + }); + // the health check goes out once the behavior settings arrive, and the scenario's first request must not pass it + await server.waitFor((requests) => requests.some((entry) => entry.params.hc), 5000); + await scenario.run(() => idle(server)); + await idle(server); + } + finally { + Countly.halt(true); + await server.close(); + } + return server.requests + .slice() + .sort((a, b) => Number(a.headers[SEQUENCE_HEADER]) - Number(b.headers[SEQUENCE_HEADER])) + .map(recordedRequest); +} + +/** + * The content of api/requests/.json for the requests of a scenario + * @param {Object[]} requests - the requests, as scenarioRequests gives them + * @returns {string} file content + */ +function requestsReport(requests) { + return `${JSON.stringify(requests, null, 2)}\n`; +} + +/** + * Runs every scenario and writes its record to api/requests/ + * @returns {Promise} resolves when every record is written + */ +async function updateRecords() { + fs.mkdirSync(RECORDS, { recursive: true }); + for (const name of Object.keys(SCENARIOS)) { + // the scenarios share the SDK, so they run one after another + // eslint-disable-next-line no-await-in-loop + await hp.clearStorage(); + // eslint-disable-next-line no-await-in-loop + const report = requestsReport(await scenarioRequests(name)); + fs.writeFileSync(path.join(RECORDS, `${name}.json`), report); + process.stdout.write(`api/requests/${name}.json\n`); + } + await hp.clearStorage(); +} + +if (require.main === module) { + updateRecords().catch((error) => { + process.stderr.write(`${error.stack}\n`); + process.exit(1); + }); +} + +module.exports = { SCENARIOS, RECORDS, scenarioRequests, requestsReport }; diff --git a/test/tests_requests.js b/test/tests_requests.js new file mode 100644 index 0000000..40d1bd0 --- /dev/null +++ b/test/tests_requests.js @@ -0,0 +1,25 @@ +// In each request scenario the SDK sends the requests api/requests/.json records, with the values that change +// from run to run masked. A deliberate change is recorded with npm run requests:update and needs a CHANGELOG.md line. +const assert = require("assert"); +const fs = require("fs"); +const path = require("path"); +const hp = require("./helpers/helper_functions"); +const { SCENARIOS, RECORDS, requestsReport, scenarioRequests } = require("./helpers/request_scenarios"); + +describe("Request records", () => { + beforeEach(async() => { + await hp.clearStorage(); + }); + afterEach(async() => { + await hp.clearStorage(); + }); + + Object.keys(SCENARIOS).forEach((name) => { + it(`sends the requests api/requests/${name}.json records in the ${name} scenario`, async() => { + const file = path.join(RECORDS, `${name}.json`); + const current = requestsReport(await scenarioRequests(name)); + const committed = fs.existsSync(file) ? fs.readFileSync(file, "utf8").replace(/\r\n/g, "\n") : ""; + assert.strictEqual(current, committed, `The requests of the ${name} scenario differ from api/requests/${name}.json. If that is deliberate, run npm run requests:update, check the difference and add a CHANGELOG.md line.`); + }); + }); +});